Page Comparison

...

Goals

Create a software component implementing capturing command line utility that captures network traffic with the following requirements.

• For SR140 installation, this component utility will be installed optionally.  
• Only the traffic from and to the machine running SR140 will be captured.
• Only IP traffic will always be captured. Other kinds of Ethernet packets are rejected.
• The basic configurable filtering is available:
  • Capture UDP packets only (default), or, in addition, also capture TCP packets.
  • Capture only packets coming from and to specified list of IP addresses (the other end is always local SR140 host machine, as mentioned earlier in this list)
  • Capture only packets coming to or from specific ports on local SR140 machine.  
• The resulting output files will be in .pcapng format files. They will be open for view/analysis in 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 be of reasonable size. There will be rotation when max size is reached, also when day changes.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 be created. When it is reached, the reside in the output directory. The oldest files will be replaced with the new files.

...

• 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 capturingcapture, 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 executable that loads and uses btcap dynamic library 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). If btcap is loaded into the context of a non-elevated process then Start() entry point will return error.     

Requirements

API Design

The capture traffic component is implemented as a dynamic library. Implementing it this way works well for making it optionally installed. The library is named btcap.dll on Windows and btcap.so on Linux. That naming schema appears to be in line with other library names in the problem area (pcap, wincap and so on). The code utilizing btcap library may be placed in a variety of executables including the SR140 server process itself. The executables using btcap library must be running as Administrator (in Window) or root (in Linux).  

Important definitions:

• Capture Point. This is defined as one of IP network interfaces available on the host machine PLUS the IP version of packets that we want to capture (IPv4 or IPv6). So, for every NIC installed there can be 2 capture points configured - one for IPv4, and one for IPv6. Capture Point concept is defined simply because the underlying capture technologies require to choose one adapter AND one IP version to setup the packet capture. There will be various ways to identify a Capture Point. The simplest way to point to a particular capture point is to provide a IP address string. Btcap will then understand whether it is IPv4 or IPv6, and then identify the network interface that has the specified IP address. If none of the local IP interfaces have the specified address, then an attempt to start capture will fail. 
• Capture Session. This describes the process of capturing network traffic from a single Capture Point. An executable using btcap library may start multiple capture sessions if necessary. With appropriate configuration, some or all of them can capture from the same Capture Point. 

Basic API

With the terms defined above, the exposed API is very simple, and is the same for Windows and Linux. There are only 2 C functions exported from the library. One of them starts new capture session, the other eventually stops it. Capture session is configured as a sections in btcap config file. The config parameters include capture point, output directory, capture filters, and more. Btcap config file is described in details later in this document.

With this basic API, it is user's responsibility to dynamically load the btcap library and locate exported functions. Later in this document, a simplified level C++ API is described which incapsulates loading library bookkeeping. 

// Start one Capture Session configured in the config file section named sectionName. Session ID is returned in *sessionID.

int btcap_start(const char* configFilePath, const char* sectionName, int* sessionID);

// Stop Capture Session identified with sessionID.

int btcap_stop(int sessionID);

Both methods return 0 on success or a non-zero error code. 

To start a capture session the user calls btcap_start() providing (a) a valid path to a btcap config file and (b) a valid section name within that file.

First, btcap_start() attempts to (a) open the config file, (b) read the section in the file, (c) read session parameters from that section, and (d) validate session parameters. If any of that fails with appropriate error code. 

If all required parameters are read from the config file, btcap_start() attempts to start the capture session in a separate "capture thread". btcap_start() itself returns as soon as the capture thread successfully starts. If the capture cannot start for whatever reason, then the btcap_start() will return an error code, and the capture thread will not exist upon return. So btcap_start() is not blocking.

On success, btcap_start() fills the sessionID with the new session's ID. That is an opaque identifier of the session, similar to Unix file descriptor. It is later used in btcap_stop().

To stop a capture session the user calls btcap_stop() providing the ID of the previously saved session. btcap_stop() signals the capture thread to stop and waits until it is done before returning.

Basic Usage Scenario

Here is the basic sequence of operations utilizing the btcap library (in pseudo-code). 

// The code loading btcap library and obtaining exported entry point pointers by names is omitted. If loading failed, the program exits.  

const char* configFilePath = ".\btcap.cfg";   // Config file path for this session

const char* configFileSection = "wlan0-ipv4"; // Config file section name

// Start capture session

int sessionID = 0;

int rc = btcap_start(configFilePath, configFileSection, &sessionID);

if(rc)

    return 1;

// Session started in separate thread. Do other stuff...

// ... 

// Later stop the capture session

btcap_stop(sessionID);

// Unload btcap library

Btcap Config File Overview

Btcap config file has the same format as SR140 call control file. It consists of sections. Section names can be anything in square brackets. Each section configures one capture session. btcap_start() API (described earlier) takes both config file path and section name as arguments. 

One section defines one capture session which maps to one capture point There can be more than one sections configured for the same capture point.

The following parameters can be configured in a section.    

...

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.111. This parameter cannot be missing or empty, there is not default value. 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 IP address or a subnet. The asterisk symbol '*' is used to depict subnets. individual IPv4 addresses or an interval of IPv4 addresses. Note: IPv6 addresses are not supported in this parameter.
# Example: peer_ip   = 192.168.5.*, 1921 - 192.168.5.255, 192.168.7.118 . There is also a special value, * , depicting ANY IP addressTo 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. Example: 
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 include = 1983, 1984, 2010-202511983, 11984, 21010-21025
local_port_include = 5060, 56000 - 56999

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

# remote_port_include:  Capture 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 include = 198311983, 198411984, 2010-202521010-21025
remote_port_include = *

# remote_port_exclude:  Exclude specified Exclude packets from/to some remote ports even if they are to be included in in remote_port_include. Default value is empty. The value is a comma-separated list. Items in the
# list are either individual port numbers or intervals. '*'' is not a valid value for this item. Example: remote_port_exclude 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.  Example: Can be absolute path or relative to current directory.
results_dir = . ./binpcapng/pcapng-output

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

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

More parameters will be added as necessary. 

Higher level API - BTCapHelper

A higher level C++ API in form of class BTCapHelper was created mainly to hide the technical details of loading library and also hide the differences in that area between OS platforms. Here is the class definition.

...

Here, BTCap_GetHelper() is the factory function that will create an instance of BTCapHelper-derived platform-dependent implementation.

The BTCapHelper::Start() will (a) load the library, (b) find and save function pointers for btcap_start and btcap_stop, and (c) call btcap_start(). BTCapHelper will remember the sessionID. 

The BTCapHelper::Stop() will (a) call btcap_stop() then (b) unload the library.

Usage scenario with BTCapHelper

Here is the complete command line program for Windows that utilizes BTCapHelper API.

...

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...)

...