Overview

The capture probe has 2 configuration file formats. The first is a JSON configuration format similar to a stack probe configuration and with the most flexibility, including support for filter modules. The second, referred to as “command line configuration” is a more limited format with support only for basic BPF.

It is important to note that you can run as many capture probes as you wish. Some example strategies might be:

A separate capture probe per Napatech stream - see VMX-Capture Capture Card Configuration.
One capture probe for TCP traffic, and one capture probe for UDP traffic (per Visibility Point).
A separate capture probe for each different market.
A separate capture probe for each different visibility point.

Running multiple capture probes supports, for example, different retention periods or snaplengths for different types of traffic.

Capture probes are usually run on a separate packet multiplexer to stack probes decoding protocols. The reason that we do this is because if something goes wrong with a stack probe’s processing, it is useful to have a separate capture probe running to capture the details of the packet which caused the issue.

JSON Configuration

The capture probe JSON configuration format uses the same module-based JSON configuration as the stack probe JSON configuration.

Capture probe JSON configuration files have the .capture.json filename suffix.

Example Capture Probe JSON Configuration File

Here’s a sample packet capture probe configuration file called capVP.capture.json:

{
  "probe": {
    "parameters": {
      "name": "capVP",
      "compression_type": "noloadgz",
      "capture_file_type": "pcapns",
      "output_directory": "/data/capture",
      "output_filename_prefix": "capVP",
      "filter": "vlan 2010",
      "file_duration_s": 10,
      "influxdb_dsn": "influxdb://vmxadmin:grafstats@localhost:8086/capture",
      "influxdb_measurement": "pcap"
    }
  }
}

Probe Parameters

Parameter	Type	Required	Default	Description
name	string	N	unnamed	Name of the probe.
filter	string	N		BPF expression for filtering packets.
filter_module	module	N		Packet filter module. See https://beeks.atlassian.net/wiki/spaces/CFD/pages/740786199/Stack+Packet+Filter+Configuration#Filter-Modules
snaplen	uint	N	65535	Maximum number of bytes written per packet.
capture_file_type	enum (`pcap`, `pcapns`)	N	pcapns	Capture file type.
compression_type	enum (`noloadgz`, `363gz`, `bzip2`, `gzip`, `lzf`, `lzop`, `null`)	Y		Compression method.
compression_level	int	N	9	Compression level. This may not be used by all compression types and valid ranges vary between compressors, but usually 0-9.
output_directory	path	Y		Path to the directory where the capture files should be written.
output_filename_prefix	string	Y		Prefix to the capture file filename. Timestamp may be appended. Suitabled suffixes for capture file type and compression type will be appended.
file_duration_s	uint	N	60	File duration in seconds.
file_size_bytes	uint64	N		If set, creates a new capture file when the capture file reaches this size, in bytes (may overrun a little). If not set, file_duration_s is used instead.
influxdb_dsn	string	N		InfluxDB DSN (of the form: influxdb://<username>:<password>@<host>:<port>/<database> . Set to additionally write capture file metadata to InfluxDB.
influxdb_measurement	string	N	pcap_stats	InfluxDB measurement to write capture file metadata to.
retention_lifetime	string	N		Retention lifetime, used by external components to manage lifetime of capture files. <number> <units> where units = hours \| days \| weeks .
retention_capacity	string	N		The maximum storage capacity that can be used by capture files from this probe, used by external components to manage lifetime of capture files. <number>% = maximum percentage of the mounted volume allocated to capture files. <number><storage units> = maximum absolute size in units of GB \| GiB \| TB \| TiB .
retention_emergency_purge	string	N		The threshold for the partition storage at which emergency purge kicks in, used by external components to manage lifetime of capture files. <number>% = maximum percentage of the mounted volume in use. <number><storage units> = maximum absolute size in units of GB \| GiB \| TB \| TiB .

Command Line Configuration

The command line configuration format is a string of key/value pairs separated by spaces. Spaces in a value must be replaced by % and if % is already in a value, it must be replaced with %%.

Capture probe command line configuration files have the .capture.config filename suffix.

Example Capture Probe Command Line Configuration File

Here’s a sample packet capture probe configuration file called capVP.capture.config:

name=capVP 
compression=noloadgz
capture_file_type=pcapns
output_dir=/data/capture
file_prefix=capVP
filter=vlan%2010
rotate_period_seconds=10
influxdb_dsn=influxdb://vmxadmin:grafstats@localhost:8086/capture
influxdb_measurement=pcap

For readability, this example lists each parameter on a new line. Usually they are just space-delimited on the same line of the capture.config file.

The configuration parameters that can be used in a capture.config file are as follows:

Parameter Name	Description	Type	Mandatory?	Default
name	Name of Capture probe	string	No	unnamed
compression	Compression method that will be used on resulting PCAPs. The standard method is gzip. See VMX-Capture Compression Card Configuration	enum (`noloadgz`, `363gz`, `bzip2`, `gzip`, `lzf`, `lzop`, `null`)	No	lzf
compression_level	Compression level. This may not be respected by all compression methods. Valid values are typically 0-9.	int	No	5
capture_file_type	The file format for the capture file. `pcapns` is the standard.	enum (`pcap`, `pcapns`)	No	pcap
output_dir	Location of PCAP storage. Usually this is set to `/data/capture`.	path	Yes
file_prefix	The prefix used for the capture files.	string	Yes
filter	BPF filter to be used by the capture probe (this example filters on vlan 10 i.e., filtering only on traffic tagged with VLAN 10).	string	No
rotate_period_seconds	Time elapsed before capture rolls over onto new PCAP file.	uint	No	60
rotate_period_bytes	The maximum size of each capture file in bytes before a new file is written.	uint64	No
snaplen	The snaplength (in bytes) for each packet written to the capture file. Snaplength should not be used with capture files which will be read by decoders.	uint64	No	65535
influxdb_dsn	The InfluxDB to which more granular statistics about the capture probe performance are written.	string	No
influxdb_measurement	Should be set to `pcap`.	string	No	pcap_stats
retention_lifetime	How long capture files should be retained for. <number> <units> where units = hours \| days \| weeks . This setting isn’t actually used by the capture probe, but is used by an Appliance cronjob (`capture_purge.py`) which handles capture file tidy-up.	string	No
retention_capacity	The maximum storage capacity that can be used by capture files from this probe <number>% = maximum percentage of the mounted volume allocated to capture files. <number><storage units> = maximum absolute size in units of GB \| GiB \| TB \| TiB . This setting isn’t actually used by the capture probe, but is used by an Appliance cronjob (`capture_purge.py`) which handles capture file tidy-up.	string	No
retention_emergency_purge	The threshold for the partition storage at which emergency purge kicks in. <number>% = maximum percentage of the mounted volume in use. <number><storage units> = maximum absolute size in units of GB \| GiB \| TB \| TiB . This setting isn’t actually used by the capture probe, but is used by an Appliance cronjob (`capture_purge.py`) which handles capture file tidy-up.	string	No