udpxy man page

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.

See Also

udpxrec(1)

Referenced By

udpxrec(1).

November 17, 2012 Version 1.0 udpxy manual page