Copyright 2008-2018 Pavel V. Cherenkov (pcherenkov@gmail.com)

This file is part of udpxy.

udpxy is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation, either version 3 of the License, or

(at your option) any later version.

udpxy is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with udpxy. If not, see http://www.gnu.org/licenses/.

Summary

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 is released under GPL v.3

Project status

udpxy has not been extended or supported for 4+ years, having been replaced by Gigapxy - a superior enterprise-oriented product. Please see more info at http://gigapxy.com, thank you.

Building and installing

Untar the *.tgz source distribution into a directory of your choice by running tar -xzvf udpxy.X.Y-ZZ.tgz or gzip -dc udpxy.X.Y-ZZ.tgz | tar -xvf -

Make sure GNU make and gcc are available (gcc 3.x and up should work, lower versions are not guaranteed to build the source correctly); for compilers other than gcc alterations to Makefile might be needed.

Running 'make' without a target will build the 'release' version of udpxy (no asserts, no debug symbols, verbose mode on).

Other make targets are: debug (asserts, debug symbols, verbose mode on); lean (no asserts, no debug symbols, verbose mode off); rdebug (same as 'release' but with debug symbols); ldebug (same as 'lean' but with debug symbols);

Once the make has succeeded, the udpxy executable file could be copied to a location of one's choice and run from there - no additional installation steps are required.

udpxy can be started with a number of configuration parameters, such as listening address/port, multicast interface name, etc. A brief usage summary is provided when udpxy is invoked from command line without parameters.

HTTP commands

udpxy responds to HTTP (GET) commands to receive data from a dedicated multicast group and forward it to the initiating (HTTP) connection.

The command to relay traffic is in the format as below:

http://<address>:<port>/<cmd>/[src_address@]<mgroup_address><sep><mgroup_port>/

[SEP] ::= :|%|~|+|-|^ i.e: http://ip:port/cmd/mgroup_address:mgroup_port/ http://ip:port/cmd/mgroup_address%mgroup_port/ http://ip:port/cmd/mgroup_address~mgroup_port/ ...... http://ip:port/cmd/mgroup_address^mgroup_port/

are acceptable and should all work in the same manner.

cmd ::= udp | rtp

where ip and port match the listening address/port combination of udpxy, and [src_address@]mgroup_address:mgroup_port identify the multicast group (and optional source) to subscribe to.

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

udpxy will start a 'client' process for each new relay request as long as their number would not exceed a pre-set maximum (see usage summary).

udpxy also supports a few additional HTTP requests, such as:

http://address:port/status/ - to display basic daemon's statistics http://address:port/restart/ - to close all active connections and restart

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 so that media players not recognizing RTP on TCP could still play back the stream.

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

Recording MPEG traffic

udpxy (in builds >0.33) 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 by a symbolic link (named udpxrec) to the udpxy executable (NB: do not rename udpxy executable).

udpxrec creates MPEG files encapsulating MPEG-TS segments; most media players will NOT play such files; 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 PS file can be played back by most media players.

Portability

udpxy was written to run on 'POSIX-compliant' systems; so far all builds have been tested to build and run on Linux 2.4, 2.6, 3.x (IA32, ARM) and some (but not all) on HP-UX 11.11 (PA-RISC 1.1, 2.0w).

Build 12 of version 1.0 (Chipmunk) was ported to compile under FreeBSD 7.1 using GNU make 3.8; later builds have been tested to compile under later versions of FreeBSD (up to 9.0);

Certain builds have been ported to build under cygwin; cygwin is NOT considered to be a fully supported platform yet there is an ongoing effort to make udpxy run on it as well.

Environment variables

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 the 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 value set by -B), default=1 (sync); UDPXY_DSOCKBUF_NOSYNC - do not sync outbound (TCP) socket's buffer size (with 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 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, keep reading data until the buffer (-B size) is full, default=disabled; UDPXY_PAUSE_MSEC - allow only N milliseconds of reading data when blocked on a write. UDPXY_CONTENT_TYPE - specify custom Content-Type in HTTP responses.

--EOF--