TCPREEN(1)

🦋 TCPREEN(1) 🦋

okay bestie, welcome to tcpreen, from the System Manager's Manual section. it's a whole vibe and it's about to be your new fave. sit down, grab a strawberry 🍓, let's go.

---

🌸 NAME 🌸

tcpreen — TCP stream monitoring tool. literally what it says on the tin. 👑

---

💫 SYNOPSIS 💫

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

---

✨ DESCRIPTION ✨

so. TCPreen monitors data flying back and forth between clients and servers over TCP connections, and lets you analyse it. 🕵️‍♀️ it's hyper-fixated on the data stream itself and it works at the software layer — it does not mess with lower level transmission protocols the way a packet sniffer does. different lane, different energy.

it's basically a bridge between a server and the clients talking through TCP sessions, and it can display or save the data going either way. both directions, no cap. 💅

in standard mode, TCPreen opens a listening socket — on port localport, which is dynamically allocated by default — and just waits there, patiently, until a client connects to it. then it connects to the server (on port serverport) and forwards data between each hosts until the session gets closed by either side. iconic behaviour tbh. 🫶

---

🎀 OPTIONS 🎀

• -a interface, --accept interface, --bind interface — tell it which interface to listen on for client connections. by default it uses all network interfaces, so it's got range. 🌈
• -b bytecount, --bytes bytecount — caps the length of a TCP session at bytecount bytes. if a session goes over that, it gets closed on the next data packet boundary. not immediately, bestie — on the boundary. remember that. ⭐
• -c, --connect — connect to the specified client instead of waiting around for the client to come to you. this is for expert users who know what they're 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, --daemon — daemon mode, slay. TCPreen runs in the background and sends informations to syslog instead of the console. this automatically turns on quiet mode and multiple clients mode.

you'll probably want to use option -F as well. just saying. 🙈

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. that's the tea. ☕

• -f logformat, --format logformat — picks a format for the output. the supported formats include: 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). pick your fighter. ✨
• -F nproc, --fork nproc — sets the max number of sessions that can be treated at the same time. by default only one session at a time is allowed, not so as to keep the program output easy to read. one at a time, focused, main character energy. 💅
• -h, --help — display some help and exit. we love a quick exit. 🚪
• -l, --listen — listen for the "server" instead of connecting to it. advanced users can use this 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, --maxconn conn_num — handle conn_num consecutive client connections before exiting. if you don't use this option, the program will run forever (until interrupted). forever-ever? forever-ever. 😭
• -n, --numeric — disables reverse DNS lookup and service name resolution. node names and port numbers show up in numeric form. this speeds up connections a little. speed. 🏎️
• -o logfile, --output logfile — save data to file logfile. if it already exists, it will be overwritten — gone, deleted, ghosted. "-" 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. two files, two formats, one legend. 🌈

• -p, --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. order matters, bestie. 📋

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, --quiet — quiet mode: do not write anything on the standard output (stdout). shhh. 🤫
• -s hostname, --server hostname — connect to the specified server instead of the local host, which is used by default. 🖥️
• -u user, --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, --verbose — increase program verbosity. this can be cumulated. stack it, layer it, make it loud. 📢
• -V, --version — display program version and license and exit. 🏷️

---

🩺 DIAGNOSTICS 🩺

these are the common problems, so you know what's up:

• 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. mystery solved. 🔍

---

🔒 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. 💀 that's not a vibe, that's a warning.

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). be safe out there. 🫶

---

👀 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/

---

and that's the whole page, bestie. 🎀 this one came from the tcpreen source, version stamp $Date: 2006-03-18 20:10:23 +0200 (sam, 18 mar 2006) $, and yes, it's a TCPREEN(1) situation. thanks for reading, go monitor something responsibly. 💅✨🦋