From 5af73b387954914842f085e2af475a5ca8d4ef52 Mon Sep 17 00:00:00 2001 From: Jason Ish Date: Wed, 24 May 2023 13:18:21 -0600 Subject: [PATCH] doc/userguide: document include files Document how to use include files, plus add a deprecation notice on the use of multiple "include" statements. --- doc/userguide/configuration/includes.rst | 56 ++++++++++++++++++++++++ doc/userguide/configuration/index.rst | 1 + doc/userguide/upgrade.rst | 6 +++ 3 files changed, 63 insertions(+) create mode 100644 doc/userguide/configuration/includes.rst diff --git a/doc/userguide/configuration/includes.rst b/doc/userguide/configuration/includes.rst new file mode 100644 index 0000000000..2fc62908aa --- /dev/null +++ b/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. diff --git a/doc/userguide/configuration/index.rst b/doc/userguide/configuration/index.rst index a32a83bf6e..8a90cec474 100644 --- a/doc/userguide/configuration/index.rst +++ b/doc/userguide/configuration/index.rst @@ -11,3 +11,4 @@ Configuration dropping-privileges landlock systemd-notify + includes diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst index 9cd66b2ab1..0dd7223dfc 100644 --- a/doc/userguide/upgrade.rst +++ b/doc/userguide/upgrade.rst @@ -61,6 +61,12 @@ Logging changes 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 ~~~~~~~~~~~~~ - NSS is no longer required. File hashing and JA3 can now be used without the NSS compile time dependency.