-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
168 lines (126 loc) · 6.86 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
#
# Copyright 2008-2012 Pavel V. Cherenkov ([email protected])
#
# 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
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/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 mgroup_address:mgroup_port identify the multicast group 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.
--EOF--