From Fortian

The Fortian Embedded Real-Time Packet Analyzer

Abstract

The embedded version of RTTA, named nightcap, is documented here. To date, there have been three released generations of nightcap. The most recent version is: 3.0.5

Changes from version 2.0:

nightcap now transmits information similar to that logged to disk, via multicast
The relevant multicast group is defined with the new multicast keyword in the configuration file. This keyword can be repeated multiple times, to allow multiple transmissions on different multicast groups and with different TTLs.

Changes from version 1.0 in version 2.0:

Logs are now stored in separate logfiles, as defined by the configuration file. Operation without a configuration file is not possible.
Command-line syntax has been updated to reflect more complex operational parameters.

nightcap contains previously unreleased source code that is the property of Fortian. Redistribution is prohibited without explicit permission.

Overview

nightcap resets its counters every time data is logged. This means that it behaves the way that MRTG's gauge keywork anticipates, that is, more like a speedometer than an odometer. If a data point from nightcap is lost, it may be possible to interpolate it statistically, but subsequent values are independent of the missing data.

Command-Line Syntax

Usage: nightcap [-c PROPSFILE] [-p PIDFILE] [-d TIME] [-f LOGPATH] [-F]

PROPSFILE is the name of the properties file, and defaults to: /etc/nightcap.properties

It must be readable for the program to operate.

PIDFILE is the name of the file to write the process ID to, and defaults to: /var/log/nightcap.pid

TIME is the number of seconds between samples, and defaults to: 10

LOGPATH is the location for logfiles, and defaults to: /root

The program will not fork into the background if -F is provided.

Run-Time Configuration

Configuration file options will be overriden by the command line, but provide system-specific defaults. Since version 2.0, nightcap cannot operate without a configuration file. An annotated configuration file is available. The same configuration follows, with greater discussion.

 1	# names: used as the suffix for the device.*, filter.*, and description.*
 2	#   one log will be kept per name, with the extension ".binlog"
 3	names=wire_in,radio_out,wire_out,radio_in
 4	# logpath: where logs should be stored
 5	logpath=/root
 6	# pidfile: where to store the runtime PID file
 7	pidfile=/var/log/nightcap.pid
 8	# interval: the number of seconds between entries in the logfile
 9	interval=1
10	# foreground: whether or not to remain in the foreground.
11	foreground=0
12	# multicast: the multicast group upon which to send updates
13	#   * the host is responsible for setting the correct route
14	#   * if this entry is not present, no multicast will be sent
15	#   * this entry may be repeated
16	#   * format: ip.ad.dr.ess:port.ttl
17	multicast=241.23.45.67:11110.1
18	# filter.*: the BPF filter string for the device of interest (DOI)
19	#   XX:XX:XX:XX:XX:XX will be replaced with the MAC of the DOI
20	#   %s will be replaced with the IP of the DOI
21	filter.wire_in=ether src not XX:XX:XX:XX:XX:XX and dst not %s
22	# device.*: the name of the DOI
23	device.wire_in=eth0
24	# description.*: A textual representation of the meaning of the filter
25	#   This is not used by nightcap itself, but may be used by post-processing
26	description.wire_in=Inbound LAN traffic not destined for the radio
27	filter.radio_out=ether src XX:XX:XX:XX:XX:XX
28	device.radio_out=ath0
29	description.radio_out=Outbound MANET traffic sent by the radio
30	filter.wire_out=ether src XX:XX:XX:XX:XX:XX and src not %s
31	device.wire_out=eth0
32	description.wire_out=Outbound LAN traffic not sourced by the radio
33	filter.radio_in=ether src not XX:XX:XX:XX:XX:XX
34	device.radio_in=ath0
35	description.radio_in=Inbound MANET traffic received by the radio

As indicated on lines 1 and 2, the comment indicator follows convention and is a # symbol. Line order in the configuration file does not matter, as long as all names without a dot or period delimiter precede those with delimiters.

Line 3 provides a comma-separated list of names of filters. For every defined filter, a logfile will be created, as discussed in the comments. Various keywords also need to be detailed on a per-filter basis, as indicated lower in the configuration file. Logfiles are flushed and closed after each write, which may be destructive to "non-leveling" flash filesystems.

Line 5 provides the storage directory for the logfiles. A directory that survives reboots and has adequate storage should be chosen. nightcap will change into this directory, so it cannot be unmounted while nightcap is running.

Line 7 provides the name of the PID file. This file is mostly useful as a system administration aid.

Line 9 provides the interval between log updates. Approximately once every interval seconds, nightcap will update the on-disk logfiles. All counters reset after logging. If nightcap misses an interval, the counters will not be reset, but will instead continue to accumulate until the next time they are examined (and thereby cleared). New in 3.0: approximately once every interval seconds, nightcap will transmit one UDP packet per filter with the same counts just before resetting the counter.

Line 11 controls whether or not nightcap forks into the background. This is largely a debugging switch.

New in 3.0: Line 17 provides the multicast group upon which to transmit data. If this entry is repeated, data can be sent to more than one group, with or without different TTLs. You must always explicitly state the TTL when providing a group. Unlike the Simple SA Packet Generator, nightcap will not flood, nor can you specify a particular interface in the configuration file. nightcap will therefore obey the routing table on the host.

Lines 21, 27, 30, and 33 indicate the modified Berkeley Packet Filter syntax that nightcap will use to differentiate packets of interest. You can specify any legal BPF syntax here, plus two variable substitutions. As the comments imply, "XX:XX:XX:XX:XX:XX" will be replaced with the MAC address of the interface named by the associated "device" keyword, and "%s" will be replaced by the IP of the associated interface. There is no provision for a continuation character, so care needs to be taken so that long filter strings do not line wrap.

Lines 23, 28, 31, and 34 all correlate an interface with a filter. This is required to allow proper compilation of the associated filter strings.

Lines 26, 29, 32, and 35 all provide a textual tag for post-processing tools. nightcap ignores this text, but other software may use it.

File Formats

Since version 2.0, each log file has the same on-disk format. Logfiles are named after the names keyword in the configuration file. All integers are 4 bytes long, and in network order.

Field	Value	Notes
time	Seconds since the epoch, according to the host	It is hoped that the hosts are synchronized via GPS or otherwise have reasonably accurate clocks. No effort is made by nightcap to discipline the clock, nor will it try to "catch up" if it misses a count.
packets	The count of packets which matched the filter string since the last record.
bytes	The volume of traffic which matched the filter string since the last record.	This value is in bytes, not bits. This differs from the Real-Time Traffic Analyzer. This should be capable of handling a throughput of up to 3.4 Gbps or 429 MBps.

Network Protocol

Every interval seconds, or as nearly as possible, nightcap will transmit (via UDP) similar information to each address:port specified in the configuration file, with the relevent multicast TTL. If, for some reason, the kernel did not allow nightcap to set the multicast TTL, it will still attempt to transmit with the system default TTL (which is usually 1). If no addresses are specified, no transmission will occur.

One packet will be sent per filter. This means that the example above will trigger four packets per second.

Field	Value	Length and Notes	Offset
protocol version	Always 1	1 byte long. May change if the protocol requires revision	0
marker	Always 0x34 0x54 0x49 0x41 0x4e	5 bytes. Used to make frames more obvious in tcpdump	1
namelen	The length of the name of the filter for this data	2 bytes. This value is based upon the name of the logfile.	6
time	Seconds since the epoch, according to the host	4 bytes. It is hoped that the hosts are synchronized via GPS or otherwise have reasonably accurate clocks. No effort is made by nightcap to discipline the clock, nor will it try to "catch up" if it misses a count.	8
packets	The count of packets which matched the filter string since the last record.	4 bytes.	12
bytes	The volume of traffic which matched the filter string since the last record.	4 bytes. This value is in bytes, not bits. This differs from the Real-Time Traffic Analyzer. This should be capable of handling a throughput of up to 3.4 Gbps or 429 MBps.	16
name	The name of this filter.	Variable length. This value matches the name used to create the log filename. No data follows this in this packet.	20

nightcap 2.0

Version 2.0 of nightcap is not formally documented. Operation is identical to version 3.0, and the configuration files are backwards compatible, although a version 2.0 binary will issue warnings about unknown keywords that appeared in version 3.0 and later.

nightcap 1.0

This documents the behavior and operation of the first generation of nightcap.

Usage: nightcap [-p PIDFILE] [-f LOGF] [-r RDEV] [-e EDEV] [-d TIME] [-F]

PIDFILE is the name of the file to write the process ID to, and defaults to /var/log/nightcap.pid

LOGF is name of the binary logfile, and defaults to /var/log/nightcap.binlog

RDEV is the name of the radio device, and defaults to wlan0

EDEV is the name of the wired device, and defaults to eth0

TIME is the number of seconds between samples, and defaults to 10

The program will not fork into the background if -F is provided.

This program is a much simpler version of RTTA's pcapper. It collects only the packet and byte sizes of data flowing across interfaces of interest. The on-disk data format is:

Field	Value	Notes
time	Seconds since the epoch, according to the host	It is expected that the host clock may be quite inaccurate, so take this value with a grain of salt.
Wired Packets	The number of packets seen on the wired interface	These values are derived from the expression "sourced by a foreign MAC and not targeted at the host's Ethernet interface's IP address."
Wired Bytes	The number of bytes (not bits) seen on the wired interface
Radio Packets	The number of packets seen on the wireless interface	These values are derived from the expression "sourced with the host's wireless interface's MAC and not targeted at the host's wireless interface's IP address."
Radio Bytes	The number of bytes (not bits) seen on the wireless interface

All fields are 4 bytes long, and are stored in network byte order. All counters (other than time) reset after each log. Therefore, assuming that the host's clock runs in real time, traffic at a rate less than 3.4 Gbps (429 MBps) should not cause an overflow of the counters. At one sample every ten seconds, this will be consume about seven kilobytes per hour.

Views

Nightcap