pcap-file: document capture method options

doc/userguide/capture-hardware/index.rst

@@ -10,3 +10,4 @@ Using Capture Hardware
    netmap
    af-xdp
    dpdk
+   pcap-file

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 <cmdline-option-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 <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.

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
@@ -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 <value>
 
    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
    </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

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.