derrick man page

derrick -- a simple network stream recorder


derrick [-mvVh] [-i interface] [-r file] [-f expression] [-l file] [-b bytes] [-t lines]


derrick is a simple tool for recording data streams of TCP and UDP traffic. It shares similarities with other network recorders, such as tcpflow and wireshark, where it is more advanced than the first and clearly inferior to the latter.

derrick has been specifically designed to monitor application-layer communication. In contrast to other tools the application data is logged in a line-based text format. Common UNIX tools, such as grep, sed & awk, can be directly applied. Even replay of recorded communication is straight forward using netcat.

derrick supports on-the-fly compression and rotation of log files. Payloads of TCP sessions are re-assembled using libnids and can be merged or truncated. UDP payloads are logged as-is. Details of lower network layers are omitted.

Output Format

derrick outputs the monitored network traffic in a line-based text format, where each line corresponds to one recorded TCP or UDP payload. Note that TCP payloads are re-assembled and thus not necessary match the corresponding TCP datagrams.

Each line of the output has the following format:


The different fields of the output are defined as follows

This field specifies the time at which the payload has been monitored. The time is given as standard UNIX time and encoded as a floating-point number of seconds.
This field indicates the type of payload that has been recorded. U refers to a UDP payload and T refers to a TCP payload. Additionally, the beginning and end of TCP streams are marked by T+ and T-, respectively.
This field specifies the source of the payload. It is a tuple of an IP address and a port number in form of IP:PORT.
This field specifies the destination of the payload. It is a tuple of an IP address and a port number in form of IP:PORT.
The last field is the monitored payload. Non-printable characters are escaped using standard URI encoding. Each non-printable characters is replaced by %XX where XX is the character's hexadecimal ASCII number.

An example output of derrick looks as follows

05.80 T GET /index.html ...

The line shows a TCP payload recorded at time 05.80, that is, 5.8 seconds after new year's eve of 1970 ;). The payload is directed to port 80 (HTTP) and shows the beginning of a typical HTTP GET request. Note that whitespaces are not escaped in the payload and thus each line may seemingly have more than 5 fields. However, starting from the 5th field all following white-spaces are part of the payload.


derrick supports the following command-line options which can be used to control the recording of network traffic.

-i interface
Record network traffic from this interface. On Linux systems with 2.2 or later kernels, an interface argument of "any" can be used to capture packets from all interfaces.
-r file
Read network traffic from a dump file in pcap format. Dump files can be created using tcpdump.
-f expression
Filter network traffic using a filter expression. Only packets that match the expression will be recorded. Consult the man page of tcpdump for a description of filter expressions.
-l file
Write output to a compressed log file instead of stdout. This option can be used when derrick runs in the background. The log file will be rotated if a certain number of lines have been logged, see -t.
-b bytes
Record only the first bytes of each TCP stream. The number of bytes is computed from incoming and outgoing TCP payloads.
Merge consecutive TCP payloads in the same direction. This options comes handy if protocol messages are split over multiple TCP payloads.
-t lines
Rotate the log file after the given number of lines.
Increase the verbosity of derrick during recording.
Print a brief help screen.
Print a version and copyright string.


derrick 0.3 2013-01-21