NAME

udpxy - a UDP-to-HTTP multicast traffic relay daemon.

SYNOPSIS

udpxy [-vTS] [-a <listenaddr>] [-m <mcast_ifc_addr>] [-c <clients>] [-l <logfile>] [-B <sizeK>] [-R <msgs>] [-H <sec>] [-n <nice_incr>] [-M <sec>] -p <port>

DESCRIPTION

udpxy is a UDP-to-HTTP multicast traffic relay daemon: it forwards UDP traffic from a given multicast subscription to the requesting HTTP client.

udpxy listens (on a dedicated address/port) for HTTP requests issued by clients. A client request should be structured as:

http://{address}:{port}/{cmd}/{mgroup_address}[SEP]{mgroup_port}

[SEP]: :|%|~|+|-|^
{cmd}: udp|rtp

where address and port match the listening address/port combination of udpxy, and mgroup_address:mgroup_port identify the multicast group/channel to subscribe to.

udp: udp command will have udpxy probe for known types of payload (such as MPEG-TS and RTP over MPEG-TS);
rtp: rtp command makes udpxy assume RTP over MPEG-TS payload, thus skipping the probes.

udpxy will start a separate client process for each new relay request (within the specified limit on active clients). The client process will relay/forward all network traffic received (via a UDP socket) from the specified multicast group to the requesting HTTP connection.

udpxy also supports a few administrative requests:

status

http://address:port/status/ to send back an HTML page with daemon status and client statistics.

restart

http://address:port/restart/ to close all active connections and restart.

EXAMPLES

http://192.168.0.12:5056/udp/224.0.2.26:24012

http://192.168.0.12:5056/rtp/224.0.2.26:24012

http://192.168.0.15:5056/rtp/224.0.2.26^24055

http://192.168.0.15:5056/status/

OPTIONS

udpxy accepts the following options:

-v: Enable verbose output [default = disabled].
-S: Enable client statistics [default = disabled].
-T: Do NOT run as a daemon [default = daemon if root].
-a <listenaddr>: IPv4 address/interface to listen on [default = 0.0.0.0].
-m <mcast_ifc_addr>: IPv4 address/interface of (multicast) source [default = 0.0.0.0].
-c <clients>: Maximum number of clients to accept [default = 3, max = 5000].
-l <logfile>: Log output to file [default = stderr].
-B <sizeK>: Buffer size (65536, 32Kb, 1Mb) for inbound (multicast) data [default = 2048 bytes].
-R <msgs>: Maximum number of messages to buffer (-1 = all) [default = 1].
-H <sec>: Maximum time (in seconds) to hold data in a buffer (-1 = unlimited) [default = 1].
-n <nice_incr>: Nice value increment [default = 0].
-M <sec>: Renew multicast subscription every M seconds (skip if 0) [default = 0].
-p <port>: Port to listen on.

PAYLOAD TYPES AND HANDLING

udpxy recognizes MPEG-TS and RTP over MPEG-TS payloads within relayed packets; if udpxy encounters RTP payload it automatically 'translates' it to MPEG-TS (by stripping RTP headers) so that media players not recognizing RTP could still play back the stream.

So far, no translation is performed for other payload types.

RECORDING MPEG TRAFFIC

udpxy includes functionality to record captured traffic as raw MPEG-TS stream into a file. This functionality is enabled through udpxrec: a bundled-in application that is linked together with udpxy (as one executable).

udpxrec is invoked via a symbolic link (named udpxrec) to the udpxy executable (i.e. do not rename udpxy executable).

udpxrec creates MPEG files encapsulating MPEG-TS segments; certain media players will NOT play such files; in order to make them playable the stream must be transcoded to MPEG-PS; vlc 'knows' how to do such transcoding, here is a command-line example:

vlc input-ts.mpg --sout="#std{access=file,mux=ps,dst=out-ps.mpg}"

The resulting MPEG-PS file can be played back by most media players.

ENVIRONMENT

udpxy utilizes the following environment variables to compliment its command-line options; the variables are considered for the options that most people would not need to change too often (or simply inconvenient to use from the command line).

NB: If there is a command-line switch that would intersect in functionality with an environment variable, the switch always has higher priority.

UDPXY_RCV_TMOUT: timeout (sec) on the inbound data stream (multicast), default=5;
UDPXY_DHOLD_TMOUT: timeout (sec) to hold buffered data before sending/flushing to client(s), default=1;
UDPXY_SREAD_TMOUT: timeout (sec) to read from the listening socked (handling HTTP requests), default=1;
UDPXY_SWRITE_TMOUT: timeout (sec) to write to the listening socked (handling HTTP requests), default=1;
UDPXY_SSEL_TMOUT: timeout (sec) to select(2) in server loop (unused if pselect(2) is employed), default=30;
UDPXY_LQ_BACKLOG: size of the listener socket's backlog, default=16;
UDPXY_SRV_RLWMARK: low watermaek on the receiving (m-cast) socket, default=0 (not set);
UDPXY_SSOCKBUF_NOSYNC: do not sync inbound (UDP) socket's buffer size (with the value set by -B), default=1 (sync);
UDPXY_DSOCKBUF_NOSYNC: do not sync outbound (TCP) socket's buffer size (with the value set by -B), default=1 (sync);
UDPXY_TCP_NODELAY: disable Nagle algorithm on the newly accepted socket (faster channel switching), default=1;
UDPXY_HTTP200_FTR_FILE: append contents of the given text file to the HTTP 200 response, default=none;
UDPXY_HTTP200_FTR_LN: append the text (line) to the HTTP 200 response, default=none;
UDPXY_ALLOW_PAUSES: if blocked on a write(2), keep reading data until the buffer (-B <sizeK>) is full, default=disabled;
UDPXY_PAUSE_MSEC: allow only N milliseconds of reading data when blocked on a write(2).
UDPXY_CONTENT_TYPE: specify custom Content-Type in HTTP responses.

AUTHORS

Pavel V. Cherenkov and all the good people who submitted patches or otherwise contributed to the project.