1#
2# Copyright 2008-2012 Pavel V. Cherenkov (pcherenkov@gmail.com)
3#
4#  This file is part of udpxy.
5#
6#  udpxy is free software: you can redistribute it and/or modify
7#  it under the terms of the GNU General Public License as published by
8#  the Free Software Foundation, either version 3 of the License, or
9#  (at your option) any later version.
10#
11#  udpxy is distributed in the hope that it will be useful,
12#  but WITHOUT ANY WARRANTY; without even the implied warranty of
13#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14#  GNU General Public License for more details.
15#
16#  You should have received a copy of the GNU General Public License
17#  along with udpxy.  If not, see <http://www.gnu.org/licenses/>.
18#
19
20Summary
21--------------
22
23udpxy is a UDP-to-HTTP multicast traffic relay daemon:
24it forwards UDP traffic from a given multicast subscription
25to the requesting HTTP client.
26
27udpxy is released under GPL v.3
28
29Building and installing
30--------------
31
32Untar the *.tgz source distribution into a directory of your choice by
33running
34        tar -xzvf udpxy.X.Y-ZZ.tgz
35    or
36        gzip -dc udpxy.X.Y-ZZ.tgz | tar -xvf -
37
38Make sure GNU make and gcc are available (gcc 3.x and up should work, lower
39versions are not guaranteed to build the source correctly); for compilers
40other than gcc alterations to Makefile might be needed.
41
42Running 'make' without a target will build the 'release' version of
43udpxy (no asserts, no debug symbols, verbose mode on).
44
45Other make targets are:
46    debug (asserts, debug symbols, verbose mode on);
47    lean  (no asserts, no debug symbols, verbose mode off);
48    rdebug (same as 'release' but with debug symbols);
49    ldebug (same as 'lean' but with debug symbols);
50
51Once the make has succeeded, the udpxy executable file could be
52copied to a location of one's choice and run from there - no additional
53installation steps are required.
54
55udpxy can be started with a number of configuration parameters,
56such as listening address/port, multicast interface name, etc.
57A brief usage summary is provided when udpxy is invoked from command line
58without parameters.
59
60HTTP commands
61--------------
62
63udpxy responds to HTTP (GET) commands to receive data from
64a dedicated multicast group and forward it to the initiating (HTTP)
65connection.
66
67The command to relay traffic is in the format as below:
68
69http://address:port/cmd/mgroup_address[SEP]mgroup_port/
70
71[SEP] ::= :|%|~|+|-|^
72i.e:
73    http://ip:port/cmd/mgroup_address:mgroup_port/
74    http://ip:port/cmd/mgroup_address%mgroup_port/
75    http://ip:port/cmd/mgroup_address~mgroup_port/
76    ......
77    http://ip:port/cmd/mgroup_address^mgroup_port/
78
79are acceptable and should all work in the same manner.
80
81cmd ::= udp | rtp
82
83where ip and port match the listening address/port combination of udpxy,
84and mgroup_address:mgroup_port identify the multicast group to subscribe to.
85
86Using 'udp' command will instruct udpxy to probe for known types of payload
87(such as MPEG-TS and RTP over MPEG-TS); using 'rtp' makes udpxy assume RTP
88over MPEG-TS payload, thus skipping the probes.
89
90udpxy will start a 'client' process for each new relay request as long as
91their number would not exceed a pre-set maximum (see usage summary).
92
93udpxy also supports a few additional HTTP requests, such as:
94
95http://address:port/status/  - to display basic daemon's statistics
96http://address:port/restart/ - to close all active connections and restart
97
98Payload types and handling
99--------------
100
101udpxy recognizes MPEG-TS and RTP (over MPEG-TS) payloads within relayed packets;
102if udpxy encounters RTP payload it automatically 'translates' it to MPEG-TS so that
103media players not recognizing RTP on TCP could still play back the stream.
104
105So far, no translation is performed for other payload types.
106
107Recording MPEG traffic
108--------------
109udpxy (in builds >0.33) includes functionality to record captured traffic as
110raw MPEG-TS stream into a file. This functionality is enabled through udpxrec:
111a bundled-in application that is linked together with udpxy (as one executable).
112
113udpxrec is invoked by a symbolic link (named udpxrec) to the udpxy executable
114(NB: do not rename udpxy executable).
115
116udpxrec creates MPEG files encapsulating MPEG-TS segments; most media players
117will *NOT* play such files; to make them playable the stream must be transcoded
118to MPEG-PS; vlc knows how to do such transcoding, here is a command-line example:
119
120vlc input-ts.mpg --sout="#std{access=file,mux=ps,dst=out-ps.mpg}"
121
122The resulting PS file can be played back by most media players.
123
124Portability
125--------------
126udpxy was written to run on 'POSIX-compliant' systems;
127so far all builds have been tested to build and run on Linux 2.4, 2.6, 3.x (IA32, ARM)
128and *some* (but not all) on HP-UX 11.11 (PA-RISC 1.1, 2.0w).
129
130Build 12 of version 1.0 (Chipmunk) was ported to compile under FreeBSD 7.1
131using GNU make 3.8; later builds have been tested to compile under later
132versions of FreeBSD (up to 9.0);
133
134Certain builds have been ported to build under cygwin; cygwin is
135*NOT* considered to be a fully supported platform yet there is an
136ongoing effort to make udpxy run on it as well.
137
138Environment variables
139--------------
140udpxy utilizes the following environment variables to compliment its
141command-line options; the variables are considered for the options that
142most people would not need to change too often (or simply inconvenient
143to use from the command line).
144
145NB: If there is a command-line switch that would intersect in functionality
146with an environment variable, the switch *always* has the higher priority.
147
148UDPXY_RCV_TMOUT         - timeout (sec) on the inbound data stream (multicast), default=5;
149UDPXY_DHOLD_TMOUT       - timeout (sec) to hold buffered data before sending/flushing to client(s), default=1;
150
151UDPXY_SREAD_TMOUT       - timeout (sec) to read from the listening socked (handling HTTP requests), default=1;
152UDPXY_SWRITE_TMOUT      - timeout (sec) to write to the listening socked (handling HTTP requests), default=1;
153UDPXY_SSEL_TMOUT        - timeout (sec) to select(2) in server loop (unused if pselect(2) is employed), default=30;
154UDPXY_LQ_BACKLOG        - size of the listener socket's backlog, default=16;
155UDPXY_SRV_RLWMARK       - low watermaek on the receiving (m-cast) socket, default=0 (not set);
156UDPXY_SSOCKBUF_NOSYNC   - do not sync inbound (UDP) socket's buffer size (with value set by -B), default=1 (sync);
157UDPXY_DSOCKBUF_NOSYNC   - do not sync outbound (TCP) socket's buffer size (with value set by -B), default=1 (sync);
158
159UDPXY_TCP_NODELAY       - disable Nagle algorithm on the newly accepted socket (faster channel switching), default=1;
160
161UDPXY_HTTP200_FTR_FILE - append contents of the given file to the HTTP 200 response, default=none;
162UDPXY_HTTP200_FTR_LN   - append the text (line) to the  HTTP 200 response, default=none;
163
164UDPXY_ALLOW_PAUSES     - if blocked on a write, keep reading data until the buffer (-B size) is full, default=disabled;
165UDPXY_PAUSE_MSEC       - allow only N milliseconds of reading data when blocked on a write.
166UDPXY_CONTENT_TYPE     - specify custom Content-Type in HTTP responses.
167
168--EOF--
169
170