Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

       tcpreen - TCP stream monitoring tool

       tcpreen	[-cdflnqv] [-b maxbytes] [ -f format] [-F maxclients] [-m max-
       connect]	[ -o logfile] [-u user]	[-a bindaddress] [ -s servername]  [-p
       proto1/proto2] serverport [localport]

       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

       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 ei-
       ther side.

       -a interface, --accept interface	or --bind interface
	      Specify an interface that	will be	used to	listen for client con-
	      nections.	 By default, all network interfaces are	used.

       -b bytecount or --bytes bytecount
	      Limit  the length	of a TCP session to bytecount bytes. If	a ses-
	      sion 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

	      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  dae-
	      mon(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 con-
	      nections addresses), password (basic  password  capture,	unfin-
	      ished  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 in-
	      terface 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  (un-
	      til 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 ex-

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

	      will  save  hexafile.log in hexadecimal and file.log in C	encod-

       -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

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

       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.

       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 re-
       served 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).

       nc(1), nc6(1), tcpflow(1), tcpdump(8), tethereal(1)

       Remi Denis-Courmont <rdenis at>

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

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


Want to link to this manual page? Use this URL:

home | help