doc/reload: Expand rule-reload discussion

Clarify the resources involved in a rule reload.

Issue: 5078

doc/userguide/rule-management/rule-reload.rst

@@ -1,32 +1,94 @@
 Rule Reloads
 ============
 
-Suricata can reload the rules without restarting. This way, there
+Suricata was designed to reload rules while it is actively processing
-is minimal service disruption.
+network traffic to minimize service disruption.
 
-This works by sending Suricata a signal or by using the unix socket. When Suricata is told to reload the rules these are the basic steps it takes:
+Suricata must be administratively directed to reload rules while it is running.
 
-* Load new config to update rule variables and values.
+It is also possible to get information about the last reload via dedicated commands.
-* Load new rules
+See :ref:`standard-unix-socket-commands` for more information.
-* Construct new detection engine
-* Swap old and new detection engines
-* Make sure all threads are updated
-* Free old detection engine
 
-Suricata will continue to process packets normally during this process. Keep in mind though, that the system should have enough memory for both detection engines.
+Reload Triggers
+~~~~~~~~~~~~~~~
+There are multiple ways to trigger a rule reload. ``suricatasc`` is a program distributed with Suricata
+that provides client-side services, including the ability to trigger a Suricata rule reload..
 
-Signal::
+Via process signal
+------------------
 
-  kill -USR2 $(pidof suricata)
+The ``USR2`` signal will cause Suricata to start a rule reload. The signal can be sent from the command
+line or from a script/program. Escalation of privileges may be necessary to send the signal.
 
-There are two methods available when using the Unix socket.
+  $ kill -USR2 $(pidof suricata)
 
-Blocking reload ::
+Via the UNIX domain socket
+--------------------------
+
+The ``suricatasc`` program has two commands to initiate a Suricata rule reload.
+
+Blocking reload
+^^^^^^^^^^^^^^^
+
+This will cause Suricata to reload rules while the caller blocks, or waits.
 
   suricatasc -c reload-rules
 
-Non blocking reload ::
+Non-blocking reload
+^^^^^^^^^^^^^^^^^^^
+
+This will cause Suricata to reload rules without the caller blocking or waiting.
 
   suricatasc -c ruleset-reload-nonblocking
 
-It is also possible to get information about the last reload via dedicated commands. See :ref:`standard-unix-socket-commands` for more information.
+Resources Reloaded
+~~~~~~~~~~~~~~~~~~
+
+There are two types of resources that are reloaded during a rule reload.
+
+* Rule-related configuration:
+
+  * Suricata's configuration file(s): ``suricata.yaml`` and any specified with the command-line
+    options ``--include <config-file.yaml>``. Only rule-related information is reloaded.
+
+    * Rule variables: items in the ``vars`` section.
+    * Rule files from the ``rule-files`` section (if the ``-S`` command line option was not used)
+
+  * Ancillary rule-related configuration files: ``classification.config``, ``reference.config``
+    and ``threshold.config``
+
+  * Dataset(s) used by rules.
+
+  * When multi-tenants are configured, rule-related configuration information for each tenant.
+
+When to reload rules
+~~~~~~~~~~~~~~~~~~~~
+
+Rule reloads are used in situations when:
+
+* Rules have been changed since the last reload. Vendors often add rules frequently and
+  sometimes update existing rules. Rules should be reloaded according to a security policy
+  that includes Suricata rule and configuration settings.
+* Rule variables have been changed. Rule reloads will use rule variables from the Suricata
+  configuration file. When updating these, reload the rules in order for the updated rule
+  variables to take effect.
+* Ancillary rule-related configuration files are updated.
+
+Advanced: Rule Reload Steps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When reloading rules, Suricata executes the following steps to ensure a safe
+and consistent update:
+
+* The main Suricata configuration is reloaded to update rule variables and values,
+  including the rule related files ``classification.config``, ``reference.config`` and
+  ``theshold.config``.
+* All rule files are reloaded with new rule variables applied.
+* A new detection engine is created for the updated rules.
+* The previous and newly created detection engines are swapped.
+* Ensure all threads are updated.
+* Free old detection engine and associated resources.
+
+Suricata will continue to process packets during the update process. Note that additional system
+memory is used during the reload process as a new detection engine and the reloaded rules are
+associated with it.