|
|
|
|
.. _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]"
|
|
|
|
|
|
conf-yaml: support glob patterns in include directive
SCConfYamlHandleInclude only accepted explicit filenames. The
rule-files directive has supported shell-style glob expansion via
glob(3) for years, and asymmetry with include has been blocking
clean drop-in conf.d/ style configuration directories.
Refactor SCConfYamlHandleInclude into a thin wrapper that resolves
the path against conf_dirname and, if the input contains glob
metacharacters (*, ?, [), expands it with glob(3) and includes
each match in lexicographic order. A pattern that matches no
files is logged as a warning and not treated as an error, so a
drop-in directory can be empty without breaking startup. Literal
paths skip glob() and call the existing per-file inclusion logic
directly, preserving current behaviour.
Glob expansion needs glob(3), which is not available everywhere.
Windows builds have no glob.h, so an include pattern used to fall
through and be opened as a literal filename, failing with a
confusing errno. On such platforms the pattern is now logged as a
warning and skipped instead. Literal includes are unaffected.
The behaviour is verified by the config-includes-glob-order
suricata-verify test, which checks that every file matching a
pattern is loaded and that matches are included in deterministic
lexicographic order.
Document the new behaviour, including the platform limitation, in
doc/userguide/configuration/includes.rst.
Feature: #8427.
3 months ago
|
|
|
Glob Patterns
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
Filenames in ``include`` may contain shell-style glob metacharacters
|
|
|
|
|
(``*``, ``?``, ``[...]``). Patterns are expanded at startup via
|
|
|
|
|
``glob(3)`` and each matching file is loaded in lexicographic order. A
|
|
|
|
|
pattern that matches no files is logged as a warning and is not treated
|
|
|
|
|
as an error, which allows drop-in ``conf.d/``-style directories to be
|
|
|
|
|
empty.
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
|
|
include:
|
|
|
|
|
- /etc/suricata/conf.d/*.yaml
|
|
|
|
|
|
|
|
|
|
Relative patterns are resolved against the directory of the top-level
|
|
|
|
|
configuration file, the same as literal includes.
|
|
|
|
|
|
|
|
|
|
.. note:: Glob expansion requires ``glob(3)``, which is not available on
|
|
|
|
|
all platforms. On platforms without it, notably Windows, an
|
|
|
|
|
``include`` containing glob metacharacters is skipped with a warning
|
|
|
|
|
and no files are loaded from it. Literal filenames are unaffected.
|
|
|
|
|
|
|
|
|
|
.. 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.
|
