NAME
tcpreen - 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]
DESCRIPTON
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).
SEE ALSO
nc(1), nc6(1), tcpflow(1), tcpdump(8), tethereal(1)
AUTHOR
Remi Denis-Courmont <rdenis at simphalempin.com>
$Id: tcpreen.1,v 1.29 2004/06/26 19:58:06 rdenisc Exp $
http://www.simphalempin.com/dev/tcpreen/