NAME
udptunnel - Tunnel UDP packets over a TCP connection
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]
DESCRIPTION
UDPTunnel is a small program which can tunnel UDP packets
bi-directionally over a TCP connection. Its primary purpose (and
original motivation) is to allow multi-media conferences to traverse a
firewall which allows only outgoing TCP connections.
USAGE
UDPTunnel can be run in two modes: a client mode and a server mode. The
client mode initiates the TCP connection before relaying UDP; the
server waits for an incoming connection before doing so. After the TCP
connection is established, the behavior of the two modes is identical.
If you are using UDPTunnel to traverse a firewall as discussed above,
the client would be run inside the firewall, and the server would be
run outside it.
OPTIONS
-s TCP-port
Server mode: If udptunnel is invoked with the -s option, it runs
in server mode: the server will wait for an incoming connection
on the specified TCP port, and then relay UDP to and from it."
-c TCP-addr[/TCP-port]
Client mode: If udptunnel is invoked with the -c option, it runs
in client mode: it will open a TCP connection to the specified
TCP host and port, and then relay UDP on it. The TCP port may be
omitted in this case; it will default to the same port number as
the UDP port.
-r RTP mode: In order to facilitate tunneling 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. Note that 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.
-v Verbose output: This flag turns on verbose debugging output
about UDPTunnel’s actions. It may be given multiple times. With
a single -v, information about connection establishment is
printed on UDPTunnel’s standard error stream; with a second one,
per-packet information is also shown. Note that this latter case
can produce a prodigious amount of information. If this flag is
not given, UDPTunnel will remain silent unless an error occurs.
One of the two options -c and -s must be given; if not, it is an error.
In all cases, the UDP address and port to tunnel is given after all
options. UDPTunnel will listen to this adddress for packets, and will
send received packets on this address. The address may be a multicast
address; in this 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 as a host name (e.g. conrail.cs.columbia.edu). Port
numbers must be in the range of 1 to 65535; TTLs must be in the range 0
to 255.
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. This format was proposed in early drafts of RTP for
RTP-over-TCP, but was dropped from the final specification.
KNOWN BUGS/ISSUES
UDPTunnel does not check incoming UDP packets to verify that they are
indeed coming from the address which the user specified; it 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.
For multicast, UDPTunnel turns off packet loopback, as it has no way to
distinguish its own packets it sent out from packets genuinely arriving
on the multicast group. This means that 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.)
UDPTunnel is designed to tunnel RTP-style traffic, in which
applications send and receive UDP packets to and from the same port (or
pair of ports). It does not support request/response-style traffic, in
which 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.
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.
IP version 6 is not supported.
AUTHORS
UDPTunnel was written by Jonathan Lennox <lennox@cs.columbia.edu>. It
incorporates code written by Henning Schulzrinne <hgs@cs.columbia.edu>.
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).