config: document includes

doc/userguide/configuration/includes.rst

@@ -0,0 +1,56 @@
+.. _includes:
+
+Includes
+========
+
+A Suricata configuration file (typically
+``/etc/suricata/suricata.yaml``) may include other files allowing a
+configuration file to be broken into multiple files. The *special*
+field name ``include`` is used to include one or more files.
+
+The contents of the *include* file are inlined at the level of the
+``include`` statement. *Include* fields may also be included at any
+level within a mapping.
+
+Including a Single File
+-----------------------
+
+::
+
+    include: filename.yaml
+
+Including Multiple Files
+------------------------
+
+::
+
+    include:
+      - filename1.yaml
+      - filename2.yaml
+
+Include Inside a Mapping
+------------------------
+
+::
+
+    vars:
+      address-groups:
+        include: address-groups.yaml
+
+where ``address-groups.yaml`` contains::
+
+    %YAML 1.1
+    ---
+    HOME_NET: "[192.168.0.0/16,10.0.0.0/8,172.16.0.0/12]"
+
+is the equivalent of::
+
+    vars:
+      address-groups:
+        HOME_NET: "[192.168.0.0/16,10.0.0.0/8,172.16.0.0/12]"
+
+.. note:: Suricata versions less than 7 required multiple ``include``
+    statements to be specified to include more than one file. While
+    Suricata 7.0 still supports this it will issue a deprecation
+    warning. Suricata 8.0 will not allow multiple ``include``
+    statements at the same level as this is not allowed by YAML.

doc/userguide/configuration/index.rst

@@ -11,3 +11,4 @@ Configuration
    dropping-privileges
    landlock
    systemd-notify
+   includes

doc/userguide/upgrade.rst

@@ -57,6 +57,15 @@ Logging changes
   ``ike.ikev2.errors`` and ``ike.ikev2.notify``.
 - FTP DATA metadata for alerts are now logged in ``ftp_data`` instead of root.
 - Alert ``xff`` field is now logged as ``alert.xff`` for alerts instead of at the root.
+- Protocol values and their names are built into Suricata instead of using the system's ``/etc/protocols`` file. Some names and casing may have changed
+  in the values ``proto`` in ``eve.json`` log entries and other logs containing protocol names and values.
+  See https://redmine.openinfosecfoundation.org/issues/4267 for more information.
+
+Deprecations
+~~~~~~~~~~~~
+- Multiple "include" fields in the configuration file will now issue a
+  warning and in Suricata 8.0 will not be supported. See
+  :ref:`includes` for documentation on including multiple files.
 
 Other changes
 ~~~~~~~~~~~~~
@@ -66,12 +75,6 @@ Other changes
 - SWF decompression in http has been disabled by default. To change the default see :ref:`suricata-yaml-configure-libhtp`. Users with configurations from previous releases may want to modify their config to match the new default.
   See https://redmine.openinfosecfoundation.org/issues/5632 for more information.
 
-Logging changes
-~~~~~~~~~~~~~~~
-- Protocol values and their names are built into Suricata instead of using the system's ``/etc/protocols`` file. Some names and casing may have changed
-  in the values ``proto`` in ``eve.json`` log entries and other logs containing protocol names and values.
-  See https://redmine.openinfosecfoundation.org/issues/4267 for more information.
-
 Upgrading 5.0 to 6.0
 --------------------
 - SIP now enabled by default

suricata.yaml.in

@@ -2133,6 +2133,6 @@ reference-config-file: @e_sysconfdir@reference.config
 # in this configuration file. Files with relative pathnames will be
 # searched for in the same directory as this configuration file. You may
 # use absolute pathnames too.
-# You can specify more than 2 configuration files, if needed.
-#include: include1.yaml
-#include: include2.yaml
+#include:
+#  - include1.yaml
+#  - include2.yaml