rtpproxy.8

'\" t
.\"     Title: rtpproxy
.\"    Author: Jan Janak <janakj@users.berlios.de>
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: May 16, 2019
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "RTPPROXY" "8" "May 16, 2019" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
rtpproxy \- RTP (Real\-time Transport Protocol) Proxy Server
.SH "SYNOPSIS"
.HP \w'\fBrtpproxy\fR\ 'u
\fBrtpproxy\fR [\fB\-?\fR] [\fB\-2\fR] [\fB\-f\fR] [\fB\-v\fR] [\fB\-V\fR] [\fB\-R\fR] [\fB\-l\fR\ \fIaddr1\fR\fI[/addr2]\fR] [\fB\-6\fR\ \fIaddr1\fR\fI[/addr2]\fR] [\fB\-s\fR\ \fIctrl_socket\fR] [\fB\-t\fR\ \fItos\fR] [\fB\-p\fR\ \fIpidfile\fR] [\fB\-T\fR\ \fImax_ttl\fR] [\fB\-r\fR\ \fIrdir\fR\ [\fB\-S\fR\ \fIsdir\fR]] [\fB\-L\fR\ \fInofile_limit\fR] [\fB\-A\fR\ \fIadvaddr1\fR\fI[/advaddr2]\fR] [\fB\-m\fR\ \fImin_port\fR] [\fB\-M\fR\ \fImax_port\fR] [\fB\-u\fR\ \fIuname\fR\fI[:gname]\fR] [\fB\-w\fR\ \fIsock_mode\fR] [\fB\-F\fR] [\fB\-i\fR] [\fB\-n\fR\ \fItimeout_socket\fR] [\fB\-P\fR] [\fB\-a\fR] [\fB\-d\fR\ \fIlog_level\fR\fI[:log_facility]\fR] [\fB\-W\fR\ \fIsetup_ttl\fR] [\fB\-\-force_asymmetric\fR]
.SH "DESCRIPTION"
.PP
The
\fBrtpproxy\fR
is a generic\-purpose RTP proxy server designed to be used in conjunction with a SIP Controller capable of rewriting SDP contents\&. OpenSIPS, Kamailio, and Sippy B2BUA support
\fBrtpproxy\fR\&.
.PP
The rtpproxy can be used to facilitate RTP sessions between SIP user agents that are behind a NAT(s) (Network Address Translator) firewall\&. Several cases exists when direct end\-to\-end communication is not possible and RTP streams have to be relayed through another host\&. rtpproxy can be used to setup such a relaying host\&.
.PP
The rtpproxy can also operate as a application level bridge by specifying two interfaces to listen on\&. In bridging mode rtpproxy forwards RTP packets received on one interface to the other interface and vice versa\&. This mode can be used to forward RTP packets between networks without direct network level connectivity (provided that the host running rtpproxy has an interface connected to both networks)\&. One particular application of bridging mode is IPv4/IPv6 traversal of RTP packets\&.
.PP
When instructed by the call controller rtpproxy will record the entire RTP session to the local hard disk, fork\-off (copy) to a remote server and/or play a pre\-recorded file to the user agent (comfort ring replacement, Music\-on\-Hold, disclaimer announcements etc)\&.
.PP
The rtpproxy tracks various important operational metrics about RTP sessions (calls), such as number of packets sent, received, lost, forwarded and so forth\&. Real\-time metrics can then be retrieved by issuing appropriate command via control socket interface\&.
.SH "OPTIONS"
.PP
\fB\-?\fR
.RS 4
Show summary of options\&.
.RE
.PP
\fB\-2\fR
.RS 4
Send every RTP packet twice in sessions that use low\-bitrate codecs\&. Only packets that are smaller than 128 bytes will be sent twice\&. This option can improve audio quality on lossy links\&.
.RE
.PP
\fB\-f\fR
.RS 4
rtpproxy will stay in foreground mode if this option is set\&.
.RE
.PP
\fB\-V\fR
.RS 4
Show version of program\&.
.RE
.PP
\fB\-v\fR
.RS 4
Show supported rtpp command protocol revisions\&.
.RE
.PP
\fB\-l\fR \fIaddr1\fR\fI[/addr2]\fR
.RS 4
IPv4 listen IP address(es)\&. You can specify either one or two addresses\&. If two addresses are specified, the rtpproxy will work in bridging mode\&.
.RE
.PP
\fB\-6\fR \fIaddr1\fR\fI[/addr2]\fR
.RS 4
IPv6 listen IP address(es)\&. You can specify either one or two addresses\&. If two addresses are specified, the rtpproxy will work in bridging mode\&.
.RE
.PP
\fB\-s\fR \fIctrl_socket\fR
.RS 4
This parameter configures rtpproxy control socket\&. The control socket is used by the call controller for the purpose of creating, modifying, and deleting RTP sessions\&. The control socket can also be used to fetch stats from the rtpproxy process, or about specific media sessions\&. Format of
\fIctrl_socket\fR
is <type>:<socket>\&. Following types are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIudp:\fR
Create UDP control socket\&. In this mode rtpproxy will listen on a UDP socket for control messages from the call controlle\&.
.sp
Example: \-s udp:127\&.0\&.0\&.1:9000
.sp
IP address can be \*(Aq*\*(Aq in which case rtpproxy will listen on all local interfaces\&. If port is omitted then port 22222 will be used\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
rtpproxy control protocol has no built\-in security mechanisms\&. Make sure that you protect the listening IP and port properly when using rtpproxy with UDP control socket\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIudp6:\fR
Create IPv6 UDP control socket\&. In this mode rtpproxy will listen on UDP/IPv6 for control messages from the SIP Controller\&.
.sp
Example: \-s udp6:::1:9000
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItcp:\fR
Create IPv4 TCP control socket\&. In this mode rtpproxy will listen on TCP/IPv4 for control messages from the SIP Controller\&.
.sp
Example: \-s tcp:192\&.168\&.0\&.1:9001
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItcp6:\fR
Create IPv6 TCP control socket\&. In this mode rtpproxy will listen on TCP/IPv6 for control messages from the SIP Controller\&.
.sp
Example: \-s tcp6:::1:9002
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIunix:\fR
Create UNIX domain socket in a datagram\-like mode for control interface\&. In this mode the SIP Controller and rtpproxy must be running on the same host\&. This is traditional mode when rtpproxy would close connection after processing each command and sending reply\&.
.sp
Example: \-s unix:/var/run/rtpproxy\&.sock
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIcunix:\fR
Create UNIX domain socket for control interface\&. In this mode the SIP Controller and rtpproxy must be running on the same host\&. Similar to
\fIunix:\fR
above, but the rtpproxy would keep control socket open and accept multiple commands via the same connection\&.
.sp
Example: \-s cunix:/var/run/rtpproxy\&.sock
.RE
.sp
Default value is
unix:/var/run/rtpproxy\&.sock\&.
.RE
.PP
\fB\-t\fR \fItos\fR
.RS 4
Set ToS (Type of Service) in the outgoing IP header\&. Default value is 0xB8\&. Setting this parameter to \-1 disables setting ToS resulting in operating system default ToS being used instead\&.
.RE
.PP
\fB\-r\fR \fIrec_dir\fR
.RS 4
Directory to write recorded RTP sessions\&.
.RE
.PP
\fB\-S\fR \fIspool_dir\fR
.RS 4
Spool directory for recording of RTP streams\&. When the session is stopped, the recording will be moved from the spool directory to the rec_dir directory as specified by the
\fB\-r\fR
option\&.
.RE
.PP
\fB\-R\fR
.RS 4
Prevent rtpproxy from recording RTCP when recording RTP\&. rtpproxy records RTCP by default when RTP recording is enabled\&.
.RE
.PP
\fB\-p\fR \fIpid_file\fR
.RS 4
This parameter configures the name of the file where PID of running rtpproxy will be stored\&. Default is
/var/run/rtpproxy\&.pid\&.
.RE
.PP
\fB\-T\fR \fImax_ttl\fR
.RS 4
Specify the RTP inactivity timer\&. Defaults to 60 seconds\&.
.sp
If the rtpproxy does not receive any RTP packets for more than
\fImax_ttl\fR
it will then delete the session\&.
.RE
.PP
\fB\-L\fR \fInofile_limit\fR
.RS 4
Set the maximum number of open file descriptors per process\&. The default maximum is set by the operating system, and can be overridden using the
\fB\-L\fR
flag\&.
.sp
The rtpproxy requires four file descriptors per session to ensure that it can reliably identify where each stream is coming from in a NAT firewall scenario\&.
.RE
.PP
\fB\-A\fR \fIadvaddr1\fR\fI[/advaddr2]\fR
.RS 4
Set advertised address of rtpproxy\&. Useful if the rtpproxy is behind a NAT firewall\&. (Amazon EC2) When the rtpproxy receives a session request from a SIP controller it will return the IP address(es) specified by the
\fB\-A\fR
option\&.
.RE
.PP
\fB\-m\fR \fImin_port\fR
.RS 4
Set lower limit on UDP ports range that the rtpproxy uses for RTP/RTCP sessions to
\fImin_port\fR\&. Default is 35000\&.
.RE
.PP
\fB\-M\fR \fImax_port\fR
.RS 4
Set upper limit on UDP ports range that the rtpproxy uses for RTP/RTCP sessions to
\fImax_port\fR\&. Default is 65000\&.
.RE
.PP
\fB\-u\fR \fIuname\fR\fI[:gname]\fR
.RS 4
Switch rtpproxy to UID identified by the
\fIuname\fR
and optional GID identified by
\fIgname\fR
when proxy is up and running\&.
.RE
.PP
\fB\-w\fR \fIsock_mode\fR
.RS 4
Set access mode for the controlling UNIX\-socket (if used)\&. Only applies if rtpproxy runs under a different GID using
\fB\-u\fR
option\&.
.RE
.PP
\fB\-F\fR
.RS 4
By default the rtpproxy will warn user if running as superuser (UID 0) in local control mode and refuse to run in remote control mode at all\&. This switch removes the check\&.
.RE
.PP
\fB\-i\fR
.RS 4
Enable independent RTP activity timeout mode\&. By default, a timeout (which results in automatic destruction of the session) can only occur if no RTP packets are received on any of the session\*(Aqs ports\&. This option, if set, varies that behaviour, such that a timeout will occur if packets are still being received on one port but not the other\&. The option should be used with caution since in some cases it\*(Aqs perfectly fine to have packets coming from only one side of conversation (i\&.e\&. when the second party has muted its audio)\&.
.RE
.PP
\fB\-n\fR \fItimeout_socket\fR
.RS 4
This parameter specifies permitted notification sockets only\&. The listening socket must be created by another application, preferably before starting rtpproxy\&.
.sp
Timeout notifications must be enabled by the SIP controller when setting up the session\&. The SIP Controller must specify the timeout_socket, and a notify_tag, which is expected to be an arbitrary string that can be used by the SIP controller to identify which session a received time out notification relates to\&.
.sp
If a SIP Controller specifies a notification socket for a session, and that socket is not specified using the
\fB\-n\fR
flag, the rtpproxy will not send a notification, and will not produce an error\&. It will ignore the notification request\&.
.sp
Format of
\fItimeout_socket\fR
is <type>:<socket>\&. Following types are supported:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIunix:\fR
Connect to UNIX domain socket for sending timeout notifications\&. In this mode B2BUA and rtpproxy must be running on the same host\&.
.sp
Example: \-n unix:/var/run/rtpproxy_timeout\&.sock
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItcp:\fR
Connect to a remote host using TCP/IP for sending timeout notifications\&. Format of the
\fIsocket\fR
parameter in this case is <host>:<port>\&.
.sp
Example: \-n tcp:10\&.20\&.30:12345
.RE
.sp
There is no default value, notifications are not sent and not permitted unless a value is specified explicitly\&. Multiple notification sockets can be provided by specifying the
\fB\-n\fR
flag more than once\&.
.RE
.PP
\fB\-P\fR
.RS 4
Record sessions using libpcap file format instead of non\-standard ad\-hoc format\&. The libpcap format, which is the de\-facto standard for packet capturing software, has the advantage of being compatible with numerous third\-party tools and utilities, such as tcpdump or Wireshark\&. The drawback of libpcap is slightly larger overhead (extra 12 bytes for every saved RTP packet for IPv4)\&.
.RE
.PP
\fB\-a\fR
.RS 4
Record all sessions going through the rtpproxy unconditionally\&. By default rtpproxy expects the SIP controller to enable recording on a per\-session basis\&.
.RE
.PP
\fB\-d\fR \fIlog_level\fR\fI[:log_facility]\fR
.RS 4
Configures the verbosity level of the log output\&. Possible
\fIlog_level\fR
values in the order from the most verbose to the least verbose are: DBUG, INFO, WARN, ERR and CRIT\&.
.sp
The optional
\fIlog_facility\fR
parameter sets syslog(3) facility assigned to log messages\&.
.sp
Example: \-d WARN:LOG_LOCAL5
.sp
The default level in foreground mode is is DBUG, in background \- WARN and facility is LOG_DAEMON\&.
.RE
.PP
\fB\-\-force_asymmetric\fR
.RS 4
Treat all RTP/RTCP sessions as "assymetric", i\&.e\&. disable any NAT traversal features unconditionally\&.
.RE
.SH "PRINCIPLES OF OPERATION"
.PP
When the SIP controller receives an INVITE request, it extracts the Call\-ID and from_tag from INVITE\&. The call controller communicates it with the rtpproxy via Unix domain socket or a UDP socket\&. rtpproxy looks for an existing session with the given Call\-ID and from_tag\&.
.PP
If rtpproxy finds a session that is already associated with the given Call\-ID, it will return the UDP port number that is already associated with that session\&.
.PP
If the given Call\-ID and from_tag is not associated with an existing session, it will create a new session by randomly choosing a free UDP port from the usable UDP port range\&. The UDP port number will be provided as a response to the SIP controllers request\&.
.PP
The SIP controller is then expected to rewrite the SDP, replacing the ip:port to that of the IP address of the rtpproxy, and the port number allocated by the rtpproxy\&. The user agent reading the SDP will then send its RTP stream to the rtpproxy\&.
.PP
When the SIP Controller receives a non\-negative SIP reply with SDP it extracts the Call\-ID, from_tag and to_tag from the SIP message and sends a request to the rtpproxy with Call\-ID, from_tag and to_tag\&.
.PP
The rtpproxy looks for an existing session based on the Call\-ID and from_tag, which it should find\&. It will then randomly choose another port and "connect" this port with the earlier allocated port, forming the proxy between both sides\&.
.PP
When the SIP controller recieves the new port number from the rtpproxy, the SIP controller is expected to rewrite the SDP in the SIP message body by replacing the ip:port to that of the IP address and new udp port number provided by rtpproxy\&. The SIP controller is expected to send the reply to the user agent that initiated the call\&.
.PP
After the session has been created, the proxy listens on the ports it has allocated for that session and waits for receiving at least one UDP packet from each of the two parties participating in the call\&. Once a packet is received, the proxy fills one of two IP:port structures associated with respective stream with the source IP:port of that packet\&. When both structures are filled in, the proxy starts relaying UDP packets between the parties\&.
.PP
The rtpproxy tracks idle time for each of existing sessions (i\&.e\&. time interval within which there were no packets relayed), and automatically cleans up a sessions whose idle times exceed the idle time (60 seconds by default)\&.
.SH "FILES"
.PP
rtpproxy
.PP
makeann
.PP
extractaudio
.SH "LICENSE"
.PP
All components of the rtpproxy are licensed under the BSD 2\-Clause License\&. See
LICENSE
file in the top of source tree for details\&.
.SH "AVAILABILITY"
.PP
The latest version of this program and its components can be found at
\m[blue]\fBhttp://www\&.rtpproxy\&.org/\fR\m[]\&.
.SH "AUTHORS"
.PP
\fBJan Janak\fR <\&janakj@users\&.berlios\&.de\&>
.RS 4
Author.
.RE
.PP
\fBMaksym Sobolyev\fR <\&sobomax@gmail\&.com\&>
.RS 4
Author.
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2006-20019 Maksym Sobolyev \m[blue]\fB<sobomax@gmail\&.com>\fR\m[]
.br
Copyright \(co 2006 Jan Janak \m[blue]\fB<janakj@users\&.berlios\&.de>\fR\m[]
.br