From f5271e301403a6532b67b72a6092071ddc2df65f Mon Sep 17 00:00:00 2001 From: Ad Schellevis Date: Mon, 16 Oct 2023 16:27:09 +0200 Subject: [PATCH] Development/Backup - add Overview page explaining hooks and their order. closes https://github.com/opnsense/docs/issues/505 --- source/development/backend.rst | 1 + source/development/backend/legacy.rst | 10 ++++- source/development/backend/overview.rst | 53 +++++++++++++++++++++++++ 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 source/development/backend/overview.rst diff --git a/source/development/backend.rst b/source/development/backend.rst index 994d027e..77691e18 100644 --- a/source/development/backend.rst +++ b/source/development/backend.rst @@ -24,4 +24,5 @@ Services which need to be executed at system startup can use rc(8) or our syshoo :titlesonly: :glob: + backend/overview backend/* diff --git a/source/development/backend/legacy.rst b/source/development/backend/legacy.rst index 3098e534..244004fa 100644 --- a/source/development/backend/legacy.rst +++ b/source/development/backend/legacy.rst @@ -1,12 +1,12 @@ ============================ -Using (legacy) plugins +Using plugins ============================ ------- General ------- -Legacy type plugins are located in the following location: +Plugins are located in the following location: :: @@ -21,6 +21,12 @@ With the use of these plugins, you have the ability to hook into different areas new interface types and making sure services are shown in the regular service overview. +.. Note:: + + When plugins fail and cause PHP errors, these will be collected in :code:`/tmp/PHP_errors.log`, these plugins are not + registered and executed when emitting such errors + + ----------------- Services ----------------- diff --git a/source/development/backend/overview.rst b/source/development/backend/overview.rst new file mode 100644 index 00000000..d7aa02d2 --- /dev/null +++ b/source/development/backend/overview.rst @@ -0,0 +1,53 @@ +======================== +Overview +======================== + +The life of a service starts during the boot process, but with different hooks available, sometimes it is challenging +to find the correct one. This paragraph aims to explain the various integration spots availabe, which are +being explained in more detail in the rest of the chapter. + + +.................................... +Bootup +.................................... + +After the kernel is loaded and the machine starts to boot, the following integration points are being executed +in sequence: + +1. :doc:`syshook/early `, simple shell scripts to run before any network services are loaded, + can for example be used to load specific drivers. +2. :doc:`plugins/device `, register and create devices, services like OpenVPN use this on + our end to make sure :code:`tun` and :code:`tap` devices exist before doing further configuration. +3. :doc:`plugins/configure/early `, configure :code:`early` event in bootup process, before normal services are being started (things like ssh and the webconfigurator use this spot) +4. :doc:`plugins/firewall ` allows for automatic firewall (nat) rule registration in cases where the service is able to ship its own rules. (some do this optionally for easy setup) +5. :doc:`plugins/configure/monitor `, configure :code:`monitor` event, with the network stack ready, signal the monitor (dpinger) for startup +6. :doc:`plugins/configure/vpn `, configure :code:`vpn` event, vpn type services are being configured here (e.g. IPsec, OpenVPN) +7. :doc:`plugins/configure/bootup `, configure :code:`bootup` event, normal legacy service configuration, when not using the rc(8) system (for example: unbound, ntpd) +8. :doc:`syshook/start `, simple shell scripts to run after all networking has been setup. +9. :doc:`rc(8) `, regular `rc(8)` scripts (executed using the above :code:`the rc.syshook.d/start``) + + +.. Tip:: + + Use :code:`pluginctl -c` to display available events and the plugins attached to them. + + +.................................... +Normal operation +.................................... + +Now the system is booted and events may take place, some of the common integration points with their purpose are listed below: + +* :doc:`syshook/carp `, when a high-availability node changes roles from/to master or backup, these scripts + are being executed. This offers the ability to prevent client services from connecting when in the wrong mode. +* :doc:`plugins/configure/newwanip ` will be triggered after an interface retrieves a new address. +* :doc:`plugins/interface ` handles dynamic registration of new (virtual) interfaces. +* :doc:`plugins/syslog ` registers syslog facilities +* :doc:`plugins/xmlrpc ` registers configuration synchronisation points. + +.................................... +Shutdown (reboot) +.................................... + +When the system is shutdown or being rebooted, we can hook actions using the :doc:`syshook/stop ` +script directory. Services like the backup hook into this to flush contents before being terminated.