tcpreen - Man Page

TCP stream monitoring tool

Synopsis

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

TCPreen monitors and let the user analyse data transmitted between clients and servers via TCP connections. It focuses on the data stream and operates at the software layer, not on lower level transmission protocols as a packet sniffers do.

It works like a bridge between a server and clients that communicates through TCP sessions, 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.

Options

-a interface, --accept 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 or --connect

Connect to the specified client instead of waiting for the client to connect. This is meant for expert users who know what they are doing only. If no hostname is specified, TCPreen will try to connect to the local host.

Use -a address to specify the client address to connect to.

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

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 logformat or --format logformat

Selects a format for output. Supported formats includes: C (C source strings-like encoding), hex (hexadecimal data dump), count (write quantities of data), null (only displays new connections addresses), password (basic password capture, unfinished yet), raw (write data as is, even if it is not 7-bit clean), strip (replace non printable characters with dots).

-F nproc or --fork nproc

Specifies the maximum number of sessions that can be treated at the same time. By default, only one session is allowed at a time not so as to keep the program output easy to read.

-h or --help

Display some help and exit.

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

-m conn_num or --maxconn conn_num

Handle conn_num consecutive client connections before exiting. When this option is not used, the program will run forever (until interrupted).

-n or --numeric

Disable reverse DNS lookup and service name resolution. Node names and port numbers will appear in numeric form. This option will speed up connections a little.

-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 -f hex -o hexafile.log -f 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 unix or local (Unix interprocess streams). By default, tcp is used.

-q or --quiet

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

-s hostname or --server hostname

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

-u user or --user user

When run as super-user, drop privilege and set UID to that of user (it must be a valid 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.

Diagnostics

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.

Security

tcpreen requires root privileges to be bound to a reserved TCP port (under 1024). If you really need to do so, you may run tcpreen Set-UID root. In such circumstances, you must ensure that only trustworthy users can run tcpreen, as it could be used to divert traffic to any reserved ports on the system.

tcpreen will automatically drop privileges as soon as it has allocated its listening socket(s) to limit exposure. Log files are always created with the default permission of the current user.

Care should be taken when using tcpreen as it could be used to access your network or system from the outside (that is why it will normally refuse to run as root).