Difference between revisions of "HowTo Configure and Run a Ring Buffer Capture Session Using: "nstringbufcap""
(→Mode: install) |
(→Mode: install) |
||
| Line 10: | Line 10: | ||
This mode will install a ring buffer capture session environment configuration. A valid and accessible ring buffer capture directory must be created prior to using this mode. This directory will be used to store the captured network traffic file components that make up the ring buffer. | This mode will install a ring buffer capture session environment configuration. A valid and accessible ring buffer capture directory must be created prior to using this mode. This directory will be used to store the captured network traffic file components that make up the ring buffer. | ||
| − | Storage sizing of the ring buffer is very important because it establishes the rolling window in time (i.e., capture window) for the collection of captured traffic. The trick to sizing is based on the network traffic bandwidth. One | + | Storage sizing of the ring buffer is very important because it establishes the rolling window in time (i.e., capture window) for the collection of captured traffic. The trick to sizing is based on the network traffic bandwidth. One needs to determine the size of the capture window so that network traffic of interest is captured and does not fall outside the boundary of the ring buffer. The size is calculated by multiplying the maximum number of capture file components times the allocated file size in Kilobytes (KB). When a capture file fills up to the allocated limit the file is then closed for writing and a new file is created for capture writing. When the maximum file count is reached for the ring buffer, the oldest capture file will replaced by the new capture file to be written to. The '''dumpcap''' tool does this automatically and the '''netsniff-ng''' tool requires an additional '''systemd timer service''': "'''/usr/lib/systemd/system/ringbuf-netsniff-ng-trim.timer'''" to perform this functionality every 10 seconds. The entire sequence continues until the capture session is terminated. |
A maximum file duration option: '''--max-file-dur INTEGER''' can also be used as an additional limiting ring buffer file size criterion. The capture file will switch to the next file after INTEGER seconds have elapsed, even if the current file has not reached its allocated size. This option may be useful to better quantify the ring buffer capture window especially during lower capture rates. | A maximum file duration option: '''--max-file-dur INTEGER''' can also be used as an additional limiting ring buffer file size criterion. The capture file will switch to the next file after INTEGER seconds have elapsed, even if the current file has not reached its allocated size. This option may be useful to better quantify the ring buffer capture window especially during lower capture rates. | ||
Revision as of 12:17, 20 October 2016
Contents
Overview
A new NST script: "nstringbufcap" has been developed with NST 24 for managing one or more network packet capture sessions that utilize a ring buffer storage mechanism. This capability allows one to capture network traffic pre and post a controlled event. Currently, an NST Network Interface Bandwidth Monitor 2 Threshold Pause State Notification Execs template: "/etc/nst/notifications/bwmon/tp_state_nstringbufcap_snapwuimerge.template" is provided for snapping a capture when a Pause event occurs and then the NST WUI Single-Tap Network Packet Capture page can be used for capture decode and analysis.
The nstringbufcap script has a specific mode used for installing and configuring a ring buffer capture session. Once install, a capture session can be started under the control of a systemd service. The life cycle of the capture session can then be controlled by a nstringbufcap mode that internally uses systemd control commands (i.e., systemctl). At any point in time, a snapshot capture can be taking to preserve captured network traffic packets. nstringbufcap currently supports two (2) network capturing tools: dumpcap and netsniff-ng.
This page will describe the use of the nstringbufcap script by way of example use cases.
Mode: install
This mode will install a ring buffer capture session environment configuration. A valid and accessible ring buffer capture directory must be created prior to using this mode. This directory will be used to store the captured network traffic file components that make up the ring buffer.
Storage sizing of the ring buffer is very important because it establishes the rolling window in time (i.e., capture window) for the collection of captured traffic. The trick to sizing is based on the network traffic bandwidth. One needs to determine the size of the capture window so that network traffic of interest is captured and does not fall outside the boundary of the ring buffer. The size is calculated by multiplying the maximum number of capture file components times the allocated file size in Kilobytes (KB). When a capture file fills up to the allocated limit the file is then closed for writing and a new file is created for capture writing. When the maximum file count is reached for the ring buffer, the oldest capture file will replaced by the new capture file to be written to. The dumpcap tool does this automatically and the netsniff-ng tool requires an additional systemd timer service: "/usr/lib/systemd/system/ringbuf-netsniff-ng-trim.timer" to perform this functionality every 10 seconds. The entire sequence continues until the capture session is terminated.
A maximum file duration option: --max-file-dur INTEGER can also be used as an additional limiting ring buffer file size criterion. The capture file will switch to the next file after INTEGER seconds have elapsed, even if the current file has not reached its allocated size. This option may be useful to better quantify the ring buffer capture window especially during lower capture rates.
The example install mode shown below is used to create a configuration file (i.e., firewall located in directory: "/etc/nstringbufcap.d") for a ring buffer capture session that will capture packets on network interface: "fw0". The dumpcap capture tool will be used with the ring buffer directory set to "/opt/ringbufcap1". The ring buffer size consists of 20 capture files each with a maximum size of 2MB (i.e., A 40MB ring buffer size.).
A new Ring Buffer dumpcap Capture session environment file was
created and installed: "/etc/nstringbufcap.d/firewall"
=========================================================================================
firewall (dumpcap): Ring Buffer Capture Configuration Directory: "/etc/nstringbufcap.d"
-----------------------------------------------------------------------------------------
/bin/ls -Al "/etc/nstringbufcap.d";
total 4
-rw-r--r-- 1 root root 479 Oct 19 17:03 firewall
Configuration: "firewall"
-----------------------------------------------------------------------------------------
/bin/cat "/etc/nstringbufcap.d/firewall";
#
# An nstringbufcap environment file (Installed on: Wed Oct 19 17:03:28 EDT 2016).
#
# Capture Tool: dumpcap
#
# Ring Buffer File Count: 20
#
# Required Syntax:
# 1) Make sure the entire OPTIONS variable value is enclosed
# in double quotes (").
#
# 2) Make sure the Ring Buffer directory (-w) and/or the Capture Filter
# expression (-f) parameters are enclosed in single quotes (').
OPTIONS="-q -i fw0 -b filesize:2000 -b files:20 -w '/opt/ringbufcap1/fw.pcap'"
=========================================================================================
