If you specify 'install' a new configuration using the session environment file name: "--session-name TEXT" will be created in directory: "/etc/nstringbufcap.d". At a minimum, both a valid capture interface: "--interface DEVICE" and capture directory: "--ring-buf-dir DIRECTORY" must be specified with this mode. One cannot use this mode when an active session exists using the same capture directory to install.

If you specify 'start' one or more new capture session instances using the environment name: "--session-name TEXT" will commence utilizing a ring buffer storage mechanism for captured packets. Each capture session runs as a "Systemd service". A valid capture interface: "--interface DEVICE" and capture directory: "--ring-buf-dir DIRECTORY" must be configured with install mode: "--mode install" prior to starting each capture session.

If you specify 'status' the current systemd service state of one or more capture sessions will displayed based on the value of the selected session environment name: "--session-name TEXT". Using this mode without any other options will display the status for all sessions.

If you specify 'stop' one or more capture systemd services for the selected session environment name: "--session-name TEXT" will be terminated.

If you specify 'trimstatus' the status of the 'netsniff-ng' capture file trim Systemd timer unit: "ringbuf-netsniff-ng-trim.timer" and service unit: "ringbuf-netsniff-ng-trim.service" will be displayed.

If you specify 'show' the content of all Ring Buffer capture configuration session environment files in the directory: "/etc/nstringbufcap.d" and their associated Ring Buffer capture directories will be displayed. In addition, the systemd service status for these capture sessions will be shown. Optionally, one can use the session name: "--session-name TEXT" parameter to only display information for a particular session.

If you specify 'showenvs' a listing of all currently configured session environment files found under the "/etc/nstringbufcap.d" directory will be shown.

If you specify 'list' the content of all configured capture session ring buffer directories will be displayed. Additionally, one can specify the ring buffer directory: "--ring-buf-dir DIRECTORY" option or the session name: "--session-name TEXT" option to obtain a specific directory listing.

If you specify 'snapwuilist' the content of all NST WUI Network Packet Capture directories found within the "--snapshot-dir DIRECTORY" will be listed.

If you specify 'merge' all capture files ending in "*.pcap" located in the ring buffer directory: "--ring-buf-dir DIRECTORY" will be combined in chronological order using the "mergecap" utility to create a new capture file: "--cap-merge-name TEXT". If the optional argument: "--remove-cap-files" is specified, then all component ring buffer files that exist will be removed.

If you specify 'wuimerge' all capture files in the selected ring buffer directory: "--ring-buf-dir DIRECTORY" or the directory configured in the session environment file name: "--session-name TEXT" will be combined in chronological order using the "mergecap" utility to create a new capture file for NST WUI "Network Packet Capture" usage. A network interface "--interface DEVICE" must be specified if a session name was not used and will be included in the creation of a "Capture Session Log" file. In addition, all component ring buffer files that exist will be removed. One can use the "--wui-log-annotation TEXT" option to set and override a default log message in the session log for this "WUI Merge" mode operation. After the merge, one can then use the NST WUI "Network Packet Capture Management & Status" page for packet capture management, decode and analysis.

If you specify 'snapshot' then a copy of the specified ring buffer capture directory: "--ring-buf-dir DIRECTORY" will be created under the snapshot directory: "--snapshot-dir DIRECTORY". Typically, this mode is used to archive previously captured network traffic so that is not overwritten by the ring buffer storage mechanism.

If you specify 'snapwuimerge' all capture files in the selected ring buffer directory: "--ring-buf-dir DIRECTORY" or the directory configured in the session environment file name: "--session-name TEXT" will be combined in chronological order using the "mergecap" utility to create a new capture file for NST WUI "Network Packet Capture" usage. This file will be located in a newly created subdirectory located under the directory specified by option: "--snapshot-dir DIRECTORY". A network interface "--interface DEVICE" must be specified if a session name was not used and will be included in the creation of a "Capture Session Log" file. The naming convention for the created subdirectory will use either the session name or the network interface name followed by a date time stamp (e.g., Session: "fw0_20161012_101218" or Interface: "eth0_20161012_101218"). One can use the "--wui-log-annotation TEXT" option to set and override a default log message in the session log for this "Snap WUI Merge" mode operation. After the merge, one can then use the NST WUI "Network Packet Capture Management & Status" page for packet capture management, decode and analysis.

If you specify 'trim' then a maximum number: "--max-file-cnt INTEGER" of newer capture files with extension: ".pcap" will be preserved in the selected ring buffer capture directory: "--ring-buf-dir DIRECTORY". A session environment name: "--session-name TEXT" can also be used to indicate the ring buffer capture directory to be trimmed. This mode is typically used with the capture tool: "netsniff-ng" since it does not have a mechanism for removing older capture files in the ring buffer once the maximum file count: "--max-file-cnt INTEGER" has been reached. If the capture tool: "--cap-tool netsniff-ng" option is also set with this mode then only active "netsniff-ng" capture sessions will have their associated ring buffer directory trimmed. The Systemd timer unit: "ringbuf-netsniff-ng-trim.timer" and service unit: "ringbuf-netsniff-ng-trim.service" pair will automatically check to trim "netsniff-ng" generated capture files in the associated ring buffer directory every 10 seconds. The timer is started whenever a new "netsniff-ng" capture session has commenced. When the "netsniff-ng" capture session is terminated, the timer will be stopped if there are no other "netsniff-ng" capture sessions running.

If you specify 'snapwuitrim' then a maximum number: "--keep-wui-dirs INTEGER" of newer NST WUI Network Packet Capture directories created with mode: "--mode snapwuimerge" located in directory: "--snapshot-dir DIRECTORY" will be preserved. This mode provides the means to remove older capture directories that are no longer needed. Optionally, a session name: "--session-name TEXT" can be specified to select a set of NST WUI Network Packet Capture directories to be trimmed.

If you specify 'clear' then one can either delete all capture and log files (i.e., *.cap, *.pcap and *.log) in the ring buffer capture directory: "--ring-buf-dir DIRECTORY" and/or delete a configuration environment file associated with the capture session name: "--session-name TEXT". If the session name is set to "all", then all ring buffer directories that are not associated with an active capture session will be cleared.

This option specifies an operational nstringbufcap mode. Currently the following modes: 'install', 'start', 'status', 'stop', 'trimstatus', 'show', 'showenvs', 'list', 'snapwuilist', 'merge', 'wuimerge', 'snapshot', 'snapwuimerge','trim', 'snapwuitrim' and 'clear' are supported. The description for each supported mode is described above.

This interface device will be used to listen for network traffic with capture tool: "--cap-tool TEXT". The network interface device will be put into promiscuous mode while capturing packets.

Choose a supported capture tool to perform the network packet capture. The "nstringbufcap" script currently supports either the "dumpcap" or the "netsniff-ng" network packet capture tool. The default capture tool is set to: "dumpcap".

This directory will contain the ring buffer capture files for a given capture session. ***Note: 1) Each capture session must be associated with a unique Ring Buffer directory. The start of a new capture session will "fail" if another capture session is currently using this same capture directory. 2) The content of the capture directory will be erased prior to the start of a new capture session. 3) The capture directory must exist prior to using this option.

Set the ring buffer capture configuration environment name for the capture session. This name will be used to identify the session envronment file for a capture session instance. Each capture session runs as a "systemd service". All session configuration files are located in directory: "/etc/nstringbufcap.d". The session name: "all" is a reserved name and used to specify 'all' capture session names for modes: "--mode start", "--mode status", "--mode stop", "--mode list", "--mode clear", or "--mode show". ***Note: All space ( ) and/or hyphen (-) characters found in the session name will be converted to the underscore character (_).

Set a prefix name for the ring buffer capture file name. An "underscore (_)" character will be automatically appended to the prefix if the "netsniff-ng" capture tool is selected. Both tools will generate ring buffer capture file names with a ".pcap" extension. The default capture name prefix is set to: "rngbuf" for capture tool: "dumpcap" and "rngbuf_" for capture tool: "netsniff-ng". The following is an example default full ring buffer capture file name using "dumpcap": "rngbuf_00003_20160913074621.pcap" (See dumpcap(1) for details on file naming). The following is an example default full ring buffer capture file name using "netsniff-ng": "rngbuf_1473766946.pcap" (See netsniff-ng(8) for details on file naming).

The ring buffer capture session will switch to the next sequential capture file after it reaches a file size of this value in KiloBytes (KiB). The default maximum file size is set to: "2000 KiB". This option is ignored if set to "0 KiB". The capture tool: "dumpcap" can use both this maximum file size setting and the maximum duration setting: "--max-cap-dur" as criteria for capture file switching. The capture tool: "netsniff-ng" can only use this maximum file size setting or the maximum duration setting: "--max-cap-dur" as a criterion for capture file switching. The minimum value permitted is 0. The maximum value permitted is 2000000.

The ring buffer capture session will switch to the next sequential capture file after it reaches a time duration of this value in seconds. There is no default value setting for this parameter and therefore this criterion is not active until a value is set. The capture tool: "dumpcap" can use both this maximum duration setting and the maximum file size setting: "--max-file-size INTEGER" as criteria for capture file switching. The capture tool: "netsniff-ng" can only use this maximum duration setting or the maximum file size setting: "--max-file-size" as a criterion for capture file switching. Set the maximum file size option to zero: "--max-file-size 0" for this option to work with the "netsniff-ng" capture tool. The minimum value permitted is 1. The maximum value permitted is 86400.

This is the maximum number of files that will be created during a capture session to form the ring buffer. Once this file count limit has been reached, the oldest file will be removed and a new capture file will be written into the ring buffer. The default maximum file count is set to: "4". The minimum value permitted is 1. The maximum value permitted is 100000.

No more than snaplen bytes of each network packet will be read into memory, or saved to disk. A value of 0 specifies a snapshot length of 65535, so that the full packet is captured. ***Note: This option is only can only be used with capture tool: "dumpcap". The minimum value permitted is 0. The maximum value permitted is 65535.

Set a capture filter expression for the capture session. One uses a capture filter to selectively choose the network traffic of interest and potentially limit the size of the capture file content. For the filter syntax, see "pcap-filter(7)". Encapsulate a filter with single quotes "'" if it includes special characters or spaces. There is no default capture filter defined so all network traffic will be captured by default.

One can specify one or more additional options for the selected capture tool: "--cap-tool TEXT". This example sets a maximum packet count of 2000 packets and increases the capture buffer size to 4 MiB for the capture session using dumpcap: "--cap-tool-opts ' -c 2000 -B 4'". Encapsulate the options in single quotes "'". Use a leading space when the first option starts with a dash (-).

Set this option to "true" to assume the answer "Yes" for any mode that requires an affimative response.

This directory is used to make a reference copy of the specified ring buffer capture directory: "--ring-buf-dir DIRECTORY". Typically, this option is used with mode: "--mode snapshot" to take a snapshot reference copy of captured network traffic during an active ring buffer capture session before the packets are potentially overwritten. ***Note: If the ring buffer storage configuration is not large enough (i.e., A combination of the maximum file size: "--max-file-size INTEGER", the maximum file time duration: "--max-file-dur INTEGER" and the maximum file count: "--max-file-cnt INTEGER"), newer network packets could overwrite previously capture packets. This directory is also used as the parent directory to hold NST WUI Network Packet Capture directories created with mode: "--mode snapwuimerge". Modes: "--mode snapwuilist" and "--mode snapwuitrim" use this directory for NST WUI Network Packet Capture management.

Use this option to specify the file name resulting from merging all capture files ending in "*.pcap" using mode: "--mode merge" in the ring buffer capture directory: "--ring-buf-dir DIRECTORY". The merged capture file will be created in the ring buffer directory. The "--remove-cap-files" option can also be specified to remove all ring buffer capture files after the merge process has completed. Typically the merge file name should end with a "pcap" file name extension. An example capture merge file name: "--cap-merge-name 'lan0-20161028-103010.pcap'".

Use this option to remove all ring buffer capture files (i.e., *.pcap) when specifying mode: "--mode merge" for combining all capture files into a single merged capture file.

This parameter is used with mode: "--mode snapwuitrim" to set the maximum number of newer NST WUI Network Packet Capture directories to preserve in the snapshot directory: "--snapshot-dir DIRECTORY". The default number of directories to keep is set to: "4". Set this parameter to "zero (0)" to delete all directories. The minimum value permitted is 0. The maximum value permitted is 100000.

Use this option to set the annotation that will appear in an NST WUI Single-Tap Network Packet Capture log when using modes: "--mode wuimerge" or "--mode snapwuimerge".

When this option is specified, nstringbufcap will display a short one line description of nstringbufcap, followed by a short description of each of the supported command line options. After displaying this information nstringbufcap will terminate.

This option will attempt to pull up additional nstringbufcap documentation within a text based web browser. You can force which browser we use setting the environment variable TEXTBROWSER, otherwise, we will search for some common ones.

When you set this option to true, nstringbufcap will produce additional output. This is typically used for diagnostic purposes to help track down when things go wrong.

If this option is specified, the version number of the script is displayed.

An Environment file for the Systemd service unit: "ringbuf-netsniff-ng-trim.service"

A Systemd service unit template file for the dumpcap capture tool.

A Systemd service unit template file for the netsniff-ng capture tool.

A Systemd service unit used for trimming netsniff-ng generated capture files in the associated ring buffer directory.

A Systemd timer unit used to periodically (i.e. Every 10 seconds) start the Systemd service unit: "ringbuf-netsniff-ng-trim.service" for trimming netsniff-ng generated capture files in the associated ring buffer directory.

This directory contains the ring buffer capture session environment files.

This controls what text based browser is used to display help information about the script. If not set, we will search your system for available text-based browsers (Ex: elinks, lynx ...).