From: Lukas Sismis Date: Sun, 27 Apr 2025 13:04:29 +0000 (+0200) Subject: pcap-file: document capture method options X-Git-Tag: suricata-7.0.11~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=fce8336c9325208f5bd0dfd446f881b81db20751;p=thirdparty%2Fsuricata.git pcap-file: document capture method options (cherry picked from commit eb52e337da3a7d123a76a1a17f54337a5c76d88d) --- diff --git a/doc/userguide/capture-hardware/index.rst b/doc/userguide/capture-hardware/index.rst index 992bd07f61..f7e377a8c5 100644 --- a/doc/userguide/capture-hardware/index.rst +++ b/doc/userguide/capture-hardware/index.rst @@ -10,3 +10,4 @@ Using Capture Hardware netmap af-xdp dpdk + pcap-file diff --git a/doc/userguide/capture-hardware/pcap-file.rst b/doc/userguide/capture-hardware/pcap-file.rst new file mode 100644 index 0000000000..e12acfcc45 --- /dev/null +++ b/doc/userguide/capture-hardware/pcap-file.rst @@ -0,0 +1,86 @@ +.. _pcap_file: + +PCAP File Reading +================= + +Suricata offers a ``pcap-file`` capture method to process PCAP files and +directories of PCAP files in an offline or live-feed manner. + +Configuration +------------- + +.. code-block:: yaml + + pcap-file: + checksum-checks: auto + # tenant-id: none + # delete-when-done: false + # recursive: false + # continuous: false + # delay: 30 + # poll-interval: 5 + +Directory-related options +------------------------- + +The **recursive** option enables Suricata to traverse subdirectories within +the specified directory, up to a maximum depth of 255. This allows for +processing of PCAP files located in nested folders. Note that the recursive +option cannot be used together with the ``continuous`` option. +The command-line option is +:ref:`--pcap-file-recursive `. + +The **continuous** option allows Suricata to monitor the specified directory +for new files, processing them as they appear. +This is useful for live environments where new PCAP files are continuously +added. The continuous option cannot be combined with the ``recursive`` option. +The command-line option is +:ref:`--pcap-file-continuous `.. + +The **delay** option specifies the amount of time, in seconds, +that Suricata waits before processing newly detected files. +This helps prevent the processing of incomplete files that are still +being written. The delay option is applicable with +the ``continuous`` mode. + +The **poll-interval** option determines how frequently, in seconds, +Suricata checks the directory for new files. Adjusting this interval +can help balance responsiveness and resource usage. + +.. note:: + + ``continuous`` and ``recursive`` cannot be enabled simultaneously. + +.. note:: + + Symlinks are ignored during recursive traversal. + + +Other options +------------- + +**checksum-checks** + +- **auto** (default): Suricata detects checksum offloading statistically. +- **yes**: Forces checksum validation. +- **no**: Disables checksum validation. +- The command-line option is :ref:`-k ` + +**tenant-id** + +- Specifies the tenant for multi-tenant setups with direct select. +- The PCAP is processed by the detection engine assigned to the specified + tenant. + +**delete-when-done** + +- If ``true``, Suricata deletes the PCAP file after processing. +- The command-line option is + :ref:`--pcap-file-delete ` + +**BPF filter** + +- Suricata supports BPF filters for packet capture that is also applicable + to the ``pcap-file`` capture method. +- The BPF filter is specified in the file with the :ref:`-F ` + command-line option. diff --git a/doc/userguide/partials/options.rst b/doc/userguide/partials/options.rst index 34f8f6a1bb..c14302e257 100644 --- a/doc/userguide/partials/options.rst +++ b/doc/userguide/partials/options.rst @@ -51,18 +51,24 @@ .. Basic input options. +.. _cmdline-option-r: + .. option:: -r Run in pcap offline mode (replay mode) reading files from pcap file. If specifies a directory, all files in that directory will be processed in order of modified time maintaining flow state between files. +.. _cmdline-option-pcap-file-continuous: + .. option:: --pcap-file-continuous Used with the -r option to indicate that the mode should stay alive until interrupted. This is useful with directories to add new files and not reset flow state between files. +.. _cmdline-option-pcap-file-recursive: + .. option:: --pcap-file-recursive Used with the -r option when the path provided is a directory. This option @@ -70,6 +76,8 @@ This option cannot be combined with --pcap-file-continuous. Symlinks are ignored. +.. _cmdline-option-pcap-file-delete: + .. option:: --pcap-file-delete Used with the -r option to indicate that the mode should delete pcap files @@ -153,10 +161,14 @@ For more information about runmodes see :doc:`Runmodes ` in the user guide. +.. _cmdline-option-F: + .. option:: -F Use BPF filter from file. +.. _cmdline-option-k: + .. option:: -k [all|none] Force (all) the checksum check or disable (none) all checksum diff --git a/suricata.yaml.in b/suricata.yaml.in index 722f17a0b1..bcf861ae53 100644 --- a/suricata.yaml.in +++ b/suricata.yaml.in @@ -855,6 +855,14 @@ pcap-file: # checksum off-loading is used. (default) # Warning: 'checksum-validation' must be set to yes to have checksum tested checksum-checks: auto + # tenant-id: none # applies in multi-tenant environment with "direct" selector + # delete-when-done: false # applies to file and directory + + # PCAP Directory Processing options + # recursive: false + # continuous: false + # delay: 30 # seconds to wait before processing the newly added PCAPs + # poll-interval: 5 # how often to check the directory # See "Advanced Capture Options" below for more options, including Netmap # and PF_RING.