Skip to content

RTPProxy Command Protocol

Jump to bottom Edit New page
jevonearth edited this page Nov 13, 2015 · 3 revisions

RTPProxy command protocol

The RTPProxy uses a simple text base command protocol to manage streams, and fetch information from the RTPProxy.

This protocol is used between SIP controllers (OpenSIPs, Kamailio, Sippy B2BUA) to set up and tear down media sessions.

Commands are case in-sensitive, but uppercase is preferred.

Commands that operate on, or create a session typically take two mandatory parameters; call_id, to_tag and one optional from_tag.

The examples in this document use dummy values as follows;

  • call_id: 123@abc
  • to_tag: some_to_tag
  • from_tag: some_from_tag

A real-world example would look something like:

Q 3365030e05627765187734b81d57f6dc@10.0.0.1-0 d10bce6278e01cfe2ade240aaee26385 2919213e4eb16f01d350a99d539b4428

Accessing the command channel manually

To explore the RTPP channel, you can communicate with a RTPProxy instance either via the Unix domain socket, or via a UDP port. There are plenty of tools to do this. The examples that follow use the netcat command nc.

Accessing RTPProxy command channel using socket

# echo V | nc -U /var/run/RTPProxy.sock 
20040170

Accessing RTPProxy command channel using udp port

This example assumes you have a running RTPProxy that was started with the following flags: rtpproxy -s udp:127.0.0.1:22222

nc -u 127.0.0.1 22229
TOKEN V
TOKEN 20040107

The TOKEN string is important, and can be any alphanumeric string. It is a transaction ID used to keep track of requests. If you are writing a simple polling script to gather stats, then using a Unix time stamp should suffice. If you are controlling RTPProxy from a call controller, then you should make sure the TOKEN is unique for each request.

The following example uses the date command, and the G rtpp command to fetch the nesss_created counter.

# echo "$(date +%s) G nsess_created" |nc -u 127.0.0.1 22229
1447371704 60335158
#

This example shows RTPProxy has created 6,033,5158 sessions in its lifetime.

RTPP Commands

V

Returns the base RTPP protocol capability level.

VF protocol_version

Returns 0 for unsupported, 1 for supported.

Example of VF where protocol is supported

echo "VF 20150616" | nc -U /var/run/rtpproxy.sock
0

Example of VF where protocol is unsupported

echo "VF 20200617" | nc -U /var/run/rtpproxy.sock
1

Create/Update a session

U[opts] call_id remote_ip remote_port from_tag [to_tag] [notify_socket notify_tag]

The U command is used to either create or update a session. This command is idempotent.

Create/Update example

echo "U 123@abc 10.0.0.1 5000 xyz" | nc -U /var/run/rtpproxy.sock 
55040

Lookup session

L[opts] call_id remote_ip remote_port from_tag [to_tag]

Options for U & L

  • E - Listen Internet Address Egress External
  • I - Listen Internet Address sockaddr Ingress Internal
  • 6 - Use IPv6
  • S - symmetric RTP
  • W - weak mode relates to call transfer scenarios.
  • Z requested_nsamples - Enables re-packetization. Value will depend on codec. Minimum is 10msec. Minimum increment is 10msec. Certain Codecs have larger min packet size. GSM increments are 30msec. G711,G729 10msec.
  • C - Codec payload types. integers separated by commas. See rfc3551 Table4
  • L - specify the local RTPProxy address to use
  • R - Remote address. Destination IP. A Little weird. We don't use it much. It is for the case where you receive SDP that says “My IP is”. You can use this R flag to indicate where you received this address from. Useful when the signalling and media IP address might be different. When we don’t have reliable media information in the SDP, we can use the ‘R’ flag as a hint.

Delete active session

D[w] call_id from_tag [to_tag];

Delete an active session. Typically used for Bye/Cancel/Error scenario from upstream controller.

The w option stands for weak.

Delete example

The following example sets up a session, and then deletes it.

echo "U 123@abc 10.0.0.1 5000 xyz" | nc -U /var/run/rtpproxy.sock
36018
echo "D 123@abc xyz" | nc -U /var/run/rtpproxy.sock
0

This example attempts to delete a session that does not exist, and an error code is returned.

echo "D dev@null this_tag_doesnt_exist" | nc -U /var/run/rtpproxy.sock
E50

Fetching Stats

G [stat_name1 [stat_name2 [stat_name3 ...[stat_nameN]]]]

Get one or more stat counter by name.

Stats Example

The following example gets two stats, nsess_created and nsess_destroyed. The results are returned on a single line, separated by a space, in the same order as the command specified.

# echo "G nsess_created nsess_destroyed" |nc -U /var/run/rtpproxy1.sock
60292534 60292341

Stat names

  • nsess_created - Number of RTP sessions created
  • nsess_destroyed - Number of RTP sessions destroyed
  • nsess_timeout - Number of RTP sessions ended due to media timeout
  • nsess_complete - Number of RTP sessions fully setup
  • nsess_nortp - Number of sessions that had no RTP neither in nor out
  • nsess_owrtp - Number of sessions that had one-way RTP only
  • nsess_nortcp - Number of sessions that had no RTCP neither in nor out
  • nsess_owrtcp - Number of sessions that had one-way RTCP only
  • nplrs_created - Number of RTP players created
  • nplrs_destroyed - Number of RTP players destroyed
  • npkts_rcvd - Total number of RTP/RTPC packets received
  • npkts_played - Total number of RTP packets locally generated (played out)
  • npkts_relayed - Total number of RTP/RTPC packets relayed
  • npkts_resizer_in - Total number of RTP packets ingress into resizer (re-packetizer)
  • npkts_resizer_out - Total number of RTP packets egress out of resizer (re-packetizer)
  • npkts_resizer_discard - Total number of RTP packets dropped by the resizer (re-packetizer)
  • npkts_discard - Total number of RTP/RTPC packets discarded
  • total_duration - Cumulative duration of all sessions
  • ncmds_rcvd - Total number of control commands received
  • ncmds_rcvd_ndups - Total number of duplicate control commands received
  • ncmds_succd - Total number of control commands successfully processed
  • ncmds_errs - Total number of control commands ended up with an error
  • ncmds_repld - Total number of control commands that had a reply generated
  • rtpa_nsent - Total number of uniqie RTP packets sent to us based on SEQ tracking
  • rtpa_nrcvd - Total number of unique RTP packets received by us based on SEQ tracking
  • rtpa_ndups - Total number of duplicate RTP packets received by us based on SEQ tracking
  • rtpa_perrs - Total number of RTP packets that failed RTP parse routine in SEQ tracking

Get info summary

Deprecated, use G instead

I[b]

Returns a summary of sessions and packets.

Example

# echo "I" |nc -U /var/run/rtpproxy.sock
sessions created: 60293495
active sessions: 217
active streams: 403
packets received: 341220205706
packets transmitted: 348306157118

Play/Inject audio into media stream

P[n] call_id pname codecs from_tag [to_tag]

Query session

Q[v] call_id from_tag [to_tag [stat_name1 ...[stat_nameN]]]

The Query command can retrieve various stats for an in progress session.

Stats available via Q command

  • ttl - remaining time before timeout
  • npkts_ina - packets received from "answering side"
  • npkts_ino - packets received from "originating" side
  • nrelayed - packets relayed
  • ndropped - packets ignored (i.e. early packets no address to relay)
  • rtpa_nsent - derived number of packets received based on sequence number
  • rtpa_nrcvd - actual number of non-duplicate packets received
  • rtpa_ndups - number of duplicates
  • rtpa_nlost - derived number of lost packets
  • rtpa_perrs - packets cannot be parsed or not RTP

When used without any stat names specified, the command will return the following stats by default:

  • ttl
  • npkts_ina
  • npkts_ino
  • nrelayed
  • ndropped

Optional flag v stands for verbose, and causes the returned parameters to be in name/value pairs. Without the v flag, results will be returned as values separated by a space in order by which they were requested.

Query Command Examples

Query example first creates a session, so we have something to query, then it queries for the session using the call_id and from_tag.

Query verbose for defaults

# echo "U 123@abc 10.0.0.1 5000 some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock
57796
# echo "Qv 123@abc some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock
ttl=59 npkts_ina=0 npkts_ino=0 nrelayed=0 ndropped=0

Query verbose for specific stats

# echo "U 123@abc 10.0.0.1 5000 some_to_tag some_from_tag" | nc -U
/var/run/rtpproxy.sock 57796 # echo "Qv 123@abc some_to_tag some_from_tag
rtpa_ndups rtpa_nlost" | nc -U /var/run/rtpproxy.sock rtpa_ndups=0
rtpa_nlost=0

Query for defaults, not verbose

# echo "U 123@abc 10.0.0.1 5000 some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock
57796
# echo "Q 123@abc some_to_tag some_from_tag" | nc -U /var/run/rtpproxy.sock
53 0 0 0 0

Recording / Copy

R[s] call_id from_tag [to_tag] C[-xxx-] call_id -XXX- from_tag [to_tag]

C - COPY is synomonous with R for RECORD

Records the media streams related to the specified call_id

rtpproxy must be started with the -r flag set to the directory where recordings will be written to as files.

R options

  • S merge both media streams to single file. This will only work when RTPProxy records audio in pcap format by starting it with the -P flag. Relies on the command line option

Playback / inject audio into stream

P[n] call_id pname codecs from_tag [to_tag]

Causes the referenced pre-encoded audio to be injected into the specified audio stream.

n option is a integer that will control how many times the audio should be injected. When n is not specified, the audio is injected once.

Stop playback

S call_id from_tag [to_tag]

Stops playback of audio that was started using the P command.

Kill all sessions

Danger

X

Deletes all sessions.

Add a custom footer
Add a custom sidebar
Clone this wiki locally