iptrtpproxy - management tool for RTP/RTCP sessions  


iptrtpproxy -h [command]

iptrtpproxy info [other_options] [common_options]

iptrtpproxy list [switchboard] [session_range] [list_verbosity] [other_options] [common_options]

iptrtpproxy alloc [switchboard] RTP_params [other_options] [common_options]

iptrtpproxy update switchboard [session_range] [other_options] [common_options]

iptrtpproxy delete [switchboard] [session_range] [other_options] [common_options]  


iptrtpproxy is used to set up, maintain, and inspect the RTP/RTCP sessions in netfilter RTPPROXY target. The seesions behave as proxy for RTP/RTCP packets enabling smooth streaming for clients hidden behind NAT. The range of dedicated ports at particular IP is called `gate'. Because we have two clients in RTP/RTCP we must have also two gates. Two gates are permanently connected at the `switchboard'. One or two IP addresses may be used for connected gates. Each of RTP/RTCP clients will send packets to gate's IP:port and receive packet from the same gate's IP:port as well. It's called the `session'. The switchbord is responsible for routing to opposite client.

ibtrtpproxy makes call to kernel and requires CAP_NET_ADMIN,CAP_NET_RAW capabilities, i.e. it requires to execute as root. Capabilities may be limited by a libcap utility ( sucap, execcap ).  


The options that are recognized by iptrtpproxy can be divided into several different groups.  


These options specify the specific action to perform. Only one of them can be specified on the command line.
Get uptime, total number of switchboards and sessions and global statistics.
List switchboards and sessions, switchboards may be filtered using switchboard parameter. Session_range may specify sessions to be listed.
Allocate new session, i.e. two couples of ports will be dedicated. At least one source address or learning timeout must be provided. Session id is returned.
Update specified session(s) at specified switchboard. Unless session_range specified then affects all sessions having state non-expired and non-destroyed.
Destroy specified session(s). Unless switchboard specified affects all switchboards, unless session_range specified then affects all sessions.


The switchboard is identified by gate IP:port. Unless specified identification of both gates gate-a and gate-b then gate-b is equal to gate-b . If both addresses and ports are equal then lib_RTPPROXY module will try to find correct switchboard too. It simplifies life slightly.
--addr-a ip
--addr-b ip
IP address of gate
--port-a port
--port-b port
The lowest port of dedicated port range


Identifies sessions to be affected by command.
--sess-id-lo id
Low session id, default value is 0.
--sess-id-hi id
Hi session id value, unless specified --sess-id-lo is taken as default value.


Specify parameters of RTP/RTCP client. We can specify params of both RTP and RTCP streams separately. Default values of RTCP are based on corresponding RTP param.
--rtp-addr-a ip
--rtcp-addr-a ip
--rtp-addr-b ip
--rtcp-addr-b ip
IP address of RTP/RTCP client.
--rtp-port-a port
--rtcp-port-a port
--rtp-port-b port
--rtcp-port-b port
Port of RTP/RTCP client.
--rtp-learning-timeout-a msec
--rtp-learning-timeout-b msec
--rtcp-learning-timeout-a msec
--rtcp-learning-timeout-b msec
Time how long the session will try to learn source address of RTP/RTCP packets.
The session will try to learn always source address of RTP/RTCP packets even in the case the address:port is known. Malicious packets may silently redirect stream.


Do not list switchboards. It also implies --no-session
Do not list sessions.


The following options can be specified:
Reset global statistics
Reset switchboard statistics
Reset switchboard packet statistics
Force switchboard audit, i.e. checking expirations and update statistics


The following common options can be specified:
-v, --verbose
Verbose output. The most of verbose output goes to stderr.
Print version.
-h, --help
If command is specified then prints help regarding the command otherwise prints list of possible commands. Note that option may be specified almost at any position of command line.


lib_RTPPROXY kernel module must be loaded and a switchboard defined using iptables tool.


# load kernel module
  modprobe -i xt_RTPPROXY 

# define switchboard
  iptables -t mangle -N my_rtpproxy
  iptables -t mangle -A my_rtpproxy -j RTPPROXY --addr-a --port-a 50000 --max-sess 100

# add it to a chain in PREROUTING, POSTROUTING and OUTPUT, specify matching conditions, etc.
  iptables -t mangle -A PREROUTING -p udp -j my_rtpproxy
  iptables -t mangle -A OUTPUT -p udp -j my_rtpproxy
  iptables -t mangle -A POSTROUTING -p udp -j my_rtpproxy

# run as root with limited set of capabilities
  execcap 'CAP_DAC_READ_SEARCH,CAP_NET_ADMIN,CAP_NET_RAW=eip' iptrtpproxy info

# run as non root user, it requires CAP_SETPCAP to provide a root capability to plain user
  sucap my_user my_group execcap 'CAP_DAC_READ_SEARCH,CAP_NET_ADMIN,CAP_NET_RAW=eip' iptrtpproxy info



Various error messages are printed to standard error. The exit code is 0 for correct functioning. Errors which appear to be caused by invalid or abused command line parameters cause an exit code of 2, and other errors cause an exit code of 1.  


Bugs? Many. ;-)  


iptables(8) capabilities(7) cap_from_text(3) The netfilter-rtpproxy-HOWTO details usage for RTP/RTCP proxy. The libcap FAQ capfaq-x.y.txt.