Packet capturing from the command line

Goals

Create a command line utility that captures network traffic with the following requirements.

• For SR140 installation, this utility will be installed optionally. The user will be able to choose whether install it or not.
• The utility will be available for both Windows and Linux.
• The utility will take all configurations from a single configuration file. It will accept only one command line parameter - path to that configuration file. 
• Most functionality will be placed into a dynamic library (.dll, .so). The command line executable only contains minimal functionality required to use the library. 
• The utility will only capture packets being sent from or received to one of the network interfaces on the host machine, running the utility.
• The utility will only capture UDP and (optionally) TCP packets. Other kinds of IP packets (ARP, ICMP etc.) will be ignored, as well as any non-IP Ethernet packets.
• The utility will save the captured packets in output files in .pcapng format. The resulting files can be opened in the Wireshark UI.
• The resulting files will have configurable maximum size. Once the size limit is reached on the current file, the next file is created and the utility starts saving packets to the new file. 
• There will be limit on maximum number of result files that can reside in the output directory. The oldest files will be deleted as necessary.
• The packet filtering can be configured:
  • Set a list of peer IP addresses. Only save traffic between these IP addresses and the capture adapter address.
  • Only save packets sent from or received on certain ports on the capture IP interface (local ports).  
  • Only save packets sent from or received on certain remote ports on peer IPs (remote ports). 

Background and strategic fit

For debugging capture, it has been requested to have the ability to capture network traces from the command line. Customers are not comfortable running Wireshark and they also do not like capturing all network traffic. The request is to be able to capture network traffic from the command line without running the Wireshark GUI. It would be useful to only capture a certain call for debugging call issues but the initial request is to just capture from the command line. Some other customers may want to avoid having network sniffing capacity installed on their network. So the solution should be implemented as an optional component. The user will decide whether to install it or not in the course of the SR140 installation process. 

Assumptions

The capture utility has to be run with elevated permissions. It should be run as local Administrator in Windows. In Linux, it has to be started as root (or sudo).   

Requirements

Usage

The utility must be given one and only one command line parameter - the path to a configuration file.

In Windows, the user opens command window as Administrator, change directory to where the utility (btcap.exe) is located. Then run:

> .\btcap.exe <path-to-config-file>

In Linux, run:

$ sudo ./btcap <path-to-config-file>

For both platforms, to stop the capture process, the user needs to press Ctrl+C once. In at most a few seconds the utility will gracefully exit. All files and sockets will be closed, any system resources (memory) released.

Btcap Config File

Btcap config file path is the only command line parameter for the capture utility. It defines all configuration parameters. Here is the content of an example configuration file. Each configuration parameter is described by comments.  

# capture_ip: Identifier of the network interface to capture traffic. For Windows this MUST be the IPv4 address of the interface. For Linux, this can be 

# IPv4 address or IPv6 address of the interface. But the recommended way is to use Linux device name - wlan0, eth0 etc.
# This parameter cannot be missing or empty. There is no default value. '*' is not a valid value for this parameter.
capture_ip = 192.168.5.149

# peer_ip: Capture traffic between these IP addresses and the address specified in capture_ip. The value is a comma-separated list. Each item in the list is an individual IPv4 addresses or an interval of IPv4 addresses. Note: IPv6 addresses are not supported in this parameter.
# Example: peer_ip = 192.168.5.1 - 192.168.5.255, 192.168.7.118 . To capture traffic from ANY IP address, the special value '*' is used: peer_ip = *. Default value is '*'.
# This parameter cannot be empty. If it is missing, the default value will be assigned.
peer_ip= 192.168.5.114, 192.168.5.150 - 192.168.5.200

# tcp_packets: Boolean parameter instructing the tool whether to capture TCP packets (value of 1) or not (value of 0). Default value is 0. NOTE: UDP packets are always captured.
tcp_packets = 1

# local_port_include: Capture packets on these ports on capture_ip interface (local ports). Default value is '*', instructing the system to capture from any local port. This parameter
# cannot be empty. The value is a comma-separated list. Items in the list are either individual port numbers or intervals. Example: local_port_include = 11983, 11984, 21010-21025
local_port_include = 5060, 56000 - 56999

# local_port_exclude: Exclude packets to/from some local ports even if they are included in local_port_include. Default value is empty. The value is a comma-separated list.
# list are individual port numbers or intervals. '*'' is not a valid value for this item. Example: local_port_exclude = 1980,11908,9898-9899
local_port_exclude = 137

# remote_port_include: Capture packets coming to/from these remote ports. Default value is '*', instructing the system to capture allow any remote port. This parameter
# cannot be empty. The value is a comma-separated list. Items in the list are either individual port numbers or intervals. Example: remote_port_include = 11983, 11984, 21010-21025
remote_port_include = *

# remote_port_exclude: Exclude packets from/to some remote ports even if they are included in remote_port_include. Default value is empty. The value is a comma-separated list.
# list are individual port numbers or intervals. '*'' is not a valid value for this item. Example: remote_port_exclude = 1980,11908,9898-9899
remote_port_exclude = 53

# results_dir: The path to a directory (existing) where the pcapng files are saved by this session. Can be absolute path or relative to current directory.
results_dir = ./pcapng/

# max_result_file_size: Maximum pcapng file size before the utility creates and starts writing to the next file. The value is specified in MegaBytes (MB)
max_result_file_size = 100

# max_number_of_result_files: Maximum number of pcapng files that will be written before the system starts to delete oldest files.
max_number_of_result_files = 5

# log_debug: Set to 1 for more verbose logging (debug-level logging). Default is 0.
log_debug = 1

# log_to_console: Set to 1 to print non-critical log messages to console (Note that Errors will always be printed to console, even if this parameter is 0). Default is 0.
log_to_console = 1

Implementation Overview

(to be added...)

End User Installation

The purpose of this tool is to allow the ability of packet capturing on the SR140 system without the need to download any special tools after the installation.   The necessary components of this tool will be included with the MSI package.  Since there may be customer requirements to not allow packet sniffing tools on their network, and option will be required to allow (for Windows) the end user to not install this tool.  The release notes will contain information about this tool and its purpose.  The location for instructions for how to use the tool are to be decided.  There should be a minimum help from the command line.

Windows InstallShield to be updated to display that the tool will be installed with a check-box enabled on by default to install the tool.  Unchecking the box will not install the tool. 

The preference is to have the checkbox on the first screen of the installation. 

It will be nice to have a switch to control the installation from the command line. The MSI file can be installed with the /passive switch.

For the non-SR140 version of the MSI, this tool will not be available. The installation will not change and the tool will not be included in the MSI.

For Linux, option will be installed by default with no options.  It will be up to the end user or application developer to determine if the files should be removed.

The library and executable files will be placed into the bin directory.

A sample filter file will be placed into the config directory.

There will be a sample source file created as an example to use the library as a part of their fax application.  This sample will not be included in the installation and will be provided to the  application developers when requested.

Need to still determine legal notice and/or if an update to the COO needs to be approved. This tool does not have a dependencies on the SDK and can be created without it.  There are no plans to distribute the source files for the tool at this time.

Questions

Below is a list of questions to be addressed as a result of this requirements document:

Not Doing