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

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