doc/systemd: add documentation for sd_notify

diff --git a/doc/userguide/configuration/index.rst b/doc/userguide/configuration/index.rst
index d4891c1132f62c24c5d5a66f41cd75cc6191e363..a32a83bf6eca17d8141e8bd0619e2ec3723081f2 100644 (file)
--- a/doc/userguide/configuration/index.rst
+++ b/doc/userguide/configuration/index.rst
@@ -10,3 +10,4 @@ Configuration
    multi-tenant
    dropping-privileges
    landlock
+   systemd-notify

diff --git a/doc/userguide/configuration/systemd-notify.rst b/doc/userguide/configuration/systemd-notify.rst
new file mode 100644 (file)
index 0000000..e9fda83
--- /dev/null
+++ b/doc/userguide/configuration/systemd-notify.rst
@@ -0,0 +1,57 @@
+systemd notification
+====================
+
+Introduction
+------------
+Suricata supports systemd notification with the aim of notifying the service manager of successful
+initialisation. The purpose is to enable the ability to start upon/await successful start-up for
+services/test frameworks that depend on a fully initialised Suricata .
+
+During the initialisation phase Suricata synchronises the initialisation thread with all active
+threads to ensure they are in a running state. Once synchronisation has been completed a ``READY=1``
+status notification is sent to the service manager using ``sd_notify()``.
+
+Example
+-------
+A test framework requires Suricata to be capturing before the tests can be carried out.
+Writing a ``test.service`` and ensuring the correct execution order with ``After=suricata.service``
+forces the unit to be started after ``suricata.service``. This does not enforce Suricata has fully
+initialised. By configuring ``suricata.service`` as ``Type=notify`` instructs the service manager
+to wait for the notification before starting ``test.service``.
+
+Requirements
+------------
+This feature is only supported for distributions under the following conditions:
+
+1. Distribution contains ``libsystemd``
+2. Any distribution that runs under **systemd**
+3. Unit file configuration: ``Type=notify``
+4. Contains development files for systemd shared library
+
+To install development files:
+Fedora::
+
+    dnf -y install systemd-devel
+
+Ubuntu/Debian::
+
+    apt -y install systemd-dev
+
+This package shall be compile-time configured and therefore only built with distributions fulfilling
+requirements [1, 2]. For notification to the service manager the unit file must be configured as
+shown in requirement [3]. Upon all requirements being met the service manager will start and await
+``READY=1`` status from Suricata. Otherwise the service manager will treat the service unit as
+``Type=simple`` and consider it started immediately after the main process ``ExecStart=`` has been
+forked.
+
+Additional Information
+----------------------
+To confirm the system is running under systemd::
+
+    ps --no-headers -o comm 1
+
+See: https://man7.org/linux/man-pages/man3/sd_notify.3.html for a detailed description on
+``sd_notify``.
+
+See https://www.freedesktop.org/software/systemd/man/systemd.service.html for help
+writing systemd unit files.