.\" ***********************************************************************
.\" *  Copyright (C) 2002-2004 Remi Denis-Courmont.                       *
.\" *  This program is free software; you can redistribute and/or modify  *
.\" *  it under the terms of the GNU General Public License as published  *
.\" *  by the Free Software Foundation; version 2 of the license.         *
.\" *                                                                     *
.\" *  This program is distributed in the hope that it will be useful,    *
.\" *  but WITHOUT ANY WARRANTY; without even the implied warranty of     *
.\" *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               *
.\" *  See the GNU General Public License for more details.               *
.\" *                                                                     *
.\" *  You should have received a copy of the GNU General Public License  *
.\" *  along with this program; if not, you can get it from:              *
.\" *  http://www.gnu.org/copyleft/gpl.html                               *
.\" ***********************************************************************
.TH "TCPREEN" "1" "$Date: 2006-03-18 20:10:23 +0200 (sam, 18 mar 2006) $" "tcpreen" "System Manager's Manual"
.SH NAME
tcpreen \- TCP stream monitoring tool
.SH SYNOPSIS
.BR "tcpreen" " [" "-cdflnqv" "] [" "-b maxbytes" "] ["
.BR "-f format" "] [" "-F maxclients" "] [" "-m maxconnect" "] ["
.BR "-o logfile" "] [" "-u user" "] [" "-a bindaddress" "] ["
.BR "-s servername" "] [" "-p proto1/proto2" "]"
serverport [localport]

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

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

.SH OPTIONS
.TP
.BR "\-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.

.TP
.BR "\-b bytecount" " or " "\-\-bytes bytecount"
Limit the length of a TCP session to
.B bytecount
bytes. If a session exceeds this quantity, it will be closed on the
next data packet boundary.

.TP
.BR "\-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.

.RB "Use " "\-a address"  " to specify the client address to connect to."

.TP
.BR "\-d" " or " "\-\-daemon"
.RI "Turn on " "daemon mode" "."
.RB "When this option is selected, " "TCPreen" " will run in the background"
.RB "and send informations to " "syslog" " instead of the console."
.RI "This enables " "quiet mode" " and " "multiple clients mode" " "
automatically.

You will probably want to use option -F as well.

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

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

.TP
.BR "\-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.

.TP
.BR "\-h" " or " "\-\-help"
Display some help and exit.

.TP
.BR "\-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
.B TCPreen server
address. An optionnal listening interface address can be specified.

.TP
.BR "\-m conn_num" " or " "\-\-maxconn conn_num"
.RB "Handle " "conn_num" " consecutive client connections before exiting."
When this option is not used, the program will run forever (until interrupted).

.TP
.BR "\-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.

.TP
.BR "\-o logfile" " or " "\-\-output logfile"
Save data to file
.BR "logfile" "."
If it already exists, it will be overwritten. "-" is used for
.IR "stdout" "."

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

tcpreen -f hex -o hexafile.log -f C -o file.log smtp

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

.TP
.BR "\-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:
.BR "tcp" " (TCP over IPv4), " "tcp6" " (TCP over IPv6) and " "unix" " or "
.BR "local" " (Unix interprocess streams)."
.RB "By default, " "tcp" " is used."


.TP
.BR "\-q" " or " "\-\-quiet"
.RI "Turn on " "quiet mode" ": "
.RI "Do not write anything on the standard output (" "stdout" ")."

.TP
.BR "\-s hostname" " or " "\-\-server hostname"
Connect to the specified server instead of the local host which is used by
default.

.TP
.BR "\-u user" " or " "\-\-user user"
When run as super-user, drop privilege and set UID to that of
.B user
(it must be a valid username). That is highly recommended if
.B 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.

.TP
.BR "\-v" " or " "\-\-verbose"
Increase program verbosity. This can be cumulated.

.TP
.BR "\-V" " or " "\-\-version"
Display program version and license and exit.

.SH DIAGNOSTICS
These are common problems:

Nothing happens:
.RS
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.

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

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

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

.RB "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).

.SH "SEE ALSO"
nc(1), nc6(1), tcpflow(1), tcpdump(8), tethereal(1)

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

$Id: tcpreen.1 178 2006-03-18 18:10:23Z remi $

http://www.simphalempin.com/dev/tcpreen/