Development/Backup - add Overview page explaining hooks and their order. closes https://github.com/opnsense/docs/issues/505

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/*

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
 -----------------

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 </development/backend/autorun>`, simple shell scripts to run before any network services are loaded,
+    can for example be used to load specific drivers.
+2.  :doc:`plugins/device </development/backend/legacy>`, 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 </development/backend/legacy>`, 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 </development/backend/legacy>` 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 </development/backend/legacy>`, configure :code:`monitor` event, with the network stack ready, signal the monitor (dpinger) for startup
+6.  :doc:`plugins/configure/vpn </development/backend/legacy>`, configure :code:`vpn` event, vpn type services are being configured here (e.g. IPsec, OpenVPN)
+7.  :doc:`plugins/configure/bootup </development/backend/legacy>`, configure :code:`bootup` event, normal legacy service configuration, when not using the rc(8) system (for example: unbound, ntpd)
+8.  :doc:`syshook/start </development/backend/autorun>`, simple shell scripts to run after all networking has been setup.
+9.  :doc:`rc(8) </development/backend/autorun>`, 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 </development/backend/autorun>`, 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 </development/backend/legacy>` will be triggered after an interface retrieves a new address.
+*   :doc:`plugins/interface </development/backend/legacy>`  handles dynamic registration of new (virtual) interfaces.
+*   :doc:`plugins/syslog </development/backend/legacy>` registers syslog facilities
+*   :doc:`plugins/xmlrpc </development/backend/legacy>` registers configuration synchronisation points.
+
+....................................
+Shutdown (reboot)
+....................................
+
+When the system is shutdown or being rebooted, we can hook actions using the  :doc:`syshook/stop </development/backend/autorun>`
+script directory. Services like the backup hook into this to flush contents before being terminated.