1RTPPROXY(8) [FIXME: manual] RTPPROXY(8)
2
6 rtpproxy - RTP (Real-time Transport Protocol) Proxy Server
7
9 rtpproxy [-?] [-2] [-f] [-v] [-V] [-R] [-l addr1[/addr2]]
10 [-6 addr1[/addr2]] [-s ctrl_socket] [-t tos] [-p pidfile]
11 [-T max_ttl] [-r rdir [-S sdir]] [-L nofile_limit]
12 [-A advaddr1[/advaddr2]] [-m min_port] [-M max_port]
13 [-u uname[:gname]] [-w sock_mode] [-F] [-i]
14 [-n timeout_socket] [-P] [-a] [-d log_level[:log_facility]]
15 [-W setup_ttl] [--force_asymmetric]
16
18 The rtpproxy is a generic-purpose RTP proxy server designed to be used
19 in conjunction with a SIP Controller capable of rewriting SDP contents.
20 OpenSIPS, Kamailio, and Sippy B2BUA support rtpproxy.
21 The rtpproxy can be used to facilitate RTP sessions between SIP user
23 agents that are behind a NAT(s) (Network Address Translator) firewall.
24 Several cases exists when direct end-to-end communication is not
25 possible and RTP streams have to be relayed through another host.
26 rtpproxy can be used to setup such a relaying host.
27 The rtpproxy can also operate as a application level bridge by
29 specifying two interfaces to listen on. In bridging mode rtpproxy
30 forwards RTP packets received on one interface to the other interface
31 and vice versa. This mode can be used to forward RTP packets between
32 networks without direct network level connectivity (provided that the
33 host running rtpproxy has an interface connected to both networks). One
34 particular application of bridging mode is IPv4/IPv6 traversal of RTP
35 packets.
36 When instructed by the call controller rtpproxy will record the entire
38 RTP session to the local hard disk, fork-off (copy) to a remote server
39 and/or play a pre-recorded file to the user agent (comfort ring
40 replacement, Music-on-Hold, disclaimer announcements etc).
41 The rtpproxy tracks various important operational metrics about RTP
43 sessions (calls), such as number of packets sent, received, lost,
44 forwarded and so forth. Real-time metrics can then be retrieved by
45 issuing appropriate command via control socket interface.
46
48 -?
49 Show summary of options.
50 -2
52 Send every RTP packet twice in sessions that use low-bitrate
53 codecs. Only packets that are smaller than 128 bytes will be sent
54 twice. This option can improve audio quality on lossy links.
55 -f
57 rtpproxy will stay in foreground mode if this option is set.
58 -V
60 Show version of program.
61 -v
63 Show supported rtpp command protocol revisions.
64 -l addr1[/addr2]
66 IPv4 listen IP address(es). You can specify either one or two
67 addresses. If two addresses are specified, the rtpproxy will work
68 in bridging mode.
69 -6 addr1[/addr2]
71 IPv6 listen IP address(es). You can specify either one or two
72 addresses. If two addresses are specified, the rtpproxy will work
73 in bridging mode.
74 -s ctrl_socket
76 This parameter configures rtpproxy control socket. The control
77 socket is used by the call controller for the purpose of creating,
78 modifying, and deleting RTP sessions. The control socket can also
79 be used to fetch stats from the rtpproxy process, or about specific
80 media sessions. Format of ctrl_socket is <type>:<socket>. Following
81 types are supported:
82 • udp: Create UDP control socket. In this mode rtpproxy will
84 listen on a UDP socket for control messages from the call
85 controlle.
86 Example: -s udp:127.0.0.1:9000
88 IP address can be '*' in which case rtpproxy will listen on all
90 local interfaces. If port is omitted then port 22222 will be
91 used.
92 Note
94 rtpproxy control protocol has no built-in security
95 mechanisms. Make sure that you protect the listening IP and
96 port properly when using rtpproxy with UDP control socket.
97 • udp6: Create IPv6 UDP control socket. In this mode rtpproxy
99 will listen on UDP/IPv6 for control messages from the SIP
100 Controller.
101 Example: -s udp6:::1:9000
103 • tcp: Create IPv4 TCP control socket. In this mode rtpproxy will
105 listen on TCP/IPv4 for control messages from the SIP
106 Controller.
107 Example: -s tcp:192.168.0.1:9001
109 • tcp6: Create IPv6 TCP control socket. In this mode rtpproxy
111 will listen on TCP/IPv6 for control messages from the SIP
112 Controller.
113 Example: -s tcp6:::1:9002
115 • unix: Create UNIX domain socket in a datagram-like mode for
117 control interface. In this mode the SIP Controller and rtpproxy
118 must be running on the same host. This is traditional mode when
119 rtpproxy would close connection after processing each command
120 and sending reply.
121 Example: -s unix:/var/run/rtpproxy.sock
123 • cunix: Create UNIX domain socket for control interface. In this
125 mode the SIP Controller and rtpproxy must be running on the
126 same host. Similar to unix: above, but the rtpproxy would keep
127 control socket open and accept multiple commands via the same
128 connection.
129 Example: -s cunix:/var/run/rtpproxy.sock
131 Default value is unix:/var/run/rtpproxy.sock.
133 -t tos
135 Set ToS (Type of Service) in the outgoing IP header. Default value
136 is 0xB8. Setting this parameter to -1 disables setting ToS
137 resulting in operating system default ToS being used instead.
138 -r rec_dir
140 Directory to write recorded RTP sessions.
141 -S spool_dir
143 Spool directory for recording of RTP streams. When the session is
144 stopped, the recording will be moved from the spool directory to
145 the rec_dir directory as specified by the -r option.
146 -R
148 Prevent rtpproxy from recording RTCP when recording RTP. rtpproxy
149 records RTCP by default when RTP recording is enabled.
150 -p pid_file
152 This parameter configures the name of the file where PID of running
153 rtpproxy will be stored. Default is /var/run/rtpproxy.pid.
154 -T max_ttl
156 Specify the RTP inactivity timer. Defaults to 60 seconds.
157 If the rtpproxy does not receive any RTP packets for more than
159 max_ttl it will then delete the session.
160 -L nofile_limit
162 Set the maximum number of open file descriptors per process. The
163 default maximum is set by the operating system, and can be
164 overridden using the -L flag.
165 The rtpproxy requires four file descriptors per session to ensure
167 that it can reliably identify where each stream is coming from in a
168 NAT firewall scenario.
169 -A advaddr1[/advaddr2]
171 Set advertised address of rtpproxy. Useful if the rtpproxy is
172 behind a NAT firewall. (Amazon EC2) When the rtpproxy receives a
173 session request from a SIP controller it will return the IP
174 address(es) specified by the -A option.
175 -m min_port
177 Set lower limit on UDP ports range that the rtpproxy uses for
178 RTP/RTCP sessions to min_port. Default is 35000.
179 -M max_port
181 Set upper limit on UDP ports range that the rtpproxy uses for
182 RTP/RTCP sessions to max_port. Default is 65000.
183 -u uname[:gname]
185 Switch rtpproxy to UID identified by the uname and optional GID
186 identified by gname when proxy is up and running.
187 -w sock_mode
189 Set access mode for the controlling UNIX-socket (if used). Only
190 applies if rtpproxy runs under a different GID using -u option.
191 -F
193 By default the rtpproxy will warn user if running as superuser (UID
194 0) in local control mode and refuse to run in remote control mode
195 at all. This switch removes the check.
196 -i
198 Enable independent RTP activity timeout mode. By default, a timeout
199 (which results in automatic destruction of the session) can only
200 occur if no RTP packets are received on any of the session's ports.
201 This option, if set, varies that behaviour, such that a timeout
202 will occur if packets are still being received on one port but not
203 the other. The option should be used with caution since in some
204 cases it's perfectly fine to have packets coming from only one side
205 of conversation (i.e. when the second party has muted its audio).
206 -n timeout_socket
208 This parameter specifies permitted notification sockets only. The
209 listening socket must be created by another application, preferably
210 before starting rtpproxy.
211 Timeout notifications must be enabled by the SIP controller when
213 setting up the session. The SIP Controller must specify the
214 timeout_socket, and a notify_tag, which is expected to be an
215 arbitrary string that can be used by the SIP controller to identify
216 which session a received time out notification relates to.
217 If a SIP Controller specifies a notification socket for a session,
219 and that socket is not specified using the -n flag, the rtpproxy
220 will not send a notification, and will not produce an error. It
221 will ignore the notification request.
222 Format of timeout_socket is <type>:<socket>. Following types are
224 supported:
225 • unix: Connect to UNIX domain socket for sending timeout
227 notifications. In this mode B2BUA and rtpproxy must be running
228 on the same host.
229 Example: -n unix:/var/run/rtpproxy_timeout.sock
231 • tcp: Connect to a remote host using TCP/IP for sending timeout
233 notifications. Format of the socket parameter in this case is
234 <host>:<port>.
235 Example: -n tcp:10.20.30:12345
237 There is no default value, notifications are not sent and not
239 permitted unless a value is specified explicitly. Multiple
240 notification sockets can be provided by specifying the -n flag more
241 than once.
242 -P
244 Record sessions using libpcap file format instead of non-standard
245 ad-hoc format. The libpcap format, which is the de-facto standard
246 for packet capturing software, has the advantage of being
247 compatible with numerous third-party tools and utilities, such as
248 tcpdump or Wireshark. The drawback of libpcap is slightly larger
249 overhead (extra 12 bytes for every saved RTP packet for IPv4).
250 -a
252 Record all sessions going through the rtpproxy unconditionally. By
253 default rtpproxy expects the SIP controller to enable recording on
254 a per-session basis.
255 -d log_level[:log_facility]
257 Configures the verbosity level of the log output. Possible
258 log_level values in the order from the most verbose to the least
259 verbose are: DBUG, INFO, WARN, ERR and CRIT.
260 The optional log_facility parameter sets syslog(3) facility
262 assigned to log messages.
263 Example: -d WARN:LOG_LOCAL5
265 The default level in foreground mode is is DBUG, in background -
267 WARN and facility is LOG_DAEMON.
268 --force_asymmetric
270 Treat all RTP/RTCP sessions as "assymetric", i.e. disable any NAT
271 traversal features unconditionally.
272
274 When the SIP controller receives an INVITE request, it extracts the
275 Call-ID and from_tag from INVITE. The call controller communicates it
276 with the rtpproxy via Unix domain socket or a UDP socket. rtpproxy
277 looks for an existing session with the given Call-ID and from_tag.
278 If rtpproxy finds a session that is already associated with the given
280 Call-ID, it will return the UDP port number that is already associated
281 with that session.
282 If the given Call-ID and from_tag is not associated with an existing
284 session, it will create a new session by randomly choosing a free UDP
285 port from the usable UDP port range. The UDP port number will be
286 provided as a response to the SIP controllers request.
287 The SIP controller is then expected to rewrite the SDP, replacing the
289 ip:port to that of the IP address of the rtpproxy, and the port number
290 allocated by the rtpproxy. The user agent reading the SDP will then
291 send its RTP stream to the rtpproxy.
292 When the SIP Controller receives a non-negative SIP reply with SDP it
294 extracts the Call-ID, from_tag and to_tag from the SIP message and
295 sends a request to the rtpproxy with Call-ID, from_tag and to_tag.
296 The rtpproxy looks for an existing session based on the Call-ID and
298 from_tag, which it should find. It will then randomly choose another
299 port and "connect" this port with the earlier allocated port, forming
300 the proxy between both sides.
301 When the SIP controller recieves the new port number from the rtpproxy,
303 the SIP controller is expected to rewrite the SDP in the SIP message
304 body by replacing the ip:port to that of the IP address and new udp
305 port number provided by rtpproxy. The SIP controller is expected to
306 send the reply to the user agent that initiated the call.
307 After the session has been created, the proxy listens on the ports it
309 has allocated for that session and waits for receiving at least one UDP
310 packet from each of the two parties participating in the call. Once a
311 packet is received, the proxy fills one of two IP:port structures
312 associated with respective stream with the source IP:port of that
313 packet. When both structures are filled in, the proxy starts relaying
314 UDP packets between the parties.
315 The rtpproxy tracks idle time for each of existing sessions (i.e. time
317 interval within which there were no packets relayed), and automatically
318 cleans up a sessions whose idle times exceed the idle time (60 seconds
319 by default).
320
322 rtpproxy
323 makeann
325 extractaudio
327
329 All components of the rtpproxy are licensed under the BSD 2-Clause
330 License. See LICENSE file in the top of source tree for details.
331
333 The latest version of this program and its components can be found at
334 http://www.rtpproxy.org/.
335
337 Jan Janak <janakj@users.berlios.de>
338 Author.
339 Maksym Sobolyev <sobomax@gmail.com>
341 Author.
342
344 Copyright © 2006-20019 Maksym Sobolyev <sobomax@gmail.com>
345 Copyright © 2006 Jan Janak <janakj@users.berlios.de>
346[FIXME: source] May 16, 2019 RTPPROXY(8)