Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RTPPROXY(8)			[FIXME:	manual]			   RTPPROXY(8)

       rtpproxy	- RTP (Real-time Transport Protocol) Proxy Server

       rtpproxy	[-?] [-2] [-f] [-v] [-V] [-R] [-l addr1[/addr2]]
		[-6 addr1[/addr2]] [-s ctrl_socket] [-t	tos] [-p pidfile]
		[-T max_ttl] [-r rdir [-S sdir]] [-L nofile_limit]
		[-A advaddr1[/advaddr2]] [-m min_port] [-M max_port]
		[-u uname[:gname]] [-w sock_mode] [-F] [-i]
		[-n timeout_socket] [-P] [-a] [-d log_level[:log_facility]]
		[-W setup_ttl]

       rtpproxy	is a symmetric RTP proxy designed to be	used in	conjunction
       with a SIP Controller capable of	rewriting SDP contents.	OpenSIPs,
       Kamailio, and Sippy B2BUA support rtpproxy

       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.

       rtpproxy	can 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.

       When instructed by the call controller rtpproxy will record the entire
       RTP session to the local	hard disk or play a pre-recorded file to the
       user agent (comfort ring	replacement, Music-on-Hold, disclaimer

       rtpproxy	tracks various metrics about call sessions, such as packets
       sent, packets received, packets lost and	so fort.

	   Show	summary	of options.

	   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.

	   rtpproxy will stay in foreground mode if this option	is set.

	   Show	version	of program.

	   Show	rtpp command protocol version.

       -l addr1[/addr2]
	   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.

       -6 addr1[/addr2]
	   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.

       -s ctrl_socket
	   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 ctrl_socket is <type>:<socket>. Following
	   types are supported:

	   o   udp: Create UDP control socket. In this mode rtpproxy will
	       listen on a UDP socket for control messages from	the call

	       Example:	-s udp:

	       IP address can be '*' in	which case rtpproxy will listen	on all
	       local interfaces. If port is omitted then port 22222 will be

		   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.

	   o   udp6: Create IPv6 UDP control socket. In	this mode rtpproxy
	       will listen on UDP/IPv6 for control messages from the SIP

	       Example:	-s udp6:::1:9000

	   o   unix: Create UNIX domain	socket for control interface. In this
	       mode the	SIP Controller and rtpproxy must be running on the
	       same host.

	       Example:	-s unix:/var/run/rtpproxy.sock

	       Default value is	/var/run/rtpproxy.sock.

       -t tos
	   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.

       -r rec_dir
	   Directory to	write recorded RTP sessions.

       -S spool_dir
	   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 -r	option.

	   Prevent rtpproxy from recording RTCP	when recording RTP. rtpproxy
	   records RTCP	by default when	RTP recording is enabled.

       -p pid_file
	   This	parameter configures the name of the file where	PID of running
	   rtpproxy will be stored. Default is /var/run/

       -T max_ttl
	   Specify the RTP inactivity timer. Defaults to 60 seconds.

	   If the rtpproxy does	not receive any	RTP packets for	more than
	   max_ttl it will then	delete the session.

       -L nofile_limit
	   Set the maximum number of open connections per process. The default
	   maximum is set by the operating system, and can be overridden using
	   the -L flag.

	   rtpproxy requires four connections per media	stream to ensure that
	   it can reliably identify where a stream is coming from in a NAT
	   firewall scenario.

       -A advaddr1[/advaddr2]
	   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	-A option.

       -m min_port
	   Set lower limit on UDP ports	range that the rtpproxy	uses for
	   RTP/RTCP sessions to	min_port. Default is 35000.

       -M max_port
	   Set upper limit on UDP ports	range that the rtpproxy	uses for
	   RTP/RTCP sessions to	max_port. Default is 65000.

       -u uname[:gname]
	   Switch rtpproxy to UID identified by	the uname and optional GID
	   identified by gname when proxy is up	and running.

       -w sock_mode
	   Set access mode for the controlling UNIX-socket (if used). Only
	   applies if rtpproxy runs under a different GID using	-u option.

	   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.

	   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's	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's perfectly	fine to	have packets coming from only one side
	   of conversation (i.e. when the second party has muted its audio).

       -n timeout_socket
	   This	parameter specifies permitted notification sockets only. The
	   listening socket must be created by another application, preferably
	   before starting rtpproxy.

	   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.

	   If a	SIP Controller specifies a notification	socket for a session,
	   and that socket is not specified using the -n flag, the rtpproxy
	   will	not send a notification, and will not produce an error.	It
	   will	ignore the notification	request.

	   Format of timeout_socket is <type>:<socket>.	Following types	are

	   o   unix:Connect to UNIX domain socket for sending timeout
	       notifications. In this mode B2BUA and rtpproxy must be running
	       on the same host.

	       Example:	-n unix:/var/run/rtpproxy_timeout.sock

	   o   tcp:Connect to a	remote host using TCP/IP for sending timeout
	       notifications. Format of	the socket parameter in	this case is

	       Example:	-n tcp:10.20.30:12345

	   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 -n flag more
	   than	once.

	   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).

	   Record all sessions going through the rtpproxy unconditionally. By
	   default rtpproxy expects the	SIP controller to enable recording on
	   a per-session basis.

       -d log_level[:log_facility]
	   Configures the verbosity level of the log output. Possible
	   log_level values in the order from the most verbose to the least
	   verbose are:	DBUG, INFO, WARN, ERR and CRIT.

	   The optional	log_facility parameter sets syslog(3) facility
	   assigned to log messages.

	   Example: -d WARN:LOG_LOCAL5

	   The default level in	foreground mode	is is DBUG, in background -
	   WARN	and facility is	LOG_DAEMON.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       The rtpproxy tracks idle	time for each of existing sessions (i.e. the
       time within which there were no packets relayed), and automatically
       cleans up a sessions whose idle times exceed the	idle time (60 seconds
       by default).


       This program is licensed	under the BSD license. See COPYING file	in the
       rtpproxy	sources	for details.

       The latest version of this program can be found at

       Maxim Sobolev

       Copyright (C) 2006 janakj

[FIXME:	source]			 Jun 16, 2008			   RTPPROXY(8)


Want to link to this manual page? Use this URL:

home | help