UDPTunnel(1)

💖 UDPTunnel — the net manual, section 1 💖

okay bestie, sit DOWN, because we're about to tunnel some UDP packets through a TCP connection and it's gonna be ✨immaculate✨. this is udptunnel from the <rainbow>net</rainbow> manual, section 1. let's get into it 🫶

---

🌸 NAME 🌸

udptunnel — tunnel UDP packets over a TCP connection. that's it, that's the whole vibe. 🦋

---

🎀 SYNTAX 🎀

udptunnel -s TCP-port [-r] [-v] UDP-addr/UDP-port[/ttl]
udptunnel -c TCP-addr[/TCP-port] [-r] [-v] UDP-addr/UDP-port[/ttl]

look at those two little glow-ups. one for server mode, one for client mode. pick your fighter 💅

---

💜 DESCRIPTION 💜

UDPTunnel is a small program — like, small small, she's not doing too much — and what she does is tunnel UDP packets bi-directionally over a TCP connection. literally both directions at once, no cap.

her primary purpose (and her original motivation, her origin story if you will 👑) is to let multi-media conferences sneak across a firewall that only allows outgoing TCP connections. the firewall thinks it's just some innocent TCP traffic. it is not. 🧚

---

✨ USAGE ✨

UDPTunnel runs in two modes, bestie: client mode and server mode.

• client mode — initiates the TCP connection before relaying UDP. she makes the first move, main character energy fr fr 💅
• server mode — waits for an incoming connection before doing the relaying. she's patient. she's iconic.

once the TCP connection is established, the two modes behave identically — like twins who dressed the same on purpose. 😭

so if you're using UDPTunnel to traverse a firewall (the whole point, remember), the client would be run inside the firewall, and the server would be run outside it. that's the setup, that's the whole slay. 🔥

---

💅 OPTIONS 💅

• -s TCP-port — Server mode. if udptunnel gets invoked with -s, she's in server mode: the server waits for an incoming connection on the specified TCP port, and then relays UDP to and from it. she's standing at the door like "come through then 🫶"
• -c TCP-addr[/TCP-port] — Client mode. if udptunnel gets invoked with -c, she's in client mode: she opens a TCP connection to the specified TCP host and port, then relays UDP on it. and here's the cute part — the TCP port may be omitted, and it'll default to the same port number as the UDP port. matching set, obviously 💖
• -r — RTP mode. to help tunnel both RTP and RTCP traffic for a multi-media conference, this sets up relays on two consecutive TCP and UDP ports. all specified port numbers in this case must be even. ⚠️ and listen — both the client and the server must use the -r flag for this to work; the server will not begin relaying packets until both its connections have been established. no half-sending. periodt.
• -v — Verbose output. this turns on verbose debugging output about UDPTunnel's actions, and it may be given multiple times. with a single -v, info about connection establishment gets printed on UDPTunnel's standard error stream; with a second one, per-packet information is also shown. > heads up: that second one can produce a prodigious amount of information. like, you will be scrolling. 😭 if this flag is not given, UDPTunnel stays silent unless an error occurs. a quiet queen.

🚨 one of the two options -c and -s must be given; if not, it is an error. non-negotiable, bestie.

in all cases, the UDP address and port to tunnel is given after all options. UDPTunnel will listen to this address for packets, and will send received packets on this address. 💫

the address may be a multicast address — in which case a multicast TTL should be specified, and tunneled packets will be sent with this TTL.

all addresses, TCP and UDP, may be specified either as:

• an IPv4 dotted-quad address (e.g. 224.2.0.1), or
• a host name (e.g. conrail.cs.columbia.edu).

and the numbers, the sacred numbers:

• port numbers must be in the range 1 to 65535
• TTLs must be in the range 0 to 255

that's the range check, that's the rules, don't test her 🌈

---

🦋 PACKET FORMAT 🦋

the packets are sent on TCP using the obvious, simple format: a sixteen-bit length field, in network byte order, precedes each data packet. clean. minimal. no notes. ✨

fun fact for the lore girlies: this format was proposed in early drafts of RTP for RTP-over-TCP, but was dropped from the final specification. so she's vintage, she's a throwback, she's retro 💀

---

💀 KNOWN BUGS/ISSUES 💀

okay bestie, this is the part where we hold hands and read the fine print together. 🫶

• UDPTunnel does not check incoming UDP packets to verify that they are indeed coming from the address which the user specified; she binds to INADDR_ANY, and accepts any UDP packet arriving on the specified port. > this could potentially allow denial-of-service or spoofing attacks. 😭 if two or more -v options are given, per-packet identification will be printed of each packet's source address as it is received, allowing such a situation to be diagnosed. so like, verbose mode is your security camera fr fr.
• for multicast, UDPTunnel turns off packet loopback, because she has no way to distinguish her own packets that she sent out from packets genuinely arriving on the multicast group. this means: if you are tunneling traffic from or to a multicast group, both ends of UDPTunnel must be run on different hosts than any member of the group. (in general, the only way to distinguish looped packets from packets genuinely received from other applications on the local host is with application-layer labeling, as RTP does.) so, like, separate hosts, no exceptions 💅
• UDPTunnel is designed to tunnel RTP-style traffic, where applications send and receive UDP packets to and from the same port (or pair of ports). she does not support request/response-style traffic — the kind where a client request is sent from a transient port X to a well-known port Y, and the server's response is returned from port Y to port X. not her genre, sorry babe. 🙈
• UDPTunnel deliberately ignores "Connection Refused" errors on the UDP port, clearing the socket error state, so that a tunnel may be set up before conferencing tools are started on both ends. > this may mean that a mis-typed UDP address or port is not recognized, as no error is printed. 🙃 if two or more -v options are given, a diagnostic will be printed whenever the error state is cleared from the socket.
• once one endpoint of a tunnel is taken down (closing the socket), the other one exits as well; to re-establish the tunnel, UDPTunnel must be restarted on both sides. they go down together, they come back together. ride or die 😭
• IP version 6 is not supported. that's it. that's the sentence. IPv4 only bestie 💀

---

👑 AUTHORS 👑

UDPTunnel was written by Jonathan Lennox <lennox@cs.columbia.edu>. she also incorporates code written by Henning Schulzrinne <hgs@cs.columbia.edu>. two legends, one tunnel 🫶

this manual page was written by Thomas Scheffczyk <thomas.scheffczyk@verwaltung.uni-mainz.de>, for the Debian GNU/Linux system (but may be used by others). so generous, so giving 💖

---

and that's the whole page, bestie!! this was UDPTunnel, version 1.1, from the <rainbow>net</rainbow> manual, lovingly brought to you by Jonathan Lennox — and remember, if a firewall only lets you out through TCP, just tunnel your UDP through it like the absolute icon you are. slay, stay hydrated, and check your port numbers 💅✨🎀🦋💖