&adminguide;
Overview This is a module that enables media streams to be proxied via an &rtp; proxy. The only &rtp; proxy currently known to work with this module is the Sipwise rtpengine . The rtpengine module is a modified version of the original rtpproxy module using a new control protocol. The module is designed to be a drop-in replacement for the old module from a configuration file point of view, however due to the incompatible control protocol, it only works with &rtp; proxies which specifically support it.
Multiple &rtp; proxy usage The rtpengine module can support multiple &rtp; proxies for balancing/distribution and control/selection purposes. The module allows definition of several sets of rtpengines. Load-balancing will be performed over a set and the admin has the ability to choose what set should be used. The set is selected via its id - the id being defined with the set. Refer to the module parameter definition for syntax description. The balancing inside a set is done automatically by the module based on the weight of each &rtp; proxy from the set. The selection of the set is done from script prior using rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions - see the rtpengine_use_set() function. Another way to select the set is to define setid_avp module parameter and assign setid to the defined avp before calling rtpengine_offer() or rtpengine_manage() function. If forwarding of the requests fails and there is another branch to try, remember to unset the avp after calling rtpengine_delete() function. For backward compatibility reasons, a set with no id take by default the id 0. Also if no set is explicitly set before rtpengine_delete(), rtpengine_offer() or rtpengine_answer() the 0 id set will be used. IMPORTANT: if you use multiple sets, take care and use the same set for both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If the set was selected using setid_avp, the avp needs to be set only once before rtpengine_offer() or rtpengine_manage() call.
Dependencies
&osips; Modules The following modules must be loaded before this module: tm module - (optional) if you want to have rtpengine_manage() fully functional
External Libraries or Applications The following libraries or applications must be installed before running &osips; with this module loaded: None.
Exported Parameters
<varname>rtpengine_sock</varname> (string) Definition of socket(s) used to connect to (a set) &rtp; proxy. It may specify a UNIX socket or an IPv4/IPv6 UDP socket. Default value is NONE (disabled). Set <varname>rtpengine_sock</varname> parameter ... # single rtproxy modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221") # multiple rtproxies for LB modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221 udp:localhost:12222") # multiple sets of multiple rtproxies modparam("rtpengine", "rtpengine_sock", "1 == udp:localhost:12221 udp:localhost:12222") modparam("rtpengine", "rtpengine_sock", "2 == udp:localhost:12225") ...
<varname>rtpengine_disable_tout</varname> (integer) Once an &rtp; proxy was found unreachable and marked as disabled, the rtpengine module will not attempt to establish communication to that &rtp; proxy for rtpengine_disable_tout seconds. Default value is 60. Set <varname>rtpengine_disable_tout</varname> parameter ... modparam("rtpengine", "rtpengine_disable_tout", 20) ...
<varname>rtpengine_tout</varname> (integer) Timeout value in waiting for reply from &rtp; proxy. Default value is 1. Set <varname>rtpengine_tout</varname> parameter ... modparam("rtpengine", "rtpengine_tout", 2) ...
<varname>rtpengine_retr</varname> (integer) How many times the module should retry to send and receive after timeout was generated. Default value is 5. Set <varname>rtpengine_retr</varname> parameter ... modparam("rtpengine", "rtpengine_retr", 2) ...
<varname>extra_id_pv</varname> (string) The parameter sets the PV defination to use when the b parameter is used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or rtpengine_manage() command. Default is empty, the b parameter may not be used then. Set <varname>extra_id_pv</varname> parameter ... modparam("rtpengine", "extra_id_pv", "$avp(extra_id)") ...
<varname>setid_avp</varname> (string) The parameter defines an AVP that, if set, determines which &rtp; proxy set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and rtpengine_manage() functions use. There is no default value. Set <varname>setid_avp</varname> parameter ... modparam("rtpengine", "setid_avp", "$avp(setid)") ...
<varname>db_url</varname> (string) Database URL, used to load RTPEngines sockets from db, instead of specifying them in the script ( module parameter). Default value is NULL, no database is used. Set <varname>db_url</varname> parameter ... modparam("rtpengine", "db_url", "mysql://opensips:opensipsrw@localhost/opensips") ...
<varname>db_table</varname> (string) The table where the RTPEngines sockets are stored. Used when Database URL is provisioned. Default value is rtpengines. Set <varname>db_table</varname> parameter ... modparam("rtpengine", "db_table", "rtpengine_new") ...
<varname>socket_column</varname> (string) The name of the rtpengine socket column in the database table. Default value is socket. Set <varname>socket_column</varname> parameter ... modparam("rtpengine", "socket_column", "sock") ...
<varname>set_column</varname> (string) The name of the rtpengine set column in the database table. Default value is set_id. Set <varname>set_column</varname> parameter ... modparam("rtpengine", "set_column", "set_new") ...
Exported Functions
<function moreinfo="none">rtpengine_use_set(setid)</function> Sets the ID of the &rtp; proxy set to be used for the next rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or rtpengine_manage() command. The parameter is an integer. This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE. <function>rtpengine_use_set</function> usage ... rtpengine_use_set(2); rtpengine_offer(); ...
<function moreinfo="none">rtpengine_offer([flags[, sock_var[, sdp_pvar[, body]]]])</function> Rewrites &sdp; body to ensure that media is passed through an &rtp; proxy. To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK and on 200 OK when SDPs are in 200 OK and ACK. Meaning of the parameters is as follows: flags(string, optional) - flags to turn on some features. The flags string is a list of space-separated items. Each item is either an individual token, or a token in key=value format. The possible tokens are described below. When passing an option that &osips; is not aware of, it will be blindly sent to the rtpengine daemon to be processed. via-branch=... - Include the branch value of one of the Via headers in the request to the &rtp; proxy. Possible values are: 1 - use the first Via header; 2 - use the second Via header; auto - use the first Via header if this is a request, or the second one if this is a reply; extra - don't take the value from a header, but instead use the value of the variable. This can be used to create one media session per branch on the &rtp; proxy. When sending a subsequent delete command to the &rtp; proxy, you can then stop just the session for a specific branch when passing the flag '1' or '2' in the rtpengine_delete, or stop all sessions for a call when not passing one of those two flags there. This is especially useful if you have serially forked call scenarios where the &rtp; proxy gets an offer command for a new branch, and then a delete command for the previous branch, which would otherwise delete the full call, breaking the subsequent answer for the new branch. This flag is only supported by the Sipwise rtpengine &rtp; proxy at the moment! asymmetric - flags that UA from which message is received doesn't support symmetric RTP. (automatically sets the 'r' flag) force-answer - force answer, that is, only rewrite &sdp; when corresponding session already exists in the &rtp; proxy. By default is on when the session is to be completed. in-iface=..., out-iface=... - these flags specify the direction the SIP message. These flags only make sense when the &rtp; proxy is running in bridge mode. in-iface should indicate the proxy's inbound interface, and out-iface corresponds to the &rtp; proxy's outbound interface. You always have to specify two flags to define the incoming network and the outgoing network. For example, in-iface=internal out-iface=external should be used for SIP message received from the local interface and sent out on the external interface. internal, external - these the old flags used to specify the direction of call. They are now obsolate, being replaced by the in-iface=internal out-iface=external configuration. auto-bridge - this flag an alternative to the internal and external flags in order to do automatic bridging between IPv4 on the "internal network" and IPv6 on the "external network". Instead of explicitly instructing the &rtp; proxy to select a particular address family, the distinction is done by the given IP in the SDP body by the RTP proxy itself. Not supported by Sipwise rtpengine. address-family=... - instructs the &rtp; proxy that the recipient of this &sdp; body expects to see addresses of a particular family. Possible values are IP4 and IP6. For example, if the &sdp; body contains IPv4 addresses but the recipient only speaks IPv6, you would use address-family=IP6 to bridge between the two address families. Sipwise rtpengine remembers the address family preference of each party after it has seen an &sdp; body from them. This means that normally it is only necessary to explicitly specify the address family in the offer, but not in the answer. Note: Please note, that this will only work properly with non-dual-stack user-agents or with dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations). This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests having different m-lines with different IP-protocols grouped together. force - instructs the &rtp; proxy to ignore marks inserted by another &rtp; proxy in transit to indicate that the session is already goes through another proxy. Allows creating a chain of proxies. Not supported and ignored by Sipwise rtpengine. trust-address - flags that IP address in SDP should be trusted. Without this flag, the &rtp; proxy ignores address in the SDP and uses source address of the SIP message as media address which is passed to the RTP proxy. replace-origin - flags that IP from the origin description (o=) should be also changed. replace-session-connection - flags to change the session-level SDP connection (c=) IP if media description also includes connection information. symmetric - flags that for the UA from which message is received, support symmetric RTP must be forced. You do not need to explicitly specify this value, as it is the default, and the behavior is only changed when the asymmetric is used. repacketize=NN - requests the &rtp; proxy to perform re-packetization of RTP traffic coming from the UA which has sent the current message to increase or decrease payload size per each RTP packet forwarded if possible. The NN is the target payload size in ms, for the most codecs its value should be in 10ms increments, however for some codecs the increment could differ (e.g. 30ms for GSM or 20ms for G.723). The &rtp; proxy would select the closest value supported by the codec. This feature could be used for significantly reducing bandwith overhead for low bitrate codecs, for example with G.729 going from 10ms to 100ms saves two thirds of the network bandwith. Not supported by Sipwise rtpengine. loop-protect - flag that instructs &rtp; to avoid rewriting the SDP when looping the same message. ICE=... - controls the &rtp; proxy's behaviour regarding ICE attributes within the &sdp; body. Possible values are: force - discard any ICE attributes already present in the &sdp; body and then generate and insert new ICE data, leaving itself as the only ICE candidates; remove instructs the &rtp; proxy to discard any ICE attributes and not insert any new ones into the &sdp;. The default (if no ICE=... is given at all), new ICE data will only be generated if no ICE was present in the &sdp; originally; otherwise the &rtp; proxy will only insert itself as an additional ICE candidate. Other &sdp; substitutions (c=, m=, etc) are unaffected by this flag. RTP, SRTP, AVP, AVPF - These flags control the &rtp; transport protocol that should be used towards the recipient of the &sdp;. If none of them are specified, the protocol given in the &sdp; is left untouched. Otherwise, the SRTP flag indicates that SRTP should be used, while RTP indicates that SRTP should not be used. AVPF indicates that the advanced RTCP profile with feedback messages should be used, and AVP indicates that the regular RTCP profile should be used. See also the next set of flags below. RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve as an alternative, more explicit way to select between the different &rtp; protocols and profiles supported by the &rtp; proxy. For example, giving the flag RTP/SAVPF has the same effect as giving the two flags SRTP AVPF. to-tag - force inclusion of the To tag. Normally, the To tag is always included when present, except for delete messages. Including the To tag in a delete messages allows you to be more selective about which dialogues within a call are being torn down. to-tag=... - use the specified string as To tag instead of the actual To tag from the &sip; message, and force inclusion of the tag in the message as per above. from-tag=... - use the specified string as From tag instead of the actual From tag from the &sip; message. call-id=... - use the specified string as Call-ID instead of the actual Call-ID from the &sip; message. rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the &rtp; proxy accept the offer, but not offer it to the recipient of this message. rtcp-mux-reject - if rtcp-mux was offered, make the &rtp; proxy reject the offer, but still offer it to the recipient. Can be combined with rtcp-mux-offer to always offer it. rtcp-mux-offer - make the &rtp; proxy offer rtcp-mux to the recipient of this message, regardless of whether it was offered originally or not. rtcp-mux-require - Similar to offer but pretends that the client has accepted rtcp-mux. This breaks RFC 5761 and will not advertise seperate RTCP ports. This option is necessary for WebRTC clients. rtcp-mux-accept - if rtcp-mux was offered, make the &rtp; proxy accept the offer and also offer it to the recipient of this message. Can be combined with rtcp-mux-offer to always offer it. media-address=... - force a particular media address to be used in the &sdp; body. Address family is detected automatically. record-call=yes/no - indicates whether rtpengine should record the call or not. When using this parameter, you may pass further information in the metadata. transcode-CODEC - used only for offer, indicates that rtpengine should transcode the CODEC towards the B-side. Example: transcode-PCMA will present to the B-side the PCMA codec. codec-strip-CODEC - used only for offer, indicates that the A-side of the call will not end up talking CODEC. Example: codec-strip-PCMA will prevent the A-side from receiving the PCMA codec. codec-mask-CODEC - used only for offer, indicates that the A-side will use the CODEC, but it will not be presented to the B-side. Example: codec-mask-PCMA will make the A-side receive the PCMA codec, but B-side will use something else. sock_var(var, optional) - variable used to store the rtpengine socket chosen for this call. sdp_var(var, optional) - variable used to store the full SDP received from rtpengine. You can perform any additional changes on this string. Important: when providing this variable, the message body is no longer changed, so you have to manually replace it!. body(string, optional) - used to provide a specific body to the rtpengine_* function. If this parameter is missing the body of the current message is used. This function can be used from ANY_ROUTE. <function>rtpengine_offer</function> usage route { ... if (is_method("INVITE")) { if (has_body("application/sdp")) { if (rtpengine_offer()) t_on_reply("1"); } else { t_on_reply("2"); } } if (is_method("ACK") && has_body("application/sdp")) rtpengine_answer(); ... } onreply_route[1] { ... if (has_body("application/sdp")) rtpengine_answer(); ... } onreply_route[2] { ... if (has_body("application/sdp")) rtpengine_offer(); ... } <function>rtpengine_offer</function> usage with body replace ... if (rtpengine_offer(, $var(socket), $var(body), $rb)) { xlog("Used rtpengine $var(socket)\n"); # make all the changes on the resulted SDP in $var(body) ... remove_body_part(); add_body_part($var(body), "application/sdp"); } ... <function>rtpengine_offer</function> usage with call recording ... $var(rtpengine_flags) = $var(rtpengine_flags) + " record-call=yes"; $json(recording_keys) := "{}"; $json(recording_keys/callId) = $ci; $json(recording_keys/fromUser) = $dlg_val(recording_from_user); $json(recording_keys/fromDomain) = $dlg_val(recording_from_domain); $json(recording_keys/fromTag) = $dlg_val(recording_from_tag); $json(recording_keys/toUser) = $dlg_val(recording_to_user); $json(recording_keys/toDomain) = $dlg_val(recording_to_domain); $var(rtpengine_flags) = $var(rtpengine_flags) + " metadata=" + $(json(recording_keys){s.encode.hexa}); rtpengine_offer($var(rtpengine_flags)); ... <function>rtpengine_offer</function> usage for transcoding ... # Goal: make A-side talk PCMA and B-side talk opus # * do not present PCMA to B-side: codec-mask-PCMA, but use it on A-side # * do not use opus for A-side: codec-strip-opus # * offer opus to B-side: transcode-opus rtpengine_offer("... codec-mask-PCMA codec-strip-opus transcode-opus ..."); ...
<function moreinfo="none">rtpengine_answer([flags[, sock_pvar[, sdp_pvar[, body]]]])</function> Rewrites &sdp; body to ensure that media is passed through an &rtp; proxy. To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK and on ACK when SDPs are in 200 OK and ACK. See rtpengine_offer() function description above for the meaning of the parameters. This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. <function>rtpengine_answer</function> usage See rtpengine_offer() function example above for examples.
<function moreinfo="none">rtpengine_delete([flags[, sock_var]])</function> Tears down the RTPProxy session for the current call. See rtpengine_offer() function description above for the meaning of the parameters. Note that not all flags make sense for a delete. This function can be used from ANY_ROUTE. <function>rtpengine_delete</function> usage ... rtpengine_delete(); ...
<function moreinfo="none">rtpengine_manage([flags[, sock_var[, sdp_var[, body]]]])</function> Manage the RTPProxy session - it combines the functionality of rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting internally based on message type and method which one to execute. It can take the same parameters as rtpengine_offer(). The flags parameter to rtpengine_manage() can be a configuration variable containing the flags as a string. Functionality: If INVITE with SDP, then do rtpengine_offer() If INVITE with SDP, when the tm module is loaded, mark transaction with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for rtpengine_answer() If ACK with SDP, then do rtpengine_answer() If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do rtpengine_delete() If reply to INVITE with code >= 300 do rtpengine_delete() If reply with SDP to INVITE having code 1xx and 2xx, then do rtpengine_answer() if the request had SDP or tm is not loaded, otherwise do rtpengine_offer() This function can be used from ANY_ROUTE. <function>rtpengine_manage</function> usage ... rtpengine_manage(); ...
<function moreinfo="none">rtpengine_start_recording([sock_var])</function> This function will send a signal to the &rtp; proxy to record the RTP stream on the &rtp; proxy. This function is not supported by Sipwise rtpengine at the moment! Meaning of the parameters is as follows: sock_var(var, optional) - variable used to store the rtpengine socket chosen for this call. This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE. <function>rtpengine_start_recording</function> usage ... rtpengine_start_recording(); ...
Exported Pseudo-Variables
<function moreinfo="none">$rtpstat</function> Returns the &rtp; statistics from the &rtp; proxy. The &rtp; statistics from the &rtp; proxy are provided as a string and it does contain several packet counters. $rtpstat Usage ... append_hf("X-RTP-Statistics: $rtpstat\r\n"); ...
<function moreinfo="none">$rtpstat(STAT)[index]</function> Returnes one of the pre-fined statistics listed below: MOS-average - without an index, it returns the average MOS value, expressed in an integer between 0 and 50, of all the RTP streams involved in the call, both caller and callee. If index is specified, it has to be one of the from-tag or to-tag involved in the call. In this case, the variable will return the average MOS of all the streams generated by that endpoint with the associated tag value. If you need more granular statistics, check the $rtpquery variable. MOS-min - without an index, it returns the minimum MOS value (integer value between 0 and 50) of all RTP streams involved in the call, both caller and callee. If the index is specified, it has the same effect as for MOS-average. MOS-max - without an index, it returns the maximum MOS value (integer value between 0 and 50) of all RTP streams involved in the call, both caller and callee. If the index is specified, it has the same effect as for MOS-average. MOS-min-at - without an index, it returns the time in seconds elapsed from the start of the call when the MOS value is minimum. If the index is specified, it has the same effect as for MOS-average. MOS-max-at - without an index, it returns the time in seconds elapsed from the start of the call when the MOS value is maximum. If the index is specified, it has the same effect as for MOS-average. NOTE: all these statistics are computed based on the statistics generated by RTPEngine. Some of them might not be available for all the calls (i.e. MOS cannot be computed if the call is too short, or if the phones do not properly report RTP statistics over RTCP). In these cases the variable returns the NULL value. $rtpstat(STAT) ... xlog("Average MOS of the entire call is $rtpstat(MOS-average)\r\n"); xlog("Average MOS of caller is $(rtpstat(MOS-average)[$ft])\r\n"); xlog("Average MOS of callee is $(rtpstat(MOS-average)[$tt])\r\n"); xlog("Min MOS of caller is $(rtpstat(MOS-min)[$ft]) reported at $(rtpstat(MOS-min-at)[$ft])\r\n"); ...
<function moreinfo="none">$rtpquery</function> Does a Query command to the &rtp; proxy and returns the answer in a JSON format. You can use this variable to fetch arbitrary data from the &rtp; proxy such as raw statistics about the call, or other indicators. You can use a $json() variable to parse its output and extract any information from the query, such as RTP statistics, or MOS values. $rtpquery Usage ... $json(reply) := $rtpquery; xlog("Total RTP Stats: $json(reply/totals)\n"); ...
Exported MI Functions
<function moreinfo="none">rtpengine_enable</function> Enables/disables a &rtp; proxy. Parameters: url - the &rtp; proxy url (exactly as defined in the config file). enable - 1 - enable, 0 - disable the &rtp; proxy. NOTE: if a &rtp; proxy is defined multiple times (in the same or different set), all of its instances will be enables/disabled. <function moreinfo="none">rtpengine_enable</function> usage ... $ opensips-cli -x mi rtpengine_enable udp:192.168.2.133:8081 0 ...
<function moreinfo="none">rtpengine_show</function> Displays all the &rtp; proxies and their information: set and status (disabled or not, weight and recheck_ticks). No parameter. <function moreinfo="none">rtpengine_show</function> usage ... $ opensips-cli -x mi rtpengine_show ...
<function moreinfo="none">rtpengine_reload</function> Reloads all rtpengine sets from the database. Used only when the parameter is set. No parameter. <function moreinfo="none">rtpengine_reload</function> usage ... $ opensips-cli -x mi rtpengine_reload ...
<function moreinfo="none">teardown</function> Terminates the SIP dialog by the SIP Call-ID given as parameter. Parameters: callid - SIP Call-ID. Note this is a just a wrapper function over the dlg_end_dlg MI function provided by the dialog module. This wrapping is done just to make rtpengine happy when trying to terminate SIP calls based on RTP timeouts. <function moreinfo="none">teardown</function> usage ... $ opensips-cli -x mi teardown Y2IwYjQ2YmE2ZDg5MWVkNDNkZGIwZjAzNGM1ZDY0ZDQ ...