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..f87d259b74 --- /dev/null +++ b/doc/userguide/capture-hardware/pcap-file.rst @@ -0,0 +1,97 @@ +.. _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 + # buffer-size: 128 KiB + # tenant-id: none + # delete-when-done: false + # recursive: false + # continuous: false + # delay: 30 + # poll-interval: 5 + + +Buffer Size +----------- + +This option specifies the size of the read buffer for the PCAP file. +The larger the buffer, the more data Suricata can read at once. +This can improve performance, especially for large files. +The size can be specified through the command line option, see +:ref:`--pcap-file-buffer-size ` + +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 91f8241854..170677bff2 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 @@ -77,6 +85,8 @@ continuously feed files to a directory and have them cleaned up when done. If this option is not set, pcap files will not be deleted after processing. +.. _cmdline-option-pcap-file-buffer-size: + .. option:: --pcap-file-buffer-size Set read buffer size using ``setvbuf`` to speed up pcap reading. Valid values @@ -158,10 +168,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 13535197fd..32d733e7d9 100644 --- a/suricata.yaml.in +++ b/suricata.yaml.in @@ -887,7 +887,16 @@ pcap-file: # Warning: 'checksum-validation' must be set to yes to have checksum tested checksum-checks: auto # Read buffer size set using setvbuf. Max value is 64 MiB. Linux only. - #buffer-size: 128 KiB + # buffer-size: 128 KiB + + # 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.