From 07b7f367488e28496f719d2a711e710418a01f8c Mon Sep 17 00:00:00 2001 From: Jeff Lucovsky Date: Sun, 22 Jun 2025 19:39:13 +0000 Subject: [PATCH] doc/reload: Expand rule-reload discussion Clarify the resources involved in a rule reload. Issue: 5078 --- doc/userguide/rule-management/rule-reload.rst | 94 +++++++++++++++---- 1 file changed, 78 insertions(+), 16 deletions(-) diff --git a/doc/userguide/rule-management/rule-reload.rst b/doc/userguide/rule-management/rule-reload.rst index 5c29232d6e..5da25c7b46 100644 --- a/doc/userguide/rule-management/rule-reload.rst +++ b/doc/userguide/rule-management/rule-reload.rst @@ -1,32 +1,94 @@ Rule Reloads ============ -Suricata can reload the rules without restarting. This way, there -is minimal service disruption. +Suricata was designed to reload rules while it is actively processing +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. -* Load new rules -* Construct new detection engine -* Swap old and new detection engines -* Make sure all threads are updated -* Free old detection engine +It is also possible to get information about the last reload via dedicated commands. +See :ref:`standard-unix-socket-commands` for more information. -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 ``. 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. -- 2.39.5