(Optional) Multiple Adapter Packet Capture

Beginning with 11.5, the Network Decoder can capture from multiple interfaces simultaneously. This functionality allows Network Decoders to capture from multiple physical Network Interface Cards (NICs), or multiple ports on multiple interfaces, while leveraging the same network rules, application rules, and parsers for each NIC. The benefit of capturing from multiple physical NICs is that this method multi-threads the capture process for each adapter interface, which also multi-threads network rule evaluation.

For example, prior to 11.5, defining capture.selected=PFRINGZC, em3 along with capture.device.params=device=zc:em3,zc:em4 allocated a single thread for the Network Decoder to capture any traffic that came into either em3 or em4 interfaces. This also meant that all network rules were evaluated in a single thread.

However, in 11.5, configuring capture.selected=PFRINGZC,em3; PFRINGZC,em4 allocates two threads for the Network Decoder to capture the traffic collected on either em3 or em4, which provides more resources to the capture pipeline.

In this topic, the term "adapter" refers to a capture device within the Decoder. An adapter's name consists of the device (for example, the software API that the Decoder uses to interact with an adapter), and an interface (the physical device). A device can have multiple interfaces, and an interface can be compatible with multiple devices.

Configure Multiple Adapter Packet Capture

Note: Changes to capture device configuration do not take effect until service restart.

You can define multiple adapter packet capture for Decoders in the config setting /decoder/config/capture.selected. It accepts a semi-colon separated list of adapters, for example: bpf,en5 (bpf);null_device,Null Capture. This setting can be edited while capture is running, however, the changes do not take effect until the service has been restarted.

You can use the /decoder?msg=select command to select one or more adapters after capture has been stopped, for example: /decoder?msg=select&adapter=1,3,5 netwitness_12.1_multipleadaptercapture_1122.png

Note: As of 11.5, this configuration is not yet available in the decoder > config page. Use the decoder > explore page or the REST API. You can the Explore view by selecting a Decoder in the user interface and going to netwitness_actions_button.png (actions)> View > Explore. You can access the REST API by opening a browser and specifying the IP address of the host, for example, https://<decoder-ip-address>:50106.

Per Interface Configuration

The /device/config/device.capture.params configuration is a global configuration setting, and is applied to every interface when capture is started.

There is also a configuration setting for individual interfaces, which is /decoder/devices/<devicename>/<interfacename>/config. Currently, the only option available in this configuration setting is capture.params. Any value in this setting will override the global configuration setting.

Stat Nodes

As with configuration, there are per-interface stats and aggregate stats (similar to the global configuration). When there is a single device configured, these stat nodes function as in previous versions. When there is more than one device configured, the stat settings /decoder/stats/capture.device and /decoder/stats/capture.selected read multi.

Per-Interface Stats

The stats for each interface can be found in: /decoder/devices/<devicename>/<interfacename>/stats

The captured stats are:

  • capture.avg.size
  • capture.dropped
  • capture.filtered
  • capture.header.bytes
  • capture.kept
  • capture.payload.bytes
  • capture.received
  • capture.total.bytes
  • pool.packet.captured

Aggregate Stats

The capture stats under /decoder/stats represent an aggregate of the individual interface stats.

In the following table, for example, capture.avg.size is the maximum average size among all the interfaces, where capture.dropped is the total captures that were dropped for all the interfaces.



capture.avg.size MAX
capture.dropped SUM
capture.filtered SUM
capture.header.bytes SUM
capture.kept SUM
capture.payload.bytes SUM
capture.received SUM
capture.total.bytes SUM
pool.packet.captured MIN

Pool Stats

All the network packet and session pool pages are tracked in /decoder/stats/pool/.

The stats under /decoder/stats/pool represents the total number of capture pages configured in Decoder. These include packet pool and session pool pages.

capture.port Meta Key

Each session is given a capture.port meta key which identifies the adapter from which the packets in the session were captured. This meta key can optionally be turned off with the /decoder/config/captureport.meta.enabled option. This meta key is on by default for Network Decoders, and is off by default for Log Decoders.

IMPORTANT: The capture.port meta key does not work with the packet_mmap_,ALL adapter. You must specify individual ports while using capture.port. The packet_mmap_,ALL adapter is capable of capturing across all types of network interfaces at the same time. For more information, see (Optional) Configure a Decoder to Capture Data Across All Types of Network Interfaces.

Note: If you turn the capture.port meta key off, you must perform a capture restart for the change to take affect since this is a configuration change.

Special Devices

The nwimport device is for handling PCAP imports while simultaneously capturing network data. For more information on PCAP imports, see Upload a Packet Capture File.

nwimport: This device is not selectable but does have stat and config nodes. The config node for nwimport is ignored.

Packet arrived out of order Message

This message means that the Decoder is seeing old packets. This can be a side-effect of running import while capture is running. This message is usually suppressed at the beginning of import and then unsuppressed at the end. However, packets can still be in the state of being processed even after the upload of the imported file has completed. This means that this warning can be unsuppressed before the processing of the imported packets is completed, which results in displaying this message.

For information about updating Decoder configurations, see the RESTful API User Guide for NetWitness Platform. For information about stopping and restarting capture, see Configure Capture Settings. Go to the NetWitness All Versions Documents page and find NetWitness Platform guides to troubleshoot issues.

Multi-Assembler Modes

The process that reassembles captured packets into streams is known as the Assembler. You can customize the Assembler operation to suit the packet capture configuration. It works in two modes (on and off) that are configured using the /decoder/config/assembler.threading.enabled variable. The value of assembler.threading.enabled only takes effect if multi-adapter packet capture is enabled.

Note: If you change the value of assembler.threading.enabled, you must perform a capture restart.

OFF Mode: If assembler threading is off, then one Assembler is used to assemble all packets captured from all interfaces. Packets from a stream may appear on any capture interface and the single assembler will put them back together.

  • Assembler threading must be off to allow assembler to reconstruct streams that are capture across multiple capture interfaces.

  • When assembler threading is off, the single Assembler instance may limit the maximum packet rate that the Decoder can process.

ON Mode: If assembler threading is on, there will be a separate Assembler for each capture interface. Each Assembler will only reassemble the packets it receives from it's capture interface.

  • This mode of operation enables higher throughput because each Assembler instance operates on a dedicated processor.

  • Each logical stream of packets must be ingested by one interface only. For example, the streams on each capture interface could come from different networks.

For compatibility with previous releases, the Multi Assembler mode is off by default.

When importing packets, the imported packets are fed to one of the existing assemblers, or the single Assembler instance when Assembler threading is off. Importing packets does not create a separate Assembler process.