tcpreen - TCP stream monitoring tool

tcpreen [-cCdfHlLnNqRSv] [-b maxbytes] [-F maxclients] [-m[maxconnect]] [-o logfile] [ -u user/UID] [-a bindaddress] [-s servername ] [-p proto1/proto2] serverport [localport]

TCPreen monitors and let the user analyse data transmitted between a client and a server via a TCP connection. It focuses on the data stream and operates at the software layer, not on lower level transmission protocols as a packet sniffer does.

It works like a bridge between a server and a client that communicates through a TCP session, and can display or save data that is sent either way.

In standard mode, TCPreen opens a listening socket (on port localport which is dynamically allocated by default), and waits until a client connects to it. Then, it connects to the server (on port serverport) and forwards data between each hosts until the session is closed by either side.

-a interface or --bind interface

Specify an interface that will be used to listen for client connections. By default, all network interfaces are used.

-b bytecount or --bytes bytecount

Limit the length of a TCP session to bytecount bytes. If a session exceeds this quantity, it will be closed on the next data packet boundary.

-c[hostname] or --connect[=hostname]

Connect to the specified client instead of waiting for the client to connect. This is meant to be used in a few very particular cases only. If no hostname is specified, TCPreen will try to connect to the local host.

This cannot be used in conjunction with -a or --bind.

-C or --C

Encode log file output like C source file character strings. This is the default log format.

-d or --daemon

Turn on daemon mode. When this option is selected, TCPreen will run in the background and send informations to syslog instead of the console. This enables quiet mode and multiple clients mode automatically.

Currently, you will probably want to use option -F as well.

NOTE: if you turn this feature on, log files will be created from the root directory, not from the current one. See daemon(3) for more details.

-f or --force

Enforce unusual potentially dangerous options combination. Otherwise, TCPreen will print a warning message on stderr and exit.

-F maxclients or --fork maxclients

Enable multi-process operation. Several session can be treated simultaneously with help from fork() Unix system call. No more than maxclients sessions will be allowed at the same time.

This option should disappear someday.

-h or --help

Display some help and exit.

-H or --hex

Encode log file output in hexadecimal. This is very convenient for monitoring of binary communications. Readable ASCII text is also displayed for ease of analyse.

-l or --listen

Listen for the "server" instead of connecting to it. This can be used by advanced users to run a human brain-powered server by telnet-ing to TCPreen server address. An optionnal listening interface address can be specified.

-L or --syslog

Use syslog facility. This will work in daemon mode only.

-m[maxconnect] or --multi=[maxconnect]

Turn on multiple client mode: Handle multiple consecutive client connections. If maxconnect is specified, TCPreen will exit after processing maxconnect TCP session. Otherwise, it will run forever.

When this option is not used, only one connection is processed before exiting.

-n or --numeric

Disable reverse DNS lookup and service name resolution. Node names and port numbers will appear in numeric form.

-N or --null

Do not include data in log file. Only record host addresses.

-o logfile or --output logfile

Save data to file logfile. If it already exists, it will be overwritten. "-" is used for stdout.

Multiple log files can be used (with different formats). For example:

tcpreen -H -o hexafile.log -C -o file.log smtp

will save hexafile.log in hexadecimal and file.log in C encoding.

-p or --protocol

Specifies which network protocol(s) is/are going to be used. If a single protocol name is specified, it will be used both ways. Two different protocols can be used on each side by separating them with a slash like this: 'tcp/tcp6'. The first protocol will then be used to communicate with the server, the last one will be used to exchange data with the client.

The following protocols are currently recognized: tcp (TCP over IPv4), tcp6 (TCP over IPv6) and any (both tcp and tcp6).

-q or --quiet

Turn on quit mode: Do not write anything on the standard output (stdout).

-R or --raw

Do not encode log file. Some people might finds this more convenient for monitoring 7-bit clean protocols, but this is error prone.

-s hostname or --server hostname

Connect to the specified server instead of the local host which is used by default.

-S or --strip

Replace non-printable characters with dots in log file.

-u user, --uid user or --user user

When run as super-user, drop privilege and set UID to user (it can be a valid UID or username). That is highly recommended if TCPreen is to be bound to a reserved port, which only root can bind on Unix systems.

You must be root to use this option.

-v or --verbose

Increase program verbosity. This can be cumulated.

-V or --version

Display program version and license and exit.

These are common problems:

Nothing happens: The client is communicating with the server correctly, but TCPreen stays quiet. Make sure you told the client to connect to TCPreen address rather than the actual server address.

Make sure you have enabled verbose mode.

Strange port names: Have a look at /etc/services and you will realize what this means. Alternatively, you may want to use -n.

Log files get strange names in multi-process mode. This will be fixed someday.

Signals are not handled in daemon mode.

Remi Denis-Courmont <rdenis at simphalempin.com>

netcat(1), tcpcat(1), tcpflow(1), telnet(1)