From 8a4d548034e398b504b63b0248c84ae7732ed487 Mon Sep 17 00:00:00 2001 From: Richard Fuchs Date: Wed, 6 Mar 2013 11:49:52 -0500 Subject: [PATCH] update docs --- modules/rtpproxy-ng/README | 321 ++++++------------ .../doc/{rtpproxy.xml => rtpproxy-ng.xml} | 0 2 files changed, 96 insertions(+), 225 deletions(-) rename modules/rtpproxy-ng/doc/{rtpproxy.xml => rtpproxy-ng.xml} (100%) diff --git a/modules/rtpproxy-ng/README b/modules/rtpproxy-ng/README index 097db16c5..d48b7e177 100644 --- a/modules/rtpproxy-ng/README +++ b/modules/rtpproxy-ng/README @@ -1,4 +1,4 @@ -rtpproxy Module +rtpproxy-ng Module Maxim Sobolev @@ -30,6 +30,12 @@ Carsten Bock ng-voice GmbH +Edited by + +Richard Fuchs + + Sipwise GmbH + Copyright © 2003-2008 Sippy Software, Inc. Copyright © 2005 Voice Sistem SRL @@ -37,6 +43,8 @@ Carsten Bock Copyright © 2009-2012 TuTPro Inc. Copyright © 2010 VoIPEmbedded Inc. + + Copyright © 2013 Sipwise GmbH __________________________________________________________________ Table of Contents @@ -56,10 +64,7 @@ Carsten Bock 4.2. rtpproxy_disable_tout (integer) 4.3. rtpproxy_tout (integer) 4.4. rtpproxy_retr (integer) - 4.5. nortpproxy_str (string) - 4.6. timeout_socket (string) - 4.7. ice_candidate_priority_avp (string) - 4.8. extra_id_pv (string) + 4.5. extra_id_pv (string) 5. Functions @@ -69,11 +74,6 @@ Carsten Bock 5.4. rtpproxy_destroy([flags]) 5.5. unforce_rtp_proxy() 5.6. rtpproxy_manage([flags [, ip_address]]) - 5.7. rtpproxy_stream2uac(prompt_name, count), - 5.8. rtpproxy_stream2uas(prompt_name, count) - 5.9. rtpproxy_stop_stream2uac(), - 5.10. start_recording() - 5.11. rtpproxy_stop_stream2uas(prompt_name, count) 6. Exported Pseudo Variables @@ -92,20 +92,15 @@ Carsten Bock 1.2. Set rtpproxy_disable_tout parameter 1.3. Set rtpproxy_tout parameter 1.4. Set rtpproxy_retr parameter - 1.5. Set nortpproxy_str parameter - 1.6. Set timeout_socket parameter - 1.7. Set ice_candidate_priority_avp parameter - 1.8. Set extra_id_pv parameter - 1.9. set_rtp_proxy_set usage - 1.10. rtpproxy_offer usage - 1.11. rtpproxy_answer usage - 1.12. rtpproxy_destroy usage - 1.13. rtpproxy_manage usage - 1.14. rtpproxy_stream2xxx usage - 1.15. start_recording usage - 1.16. $rtpstat-Usage - 1.17. nh_enable_rtpp usage - 1.18. nh_show_rtpp usage + 1.5. Set extra_id_pv parameter + 1.6. set_rtp_proxy_set usage + 1.7. rtpproxy_offer usage + 1.8. rtpproxy_answer usage + 1.9. rtpproxy_destroy usage + 1.10. rtpproxy_manage usage + 1.11. $rtpstat-Usage + 1.12. nh_enable_rtpp usage + 1.13. nh_show_rtpp usage Chapter 1. Admin Guide @@ -124,10 +119,7 @@ Chapter 1. Admin Guide 4.2. rtpproxy_disable_tout (integer) 4.3. rtpproxy_tout (integer) 4.4. rtpproxy_retr (integer) - 4.5. nortpproxy_str (string) - 4.6. timeout_socket (string) - 4.7. ice_candidate_priority_avp (string) - 4.8. extra_id_pv (string) + 4.5. extra_id_pv (string) 5. Functions @@ -137,11 +129,6 @@ Chapter 1. Admin Guide 5.4. rtpproxy_destroy([flags]) 5.5. unforce_rtp_proxy() 5.6. rtpproxy_manage([flags [, ip_address]]) - 5.7. rtpproxy_stream2uac(prompt_name, count), - 5.8. rtpproxy_stream2uas(prompt_name, count) - 5.9. rtpproxy_stop_stream2uac(), - 5.10. start_recording() - 5.11. rtpproxy_stop_stream2uas(prompt_name, count) 6. Exported Pseudo Variables @@ -154,16 +141,18 @@ Chapter 1. Admin Guide 1. Overview - This is a module that enables media streams to be proxied via an - rtpproxy. Rtpproxies know to work with this module are Sippy RTPproxy - http://www.rtpproxy.org and ngcp-rtpproxy-ng - http://deb.sipwise.com/spce/2.6/pool/main/n/ngcp-mediaproxy-ng. Some - features of the rtpproxy module apply only to one of the two - rtpproxies. + 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 ngcp-rtpproxy-ng https://github.com/sipwise/mediaproxy-ng. + The rtpproxy-ng 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. 2. Multiple RTPProxy usage - The rtpproxy module can support multiple rtpproxies for + The rtpproxy-ng module can support multiple RTP proxies for balancing/distribution and control/selection purposes. The module allows definition of several sets of rtpproxies. @@ -209,10 +198,7 @@ Chapter 1. Admin Guide 4.2. rtpproxy_disable_tout (integer) 4.3. rtpproxy_tout (integer) 4.4. rtpproxy_retr (integer) - 4.5. nortpproxy_str (string) - 4.6. timeout_socket (string) - 4.7. ice_candidate_priority_avp (string) - 4.8. extra_id_pv (string) + 4.5. extra_id_pv (string) 4.1. rtpproxy_sock (string) @@ -224,39 +210,39 @@ Chapter 1. Admin Guide Example 1.1. Set rtpproxy_sock parameter ... # single rtproxy -modparam("rtpproxy", "rtpproxy_sock", "udp:localhost:12221") +modparam("rtpproxy-ng", "rtpproxy_sock", "udp:localhost:12221") # multiple rtproxies for LB -modparam("rtpproxy", "rtpproxy_sock", +modparam("rtpproxy-ng", "rtpproxy_sock", "udp:localhost:12221 udp:localhost:12222") # multiple sets of multiple rtproxies -modparam("rtpproxy", "rtpproxy_sock", +modparam("rtpproxy-ng", "rtpproxy_sock", "1 == udp:localhost:12221 udp:localhost:12222") -modparam("rtpproxy", "rtpproxy_sock", +modparam("rtpproxy-ng", "rtpproxy_sock", "2 == udp:localhost:12225") ... 4.2. rtpproxy_disable_tout (integer) - Once RTPProxy was found unreachable and marked as disabled, the - rtpproxy module will not attempt to establish communication to RTPProxy - for rtpproxy_disable_tout seconds. + Once an RTP proxy was found unreachable and marked as disabled, the + rtpproxy-ng module will not attempt to establish communication to that + RTP proxy for rtpproxy_disable_tout seconds. Default value is “60”. Example 1.2. Set rtpproxy_disable_tout parameter ... -modparam("rtpproxy", "rtpproxy_disable_tout", 20) +modparam("rtpproxy-ng", "rtpproxy_disable_tout", 20) ... 4.3. rtpproxy_tout (integer) - Timeout value in waiting for reply from RTPProxy. + Timeout value in waiting for reply from RTP proxy. Default value is “1”. Example 1.3. Set rtpproxy_tout parameter ... -modparam("rtpproxy", "rtpproxy_tout", 2) +modparam("rtpproxy-ng", "rtpproxy_tout", 2) ... 4.4. rtpproxy_retr (integer) @@ -268,62 +254,10 @@ modparam("rtpproxy", "rtpproxy_tout", 2) Example 1.4. Set rtpproxy_retr parameter ... -modparam("rtpproxy", "rtpproxy_retr", 2) -... - -4.5. nortpproxy_str (string) - - This parameter sets the SDP attribute used by rtpproxy to mark the - message's SDP attachemnt with information that it have already been - changed. - - If empty string, no marker will be added or checked. - -Note - - The string must be a complete SDP line, including the EOH (\r\n). - - Default value is “a=nortpproxy:yes\r\n”. - - Example 1.5. Set nortpproxy_str parameter -... -modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n") -... - -4.6. timeout_socket (string) - - The parameter sets the RTP timeout socket, which is transmitted to the - RTP-Proxy. It will be used by the RTP proxy to signal back that a media - stream timed out. - - If it is an empty string, no timeout socket will be transmitted to the - RTP-Proxy. - - Default value is “” (nothing). - - Example 1.6. Set timeout_socket parameter -... -modparam("nathelper", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2") -... - -4.7. ice_candidate_priority_avp (string) - - If specified and if value of the avp value is not 0, rtpproxy_manage - function adds ICE relay candidate attributes to sdp stream(s) - containing ICE candidate attributes. - - If value of the avp is 1, added candidates have high priority. If value - of the avp is 2 (default), added candidates have low priority. - - There is no default value meaning that no ICE relay candidates are - added in any circumstance. - - Example 1.7. Set ice_candidate_priority_avp parameter -... -modparam("rtpproxy", "ice_candidate_priority_avp", "$avp(ice_priority)") +modparam("rtpproxy-ng", "rtpproxy_retr", 2) ... -4.8. extra_id_pv (string) +4.5. extra_id_pv (string) The parameter sets the PV defination to use when the “b” parameter is used on unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or @@ -331,9 +265,9 @@ modparam("rtpproxy", "ice_candidate_priority_avp", "$avp(ice_priority)") Default is empty, the “b” parameter may not be used then. - Example 1.8. Set extra_id_pv parameter + Example 1.5. Set extra_id_pv parameter ... -modparam("rtpproxy", "extra_id_pv", "$avp(extra_id)") +modparam("rtpproxy-ng", "extra_id_pv", "$avp(extra_id)") ... 5. Functions @@ -344,11 +278,6 @@ modparam("rtpproxy", "extra_id_pv", "$avp(extra_id)") 5.4. rtpproxy_destroy([flags]) 5.5. unforce_rtp_proxy() 5.6. rtpproxy_manage([flags [, ip_address]]) - 5.7. rtpproxy_stream2uac(prompt_name, count), - 5.8. rtpproxy_stream2uas(prompt_name, count) - 5.9. rtpproxy_stop_stream2uac(), - 5.10. start_recording() - 5.11. rtpproxy_stop_stream2uas(prompt_name, count) 5.1. set_rtp_proxy_set(setid) @@ -360,7 +289,7 @@ modparam("rtpproxy", "extra_id_pv", "$avp(extra_id)") This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE. - Example 1.9. set_rtp_proxy_set usage + Example 1.6. set_rtp_proxy_set usage ... set_rtp_proxy_set("2"); rtpproxy_offer(); @@ -382,10 +311,10 @@ rtpproxy_offer(); “unforce_rtpproxy”, 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 - rtpproxy gets an “update” command for a new branch, and then a + rtpproxy 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 - “lookup” for the new branch. This flag is only supported by + “answer” for the new branch. This flag is only supported by the ngcp-mediaproxy-ng rtpproxy at the moment! + 2 - append second Via branch to Call-ID when sending command to rtpproxy. See flag '1' for its meaning. @@ -419,16 +348,21 @@ rtpproxy_offer(); 'ii' and 'ee'. So, for example if a SIP requests is processed with 'ie' flags, the corresponding response must be processed with 'ie' flags. + For ngcp-mediaproxy-ng, these flags are used to select between + IPv4 and IPv6 addresses, corresponding to 'i' and 'e' + respectively. For example, if the request is coming from an + IPv4 host and is going to an IPv6 host, the flags should be + specified as 'ie'. Note: As rtpproxy in bridge mode s per default asymmetric, you have to specify the 'w' flag for clients behind NAT! See also above notes! - + x - this flag a shortcut for using the "ie" or "ei"-flags of - RTP-Proxy, in order to do automatic bridging between IPv4 on - the "internal network" and IPv6 on the "external network". The - distinction is done by the given IP in the SDP, e.g. a IPv4 - Address will always call "ie" to the RTPProxy (IPv4(i) to - IPv6(e)) and an IPv6Address will always call "ei" to the - RTPProxy (IPv6(e) to IPv4(i)). + + x - this flag an alternative to the 'ie' or 'ei'-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 + ngcp-mediaproxy-ng. 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 @@ -461,11 +395,21 @@ rtpproxy_offer(); 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. + + + - instructs the RTP proxy to 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. + Without this flag, 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. + + - - instructs the RTP proxy to discard any ICE attributes and + not insert any new ones into the SDP. Mutually exclusive with + the '+' flag. * ip_address - new SDP IP address. This function can be used from ANY_ROUTE. - Example 1.10. rtpproxy_offer usage + Example 1.7. rtpproxy_offer usage route { ... if (is_method("INVITE")) { @@ -509,7 +453,7 @@ onreply_route[2] This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. - Example 1.11. rtpproxy_answer usage + Example 1.8. rtpproxy_answer usage See rtpproxy_offer() function example above for example. @@ -545,7 +489,7 @@ onreply_route[2] rtpproxy call when 200 OK is received on a branch, where rtpproxy is not needed. - Example 1.12. rtpproxy_destroy usage + Example 1.9. rtpproxy_destroy usage ... rtpproxy_destroy(); ... @@ -579,84 +523,11 @@ rtpproxy_destroy(); This function can be used from ANY_ROUTE. - Example 1.13. rtpproxy_manage usage + Example 1.10. rtpproxy_manage usage ... rtpproxy_manage(); ... -5.7. rtpproxy_stream2uac(prompt_name, count), - - Instruct the RTPproxy to stream prompt/announcement pre-encoded with - the makeann command from the RTPproxy distribution. The uac/uas suffix - selects who will hear the announcement relatively to the current - transaction - UAC or UAS. For example invoking the rtpproxy_stream2uac - in the request processing block on ACK transaction will play the prompt - to the UA that has generated original INVITE and ACK while - rtpproxy_stop_stream2uas on 183 in reply processing block will play the - prompt to the UA that has generated 183. - - Apart from generating announcements, another possible application of - this function is implementing music on hold (MOH) functionality. When - count is -1, the streaming will be in loop indefinitely until the - appropriate rtpproxy_stop_stream2xxx is issued. - - In order to work correctly, these functions require that a session in - the RTPproxy already exists. Also those functions don't alter the SDP, - so that they are not a substitute for calling rtpproxy_offer or - rtpproxy_answer. - - This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE. - - Meaning of the parameters is as follows: - * prompt_name - name of the prompt to stream. Should be either - absolute pathname or pathname relative to the directory where - RTPproxy runs. - * count - number of times the prompt should be repeated. A value of - -1 means that it will be streaming in a loop indefinitely, until - the appropriate rtpproxy_stop_stream2xxx is issued. - - Example 1.14. rtpproxy_stream2xxx usage -... - if (is_method("INVITE")) { - rtpproxy_offer(); - if (detect_hold()) { - rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1"); - } else { - rtpproxy_stop_stream2uas(); - }; - }; -... - -5.8. rtpproxy_stream2uas(prompt_name, count) - - See function rtpproxy_stream2uac(prompt_name, count). - -5.9. rtpproxy_stop_stream2uac(), - - Stop streaming of announcement/prompt/MOH started previously by the - respective rtpproxy_stream2xxx. The uac/uas suffix selects whose - announcement relatively to tha current transaction should be stopped - - UAC or UAS. - - These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE. - -5.10. start_recording() - - This function will send a signal to the RTP-Proxy to record the RTP - stream on the RTP-Proxy. This function is only supported by Sippy - RTPproxy at the moment! - - This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE. - - Example 1.15. start_recording usage -... -start_recording(); -... - -5.11. rtpproxy_stop_stream2uas(prompt_name, count) - - See function rtpproxy_stop_stream2uac(prompt_name, count). - 6. Exported Pseudo Variables 6.1. $rtpstart @@ -668,7 +539,7 @@ start_recording(); packet-counters. The statistics must be retrieved before the session is deleted (before unforce_rtpproxy()). - Example 1.16. $rtpstat-Usage + Example 1.11. $rtpstat-Usage ... append_hf("X-RTP-Statistics: $rtpstat\r\n"); ... @@ -691,7 +562,7 @@ start_recording(); NOTE: if a rtpproxy is defined multiple times (in the same or diferente sete), all of its instances will be enables/disabled. - Example 1.17. nh_enable_rtpp usage + Example 1.12. nh_enable_rtpp usage ... $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0 ... @@ -703,7 +574,7 @@ $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0 No parameter. - Example 1.18. nh_show_rtpp usage + Example 1.13. nh_show_rtpp usage ... $ kamctl fifo nh_show_rtpp ... @@ -717,38 +588,38 @@ Chapter 2. Frequently Asked Questions 2.1. - What happend with “rtpproxy_disable” parameter? + What happend with “rtpproxy_disable” parameter? - It was removed as it became obsolete - now “rtpproxy_sock” can take - empty value to disable the rtpproxy functionality. + It was removed as it became obsolete - now “rtpproxy_sock” can take + empty value to disable the rtpproxy functionality. 2.2. - Where can I find more about Kamailio? + Where can I find more about Kamailio? - Take a look at http://www.kamailio.org/. + Take a look at http://www.kamailio.org/. 2.3. - Where can I post a question about this module? + Where can I post a question about this module? - First at all check if your question was already answered on one of our - mailing lists: - * User Mailing List - - http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users - * Developer Mailing List - - http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev + First at all check if your question was already answered on one of our + mailing lists: + * User Mailing List - + http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users + * Developer Mailing List - + http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev - E-mails regarding any stable Kamailio release should be sent to - and e-mails regarding development - versions should be sent to . + E-mails regarding any stable Kamailio release should be sent to + and e-mails regarding development + versions should be sent to . - If you want to keep the mail private, send it to - . + If you want to keep the mail private, send it to + . 2.4. - How can I report a bug? + How can I report a bug? - Please follow the guidelines provided at: - http://sip-router.org/tracker. + Please follow the guidelines provided at: + http://sip-router.org/tracker. diff --git a/modules/rtpproxy-ng/doc/rtpproxy.xml b/modules/rtpproxy-ng/doc/rtpproxy-ng.xml similarity index 100% rename from modules/rtpproxy-ng/doc/rtpproxy.xml rename to modules/rtpproxy-ng/doc/rtpproxy-ng.xml