TCPREEN(1)

NAME
tcpreen - TCP stream monitoring tool

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

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

OPTIONS

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

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.

BUGS
Log files get strange names in multi-process mode. This will be fixed someday. Signals are not handled in daemon mode.

AUTHOR
Remi Denis-Courmont <rdenis at simphalempin.com>

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