home | help 
TCPREEN(1)		     System Manager's Manual		      TCPREEN(1)

NAME
     tcpreen - TCP stream monitoring tool

SYNOPSIS
     tcpreen  [-cdflnqv]  [-b maxbytes] [ -f format] [-F maxclients] [-m maxcon-
     nect] [ -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  connec-
	    tions.  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 automat-
	    ically.

	    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  tel-
	    net-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  inter-
	    rupted).

     -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 over-
	    written. "-" is used for stdout.

	    Multiple log files can be used (with different formats).  For  exam-
	    ple:

	    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  ex-
	    change 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 ad-
	    dress 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 178 2006-03-18 18:10:23Z remi $

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

tcpreen       $Date: 2006-03-18 20:10:23 +0200 (sam, 18 mar 2006) $   TCPREEN(1)
home | help