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 992bd07f614bfad9f46c39db23298279d6322e8e..f7e377a8c54a660ccb564ae3b4ccf44c83bed86c 100644 (file)
--- 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 (file)
index 0000000..e12acfc
--- /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 <cmdline-option-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 <cmdline-option-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 <cmdline-option-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 <cmdline-option-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 <cmdline-option-F>`
+  command-line option.

diff --git a/doc/userguide/partials/options.rst b/doc/userguide/partials/options.rst
index 34f8f6a1bbbe81576d52c132f0506aa41f226f67..c14302e257892bd58bb5deb63d6f3b2dbce0fd9c 100644 (file)
--- a/doc/userguide/partials/options.rst
+++ b/doc/userguide/partials/options.rst
@@ -51,18 +51,24 @@
 
 .. Basic input options.
 
+.. _cmdline-option-r:
+
 .. option:: -r <path>
 
    Run in pcap offline mode (replay mode) reading files from pcap file. If
    <path> 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
    </performance/runmodes>` in the user guide.
 
+.. _cmdline-option-F:
+
 .. option:: -F <bpf filter file>
 
    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 722f17a0b1e9990d0c6596c6ebd6dcc7009c4fb0..bcf861ae53913d69ea05582d1de3f967ced67f45 100644 (file)
--- 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.