Skip to content

RTPP (RTPproxy protocol) technical specification

jevonearth edited this page Nov 12, 2015 · 24 revisions

Augmented BNF for the RTPproxy Protocol

All of the mechanisms specified in this document are described in both prose and an augmented Backus-Naur Form (BNF) defined in RFC 5234. Appendix B.1 of RFC 5234 defines a set of core rules that are used by this specification, and not repeated here. Implementers need to be familiar with the notation and content of RFC 5234 in order to understand this specification. Certain basic rules are in uppercase, such as SP, CRLF, DIGIT, ALPHA, etc. Angle brackets are used within definitions to clarify the use of rule names.

The use of square brackets is redundant syntactically. It is used as a semantic hint that the specific parameter is optional to use.

Basic Types

The following rules are used throughout this specification to describe basic parsing constructs. The US-ASCII coded character set is defined by ANSI X3.4-1986.

ALPHA = %x41-5A / %x61-7A   ; A-Z / a-z
DIGIT = %x30-39 ; 0-9
DQUOTE = %x22 ; " (double quote)
HEX4 =  1*4HEXDIG
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
HEXSEQ = HEX4 *( ":" HEX4)
HTAB = %x09 ; horizontal tab
IPV4 = 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT "." 1*3DIGIT
IPV6 = HEXSEQ / HEXSEQ "::" [ HEXSEQ ] / "::" [ HEXSEQ ]
LF = %x0A ; linefeed
SP = %x20 ; space
PORT = 1*DIGIT
TOKEN = 1*(ALPHA / DIGIT / "-" / "." / "!" / "%" / "*" / "_" / "+" / "`" / "'" / "~" )
VCHAR = %x21-7E ; visible (printing) characters
WORD = 1*(ALPHA / DIGIT / "-" / "." / "!" / "%" / "*" / "_" / "+" / "`" / "'" / "~" / "(" / ")" / "<" / ">" / ":" / "\" / DQUOTE / "/" / "[" / "]" / "?" / "{" / "}" )

Protocol Description

Basic Protocol building blocks

CALLID = WORD [ "@" WORD ]
CODECS = 1*DIGIT *[ "," 1*DIGIT ] ; comma-separated list of numerical codec
                                  ; ids
COOKIE = 1*VCHAR ; one or more printable characters
FROM_TAG = TOKEN ";" 1*DIGIT ; basically a SIP tag with numerical media ID
                             ; separated by a semicolon
SEP = 1*WSP
TO_TAG = TOKEN ";" 1*DIGIT ; basically a SIP tag with numerical media ID
                           ; separated by a semicolon

Delete stream

C_DELETE = "D" [ DELETE_WEAK ] SEP CALLID SEP FROM_TAG [ SEP TO_TAG ]
DELETE_WEAK = "W"

Record stream

C_RECORD = "R" [ RECORD_SINGLE_FILE ] SEP CALLID SEP FROM_TAG [ SEP TO_TAG ]
RECORD_SINGLE_FILE = "S"

Start playback (Music-on-hold or early media)

C_PLAY = "P" [ PLAYCOUNT ] SEP CALLID PNAME SEP ("session" / CODECS) SEP FROM_TAG [ SEP TO_TAG ]
PLAYCOUNT = 1 * DIGIT ; how many times file 'PNAME' must be played
PNAME = PATH ; see [RFC 3986](https://tools.ietf.org/html/rfc3986)

Stop playback

C_NOPLAY = "S" SEP CALLID SEP FROM_TAG [ SEP TO_TAG ]

Copy stream

C_COPY = "C" [ COPY_SINGLE_FILE ] SEP CALLID SEP COPY_DEST SEP FROM_TAG [ SEP TO_TAG ]
COPY_SINGLE_FILE = "S"
COPY_DEST = "udp:" IPV4 ":" PORT ; no IPv6 support :(

Create/update/lookup session

C_UPDATE = "U" [ UPDATE_LOOKUP_PARAMS ] SEP CALLID REMOTE_IP SEP REMOTE_PORT SEP FROM_TAG [ SEP TO_TAG ]  [ SEP NOTIFY_SOCKET SEP NOTIFY_TAG ]
C_LOOKUP = "L" [ UPDATE_LOOKUP_PARAMS ] SEP CALLID REMOTE_IP SEP REMOTE_PORT SEP FROM_TAG [ SEP TO_TAG ]
NOTIFY_SOCKET = ( "unix:" PATH / "tcp:" IPV4 ":" PORT ) ; no IPv6 support :(
NOTIFY_TAG = TOKEN
REMOTE_IP = IPV4 / IPV6
REMOTE_PORT = PORT
UPDATE_LOOKUP_PARAMS = 1 * ( UPDATE_LOOKUP_PARAM_ASYMMETRIC / UPDATE_LOOKUP_PARAM_EXTERNAL / UPDATE_LOOKUP_PARAM_INTERNAL / UPDATE_LOOKUP_PARAM_IPV6 / UPDATE_LOOKUP_PARAM_SYMMETRIC / UPDATE_LOOKUP_PARAM_WEAK / UPDATE_LOOKUP_PARAM_REPACKETIZATION / UPDATE_LOOKUP_PARAM_CODECS / UPDATE_LOOKUP_PARAM_LOCAL / UPDATE_LOOKUP_PARAM_REMOTE / UPDATE_LOOKUP_PARAM_NEW_PORT )
UPDATE_LOOKUP_PARAM_ASYMMETRIC = "A"
UPDATE_LOOKUP_PARAM_EXTERNAL = "E"
UPDATE_LOOKUP_PARAM_INTERNAL = "I"
UPDATE_LOOKUP_PARAM_IPV6 = "6"
UPDATE_LOOKUP_PARAM_SYMMETRIC = "S"
UPDATE_LOOKUP_PARAM_WEAK = "W"
UPDATE_LOOKUP_PARAM_REPACKETIZATION = "Z" 1*DIGIT
UPDATE_LOOKUP_PARAM_CODECS = "C" CODECS
UPDATE_LOOKUP_PARAM_LOCAL = "L" IPV4
UPDATE_LOOKUP_PARAM_REMOTE = "R" IPV4
UPDATE_LOOKUP_PARAM_NEW_PORT = "N"

Get information

C_INFO = "I" [ INFO_BRIEF / INFO_LOAD ]
INFO_BRIEF = "B"
INFO_LOAD = "L"

Query stream info

C_QUERY = "Q" SEP CALLID SEP FROM_TAG [ SEP TO_TAG ]

Get list of features

C_VER_FEATURE = "VF" SEP VERSION_NUMBER
VERSION_NUMBER = ( "20040107" / ; Basic RTP proxy functionality
        "20050322" / ; Support for multiple RTP streams and MOH
        "20060704" / ; Support for extra parameter in the V command
        "20071116" / ; Support for RTP re-packetization
        "20071218" / ; Support for forking (copying) RTP stream
        "20080403" / ; Support for RTP statistics querying
        "20081102" / ; Support for setting codecs in the update/lookup command
        "20081224" / ; Support for session timeout notifications
        "20090810" / ; Support for automatic bridging
        "20140323" / ; Support for tracking/reporting load
        "20140617" / ; Support for anchoring session connect time
        "20141004" / ; Support for extendable performance counters
        "20150330" ) ; Support for allocating a new port ("Un, Ln commands)

Get base version

C_GET_VER = "V"

Delete/stop all sessions

C_DELETE_ALL = "X"

Get statistics

C_GET_STATS = "G" [ STAT_VERBOSE ] 1*(SEP STAT_NAME)
STAT_VERBOSE = "V"
STAT_NAME = ( "nsess_created" /
        "nsess_destroyed" /
        "nsess_timeout" /
        "nsess_complete" /
        "nsess_nortp" /
        "nsess_owrtp" /
        "nsess_nortcp" /
        "nsess_owrtcp" /
        "nplrs_created" /
        "nplrs_destroyed" /
        "npkts_rcvd" /
        "npkts_played" /
        "npkts_relayed" /
        "npkts_resizer_in" /
        "npkts_resizer_out" /
        "npkts_resizer_discard" /
        "npkts_discard" /
        "total_duration" /
        "ncmds_rcvd" /
        "ncmds_rcvd_ndups" /
        "ncmds_succd" /
        "ncmds_errs" /
        "ncmds_repld" /
        "rtpa_nsent" /
        "rtpa_nrcvd" /
        "rtpa_ndups" /
        "rtpa_perrs" )

Command

COMMAND = [COOKIE SEP] (C_DELETE / C_RECORD / C_PLAY / C_NOPLAY / C_COPY / C_UPDATE / C_LOOKUP / C_INFO / C_QUERY / C_VER_FEATURE / C_GET_VER / C_DELETE_ALL / C_GET_STATS ) [LF]

Positive reply

OK = "0"

Version reply

VERSION_ACK = "1"
VERSION_NUMBER = ( "20040107" / ; Basic RTP proxy functionality
        "20050322" / ; Support for multiple RTP streams and MOH
        "20060704" / ; Support for extra parameter in the V command
        "20071116" / ; Support for RTP re-packetization
        "20071218" / ; Support for forking (copying) RTP stream
        "20080403" / ; Support for RTP statistics querying
        "20081102" / ; Support for setting codecs in the update/lookup command
        "20081224" / ; Support for session timeout notifications
        "20090810" / ; Support for automatic bridging
        "20140323" / ; Support for tracking/reporting load
        "20140617" / ; Support for anchoring session connect time
        "20141004" / ; Support for extendable performance counters
        "20150330" ) ; Support for allocating a new port ("Un, Ln commands)

Negative reply

ECODE_CMDUNKN = "E0"
ECODE_PARSE_NARGS = "E1"
ECODE_PARSE_MODS = "E2"
ECODE_PARSE_1 = "E5"
ECODE_PARSE_2 = "E6"
ECODE_PARSE_3 = "E7"
ECODE_PARSE_4 = "E8"
ECODE_PARSE_5 = "E9"
ECODE_PARSE_10 = "E10"
ECODE_PARSE_11 = "E11"
ECODE_PARSE_12 = "E12"
ECODE_PARSE_13 = "E13"
ECODE_PARSE_14 = "E14"
ECODE_PARSE_15 = "E15"
ECODE_PARSE_16 = "E16"
ECODE_PARSE_6 = "E17"
ECODE_PARSE_7 = "E18"
ECODE_RTOOBIG_1 = "E25"
ECODE_INVLARG_1 = "E31"
ECODE_INVLARG_2 = "E32"
ECODE_INVLARG_3 = "E33"
ECODE_INVLARG_4 = "E34"
ECODE_INVLARG_5 = "E35"
ECODE_SESUNKN = "E50"
ECODE_PLRFAIL = "E60"
ECODE_CPYFAIL = "E65"
ECODE_STSFAIL = "E68"
ECODE_LSTFAIL_1 = "E71"
ECODE_LSTFAIL_2 = "E72"
ECODE_NOMEM_1 = "E81"
ECODE_NOMEM_2 = "E82"
ECODE_NOMEM_3 = "E83"
ECODE_NOMEM_4 = "E84"
ECODE_NOMEM_5 = "E85"
ECODE_NOMEM_6 = "E86"
ECODE_NOMEM_7 = "E87"
ECODE_NOMEM_8 = "E88"
ECODE_SLOWSHTDN = "E99"

ERROR_REPLY = ( ECODE_CMDUNKN / ECODE_PARSE_NARGS / ECODE_PARSE_MODS / ECODE_PARSE_1 / ECODE_PARSE_2 / ECODE_PARSE_3 / ECODE_PARSE_4 / ECODE_PARSE_5 / ECODE_PARSE_10 / ECODE_PARSE_11 / ECODE_PARSE_12 / ECODE_PARSE_13 / ECODE_PARSE_14 / ECODE_PARSE_15 / ECODE_PARSE_16 / ECODE_PARSE_6 / ECODE_PARSE_7 / ECODE_RTOOBIG_1 / ECODE_INVLARG_1 / ECODE_INVLARG_2 / ECODE_INVLARG_3 / ECODE_INVLARG_4 / ECODE_INVLARG_5 / ECODE_SESUNKN / ECODE_PLRFAIL / ECODE_CPYFAIL / ECODE_STSFAIL / ECODE_LSTFAIL_1 / ECODE_LSTFAIL_2 / ECODE_NOMEM_1 / ECODE_NOMEM_2 / ECODE_NOMEM_3 / ECODE_NOMEM_4 / ECODE_NOMEM_5 / ECODE_NOMEM_6 / ECODE_NOMEM_7 / ECODE_NOMEM_8 / ECODE_SLOWSHTDN )

Socket allocated

SOCKET_REPLY = PORT SEP ( IPv4 / "6" SEP IPv6)

Statistics

STATS_REPLY = 1* ([ STAT_NAME "="] 1*DIGIT SEP )

Information

INFO_REPLY = "sessions created: " 1*DIGIT  LF
        "active sessions: " 1*DIGIT LF
        "active streams: " 1*DIGIT LF
        "packets received: " 1*DIGIT LF
        "packets transmitted: " 1*DIGIT LF
        [ "average load: 0"  LF ] ; stub for now - always returns 0

Reply

REPLY = [COOKIE SEP]  ( OK / VERSION_ACK / VERSION_NUMBER / SOCKET_REPLY / STATS_REPLY / INFO_REPLY / ERROR_REPLY ) [LF]