Kamailio-开源SIP软交换平台

中国第一个专注Kamailio SIP 软交换技术分享平台

用户工具

站点工具


iptrtpproxy_nat_traversal_module_using_kernel_for_media_relay_released

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

iptrtpproxy_nat_traversal_module_using_kernel_for_media_relay_released [2017/09/11 11:41] (当前版本)
james_zhu 创建
行 1: 行 1:
 +====== The Iptrtpproxy module ======
  
 +==== Tomas Mandys ====
 +
 +Iptel.org\\ ​
 +
 +Copyright © 2007 Tomas Mandys
 +
 +----
 +
 +**Table of Contents**
 +
 +  * **1. Admin Guide** ​
 +    * **1. Overview** ​
 +    * **2. Known limitations** ​
 +    * **3. Dependencies** ​
 +    * **4. Parameters** ​
 +      * **4.1. config (string)** ​
 +      * **4.2. switchboard (string)** ​
 +      * **4.3. rpc_heartbeat_timeout (int)** ​
 +      * **4.4. hostname (string)** ​
 +      * **4.5. declare_codec (string)** ​
 +      * **4.6. codec_set (string)** ​
 +    * **5. Functions** ​
 +      * **5.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])** ​
 +      * **5.2. iptrtpproxy_update(gate_a_to_b,​ session_ids)** ​
 +      * **5.3. iptrtpproxy_adjust_timeout(gate_a_to_b,​ session_ids)** ​
 +      * **5.4. iptrtpproxy_delete(session_ids)** ​
 +      * **5.5. iptrtpproxy_authorize_media()** ​
 +      * **5.6. iptrtpproxy_set_param(param,​ value)** ​
 +      * **5.7. iptrtpproxy_set_param("​(aggregation/​switchboard)_by_sip_ip%%_(%%a/​b)",​ sip_ip)** ​
 +      * **5.8. iptrtpproxy_set_param("​protected_session_ids",​ sess_ids)** ​
 +      * **5.9. iptrtpproxy_set_param("​o_name",​ value)** ​
 +      * **5.10. iptrtpproxy_set_param("​o_addr",​ value)** ​
 +      * **5.11. iptrtpproxy_set_param("​codec_set",​ value)** ​
 +      * **5.12. iptrtpproxy_set_param("​remove_codec_mask",​ value)** ​
 +    * **6. Selects** ​
 +      * **6.1. @iptrtpproxy.session_ids** ​
 +      * **6.2. @iptrtpproxy.sdp_ip** ​
 +      * **6.3. @iptrtpproxy.o_name** ​
 +      * **6.4. @iptrtpproxy.o_addr** ​
 +      * **6.5. @iptrtpproxy.auth_rights** ​
 +      * **6.6. @iptrtpproxy.active_media_num** ​
 +
 +**List of Examples**
 +
 +  * **1.1. Declare switchboard** ​
 +  * **1.2. Declare codec_set** ​
 +  * **1.3. iptrtpproxy_alloc usage** ​
 +  * **1.4. iptrtpproxy_update usage** ​
 +  * **1.5. iptrtpproxy_adjust_timeout usage** ​
 +  * **1.6. iptrtpproxy_delete usage** ​
 +  * **1.7. iptrtpproxy_authorize_media usage** ​
 +
 +====== Chapter 1. Admin Guide ======
 +
 +**Table of Contents**
 +
 +  * **1. Overview** ​
 +  * **2. Known limitations** ​
 +  * **3. Dependencies** ​
 +  * **4. Parameters** ​
 +    * **4.1. config (string)** ​
 +    * **4.2. switchboard (string)** ​
 +    * **4.3. rpc_heartbeat_timeout (int)** ​
 +    * **4.4. hostname (string)** ​
 +    * **4.5. declare_codec (string)** ​
 +    * **4.6. codec_set (string)** ​
 +  * **5. Functions** ​
 +    * **5.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])** ​
 +    * **5.2. iptrtpproxy_update(gate_a_to_b,​ session_ids)** ​
 +    * **5.3. iptrtpproxy_adjust_timeout(gate_a_to_b,​ session_ids)** ​
 +    * **5.4. iptrtpproxy_delete(session_ids)** ​
 +    * **5.5. iptrtpproxy_authorize_media()** ​
 +    * **5.6. iptrtpproxy_set_param(param,​ value)** ​
 +    * **5.7. iptrtpproxy_set_param("​(aggregation/​switchboard)_by_sip_ip%%_(%%a/​b)",​ sip_ip)** ​
 +    * **5.8. iptrtpproxy_set_param("​protected_session_ids",​ sess_ids)** ​
 +    * **5.9. iptrtpproxy_set_param("​o_name",​ value)** ​
 +    * **5.10. iptrtpproxy_set_param("​o_addr",​ value)** ​
 +    * **5.11. iptrtpproxy_set_param("​codec_set",​ value)** ​
 +    * **5.12. iptrtpproxy_set_param("​remove_codec_mask",​ value)** ​
 +  * **6. Selects** ​
 +    * **6.1. @iptrtpproxy.session_ids** ​
 +    * **6.2. @iptrtpproxy.sdp_ip** ​
 +    * **6.3. @iptrtpproxy.o_name** ​
 +    * **6.4. @iptrtpproxy.o_addr** ​
 +    * **6.5. @iptrtpproxy.auth_rights** ​
 +    * **6.6. @iptrtpproxy.active_media_num** ​
 +
 +===== 1. Overview =====
 +
 +This module provides similar functionality as nathelper but communicates with netfilter kernel xt_RTPPROXY module using the libipt_RTPPROXY userspace library. All RTP streams are manipulated directly in kernel space, no data is copied from kernel to userspace and back, it reduces load and delay. See [[http://​www.2p.cz/​en/​netfilter_rtp_proxy|http://​www.2p.cz/​en/​netfilter_rtp_proxy]] for more details.
 +
 +This Kamailio module is written as a light-weight module, there is no dialog management as in Nathelper. The reason is that such an API should be provided by core or a specialized dialog manager module. Because such module is not in git, session information may be stored in extra attributes of the avp_db module and the session id itself in record route as cookie, see the rr module.
 +
 +It should be able to support all cases as re-invites when SIP client offers media change in SDP and when number of medias in offer/​answer are different.
 +
 +Nathelper may be still used for testing if client is behind the NAT.
 +
 +There is also support for media authorization. Number of codec sets may be defined. When a message containing SDP offer/​answer is being processed then current codecs and streams may be inspected, removed or signallized according a codec set.
 +
 +===== 2. Known limitations =====
 +
 +  * Only IPv4 addresses are supported. ​
 +  * More media streams per session supported ​
 +
 +===== 3. Dependencies =====
 +
 +The following libraries or applications must be installed before running Kamailio with this module loaded:
 +
 +  * netfilter xt_RTPPROXY & libipt_RTPPROXY,​ see [[http://​www.2p.cz/​en/​netfilter_rtp_proxy|http://​www.2p.cz/​en/​netfilter_rtp_proxy]] ​
 +
 +==== Note ====
 +
 +The modules Makefile must be edited and iptdir setup to the directory with the iptable sources (if different from ~/​iptables). Alternatively compile the module using:
 +
 +<​code>​
 +                make -C modules/​iptrtpproxy iptdir=path_to_iptables_src
 +</​code>​
 +
 +===== 4. Parameters =====
 +
 +==== 4.1. config (string) ====
 +
 +References iptrtpproxy.cfg,​ see iptrtpproxy_helper. Default value is /​etc/​iptrtpproxy.cfg. If only codec authorization is to be used then /dev/null may be used.
 +
 +==== 4.2. switchboard (string) ====
 +
 +References xt_RTPPROXY switchboard for usage by ser module.
 +
 +The format is:
 +
 +<​code>​
 +  "​name="​ value * ( ";"​ name "​="​ value )
 +
 +  name =  "​aggregation"​ | "​sip-addr-"​
 +</​code>​
 +
 +The name is the switchboard name as declared in config and will be used by script functions and references switchboard. It's mandatory parameter. The special name * set values for all switchboards.
 +
 +The sip-addr is address used by ''​iptrtpproxy_ser_param(by_sip_ip)''​ to find a switchboard for particular connection. If not explicitly configured then RTP switchboard gate address are used for this feature.
 +
 +The aggregation enables to aggregate more switchboards in cluster and to widden bandwidth. Aggregation will take sip-addr from the first switchboard of its.
 +
 +**Example 1.1. Declare ''​switchboard''​**
 +
 +<​code>​
 +    ...
 +        modparam("​iptrtpproxy",​ "​config",​ "/​etc/​iptrtpproxy.cfg"​);​
 +        modparam("​iptrtpproxy",​ "​switchboard",​ "​name=my1;​sip-addr-a=1.2.3.4;​sip-addr-b=5.6.7.8"​);​
 +        modparam("​iptrtpproxy",​ "​switchboard",​ "​name=my2;​sip-addr-a=2.3.4.5;​sip-addr-b=3.4.5.6;​aggregation=my23"​);​
 +        modparam("​iptrtpproxy",​ "​switchboard",​ "​name=my3;​aggregation=my23"​);​
 +        modparam("​iptrtpproxy",​ "​switchboard",​ "​name=*;​aggregation=my123"​);​
 +        ...
 +</​code>​
 +
 +\\ ==== 4.3. rpc_heartbeat_timeout (int) ====
 +
 +Timeout in seconds used for rerequest remote RTP proxy via RPC command after preceeding error. In other words if a RPC server is unresponsive at the moment then next attempt will be forced after this timeout. Default value is 30.
 +
 +==== 4.4. hostname (string) ====
 +
 +The hostname used by RPC to identify machine where Ser is running to communicate which RTP proxy via local interface. Default value is taken from system hostname.
 +
 +==== 4.5. declare_codec (string) ====
 +
 +There are basic implicit codecs compiled in module, more codecs may be added by this parameter (one codec per modparam).
 +
 +==== 4.6. codec_set (string) ====
 +
 +Declares new codec set. Codecs are declared for each media type independently.
 +
 +The format is:
 +
 +<​code>​
 +  "​name="​ value * ( ";"​ name "​="​ value )
 +
 +  name =  "​media_type"​ | "​rights"​ | "​codecs"​ | "​max_streams"​ | ( "​rtp"​ | "​rtcp"​ ) "​_"​ ( "​bytes"​ | "​packets"​ )
 +
 +  media_types = "​audio"​ | "​video"​ | "​application"​ | "​text"​ | "​message"​ | "​data"​ | "​control"​ | "?"​ | "​*"​
 +</​code>​
 +
 +The name is the codec set name to be defined.
 +
 +The media_type belongs to type at m= SDP line. Question mark means "​unknown media" type and asterisk "all media types"​.
 +
 +The max_streams defines how many streams (m= lines) is allowed per media type.
 +
 +The rights defines if particular codec is allowed 0, disallowed, i.e. will be removed if bit AND operation with ''​remove_codec_mask''​ is non-zero or its presence will be signallized by ''​@iptrtpproxy.auth_rights''​ (any other value).
 +
 +The codecs comma separated list of codecs. Previous media_type&​rights will be applied.
 +
 +The rtp/​rtcp_bytes/​packets limits bandwidth per media_type (0 is unlimited). It will override bandwidth limited by ''​iptrtpproxy_set_param("​throttle%%_*%%"​)''​.
 +
 +**Example 1.2. Declare ''​codec_set''​**
 +
 +<​code>​
 +    ...
 +        # enable all codecs, default state when codec is declared
 +        modparam("​iptrtpproxy",​ "​codec_set",​ "​name=cs1;​media_type=*;​max_streams=9999;​rights=0;​codecs=*"​);​
 +        # allow only 2 audio and 1 video stream
 +        modparam("​iptrtpproxy",​ "​codec_set",​ "​name=cs2;​media_type=*;​max_streams=0;​media_type=audio;​max_streams=2;​media_type=video;​max_streams=1"​);​
 +        # dtto, allow only a few audio and video codecs, GSM codec is allowed but signallized
 +        modparam("​iptrtpproxy",​ "​codec_set",​ "​name=cs3;​media_type=*;​max_streams=0;​rights=1;​codecs=*;​media_type=audio;​max_streams=2;​rights=0;​codecs=PCMU,​G729,​G728,​parityfec,​telephone-events;​rights=2;​codecs=GSM;​media_type=video;​max_streams=1;​rights=0;​codecs=jpeg,​parityfec"​);​
 +        # limit max. bandwidth for video¨ ​      
 +        modparam("​iptrtpproxy",​ "​codec_set",​ "​name=cs4;​media_type=video;​rtp_bytes=10000;​rtcp_bytes=1000"​);​
 +        ...
 +</​code>​
 +
 +\\ ===== 5. Functions =====
 +
 +==== 5.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids]) ====
 +
 +Parses SDP content and allocates for each RTP media stream one RTP proxy session. SDP is updates to reflect allocated sessions. Switchboard/​aggregation is set using ''​iptrtpproxy_set_param(by_sip_ip)''​ or ''​iptrtpproxy_set_param("​switchboard/​aggregation"​)''​.
 +
 +Aggregation supports load balancing among more RTP proxies controlled by RPC. The module try to allocate at machines/​switchboards in following order (priorities) not yet asked (or being heartbeated) machines, responsive machines, switchboards having percentualy more free slots, non responsive machines.
 +
 +Proxy may hide caller identity provided at o= line using ''​@iptrtpproxy.o_name/​addr''​ and ''​iptrtpproxy_set_param(o_name/​addr)''​ functions. But the script is responsible for rewritting to original values in a response or a callee initiated re-INVITE. Therefore original value need to be stored in-dialog.
 +
 +  * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b direction. ​
 +  * protected_session_ids list of existing sessions enables reusing already allocated sessions in re-INVITE without allocating new sessions for each stream in SDP regardless a IP/port is required. It's mostly undesirable,​ typically "​hold-on"​ is done via re-INVITE without any change. There is drawback because callee cannot change IP:port in 200OK which is legal case in RFC3264. But because some non-RFC3264 compliant phones dislike proactively changed IP:port at RTP proxy it seems it's less evil. 
 +  * function returns true is a session was created, identifier is available via select ''​@iptrtpproxy.session_ids''​. ​
 +
 +**Example 1.3. ''​iptrtpproxy_alloc''​ usage**
 +
 +<​code>​
 +    ...
 +        if (!iptrtpproxy_set_param("​aggregation_by_sip_ip_a",​ "​@received.ip"​)) {
 +                if (!iptrtpproxy_set_param("​switchboard_by_sip_ip_a",​ "​@received.ip"​)) {
 +                        t_reply("​500",​ "RTP proxy error"​);​
 +                        drop;
 +                }
 +        }
 +        eval_push("​x:​%@next_hop.src_ip"​);​
 +        if (@eval.get[-1] == @received.ip) {
 +                if (@iptrtpproxy.aggregation_a) {
 +                        iptrtpproxy_set_param("​aggregation_b",​ "​@iptrtpproxy.aggregation_a"​);​
 +                }
 +                else {
 +                        iptrtpproxy_set_param("​switchboard_b",​ "​@iptrtpproxy.switchboard_a"​);​
 +                }
 +        }
 +        else {
 +                if (!iptrtpproxy_set_param("​aggregation_by_sip_ip_b",​ "​@eval.get[-1]"​)) {
 +                        if (!iptrtpproxy_set_param("​switchboard_by_sip_ip_b",​ "​@eval.get[-1]"​)) {
 +                                t_reply("​500",​ "RTP proxy error"​);​
 +                                drop;
 +                        }
 +                }
 +        }
 +        eval_remove(-1,​ 1);
 +        ​
 +        if (!iptrtpproxy_alloc("​1"​)) {
 +                t_reply("​500",​ "RTP proxy error"​);​
 +                drop;
 +        }
 +        $sess_ids = @iptrtpproxy.session_ids;​
 +        ...
 +</​code>​
 +
 +\\ ==== 5.2. iptrtpproxy_update(gate_a_to_b,​ session_ids) ====
 +
 +Parses SDP content and updates sessions provided by session_ids and updates SDP. If succesfull then session_ids may be changed (in case e.g. media stream has port zero particular session is released), the result of ''​@iptrtpproxy.session_ids''​ should be stored for future in-dialog usage.
 +
 +The SDP contect is also affected by ''​iptrtpproxy_set_param(o_name/​addr)''​ functions. If a stream is deactivated in SDP then Sessions may be deleted unless mentioned in protected_session_ids.
 +
 +  * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b direction. if gate_a_to_b bit 1 is set then SDP is updated only, no RTP session are affected. Should be used when handling retransmission in onreply route, retransmission replies are not eaten be tm module! ​
 +
 +**Example 1.4. ''​iptrtpproxy_update''​ usage**
 +
 +<​code>​
 +    ...
 +        # load $sess_ids from dialog
 +        if (iptrtpproxy_update("​0",​ $sess_ids)) {
 +          $sess_ids = @iptrtpproxy.session_ids;​
 +          # save sess_ids in dialog
 +        }
 +        ...
 +</​code>​
 +
 +\\ ==== 5.3. iptrtpproxy_adjust_timeout(gate_a_to_b,​ session_ids) ====
 +
 +Adjust timeout for particular gate. It's useful in "200 OK" decrease timeout to learning timeout if INVITE has set (long) ringing timeout.
 +
 +  * if gate_a_to_b bit 0 is set then it regards to gate-a to gate-b direction. ​
 +
 +**Example 1.5. ''​iptrtpproxy_adjust_timeout''​ usage**
 +
 +<​code>​
 +    ...
 +        # load $sess_ids from dialog
 +        if (status=~"​18[0-9]"​) {
 +                iptrtpproxy_set_param("​learning_timeout",​ "​60"​);​
 +        }
 +        else {
 +                iptrtpproxy_set_param("​learning_timeout",​ "​5"​);​
 +        }
 +        if (iptrtpproxy_adjust_timeout("​0",​ $sess_ids)) {
 +        }
 +        ...
 +</​code>​
 +
 +\\ ==== 5.4. iptrtpproxy_delete(session_ids) ====
 +
 +Delete sessions identified by session_ids. May be used when dialog is being destroyed (BYE) or when INVITE failed in failure route. If protected_session_ids list is provided then this set is excluded from sessions to be deleted.
 +
 +**Example 1.6. ''​iptrtpproxy_delete''​ usage**
 +
 +<​code>​
 +    ...
 +        # load $sess_ids from dialog
 +        iptrtpproxy_delete($sess_ids);​
 +        ...
 +</​code>​
 +
 +\\ ==== 5.5. iptrtpproxy_authorize_media() ====
 +
 +Authorizes SDP media according currect codec_set. If bit AND operation between rights in codec set and ''​remove_codec_mask''​ is non zero then such a codec are to be removed. The result may be obtained from ''​@iptrtpproxy.auth_rights''​ which returns max. right which has been applied when processing all codecs of enabled streams.
 +
 +The function MUST NOT be called after ''​iptrtpproxy_alloc/​update''​! But the function may be called several times to authorize using more codec sets.
 +
 +**Example 1.7. ''​iptrtpproxy_authorize_media''​ usage**
 +
 +<​code>​
 +    ...
 +        if (@iptrtpproxy.active_media_num == "​0"​) break;
 +        iptrtpproxy_set_param("​codec_set",​ "​cs2"​);​
 +        iptrtpproxy_set_param("​remove_codec_mask",​ "​1"​);​
 +        if (!iptrtpproxy_authorize_media()) {
 +                t_reply("​415",​ "​Cannot authorize media"​);​
 +                drop;
 +        }
 +        iptrtpproxy_set_param("​codec_set",​ "​cs3"​);​
 +        if (!iptrtpproxy_authorize_media()) {
 +                t_reply("​415",​ "​Cannot authorize media"​);​
 +                drop;
 +        }
 +        if (@iptrtpproxy.active_media_num == "​0"​) {
 +                t_reply("​488",​ "Not acceptable here"​);​
 +                drop;
 +        }
 +        if (@iptrtpproxy.auth_rights == "​2"​) {
 +                append_hf_value("​Contact:​ <​sip:​1.2.3.4>"​);​
 +                t_reply("​301",​ "​Redirect to transcoder"​);​
 +                drop;
 +
 +        }
 +        ...
 +</​code>​
 +
 +\\ ==== 5.6. iptrtpproxy_set_param(param,​ value) ====
 +
 +Set particular parameter needed mainly by ''​iptrtpproxy_alloc/​update/​adjust_timeout''​. The paramter value is availble via ''​@iptrtpproxy.<​param>''​.
 +
 +  * Supported parameters: expiration_timeout,​ ttl, learning_timeout,​ always_learn,​ aggregation_a,​ aggregation_b,​ switchboard_a,​ switchboard_b,​ throttle_mark,​ throttle_rtp_max_bytes,​ throttle_rtp_max_packets,​ throttle_rtcp_max_bytes,​ throttle_rtcp_max_packets. ​
 +
 +==== 5.7. iptrtpproxy_set_param("​(aggregation/​switchboard)_by_sip_ip%%_(%%a/​b)",​ sip_ip) ====
 +
 +Find corresponding aggregation or switchboard and set ''​@iptrtpproxy.aggregation_a/​b''​ or ''​@iptrtpproxy.switchboard_a/​b''​. Switchboards/​aggregations are compared against sip-addr, it allow separate SIP and RTP traffic and RTP aggregation.
 +
 +  * sip_ip IP to be compared, typically ''​@received.ip''​ or ''​@next_hop.src_ip''​. ​
 +  * function returns true if switchboard/​aggregation was found 
 +
 +==== 5.8. iptrtpproxy_set_param("​protected_session_ids",​ sess_ids) ====
 +
 +Used for reusing sessions in ''​iptrtpproxy_alloc'',​ ''​iptrtpproxy_update''​ and ''​iptrtpproxy_delete''​.
 +
 +==== 5.9. iptrtpproxy_set_param("​o_name",​ value) ====
 +
 +Username to be rewritten at o= line by ''​iptrtpproxy_alloc/​update''​ to hide caller identity. If value is blank then username is left unchanged.
 +
 +==== 5.10. iptrtpproxy_set_param("​o_addr",​ value) ====
 +
 +Address to be rewritten at o= line by ''​iptrtpproxy_alloc/​update''​ to hide caller identity. If value is blank then address is left unchanged.
 +
 +==== 5.11. iptrtpproxy_set_param("​codec_set",​ value) ====
 +
 +Codec set for ''​iptrtpproxy_authorize_media''​. Current codec set may be obtained by ''​@iptrtpproxy.codec_set''​.
 +
 +==== 5.12. iptrtpproxy_set_param("​remove_codec_mask",​ value) ====
 +
 +Mask used in ''​iptrtpproxy_authorize_media''​. Current mask may be obtained by ''​@iptrtpproxy.remove_codec_mask''​.
 +
 +===== 6. Selects =====
 +
 +==== 6.1. @iptrtpproxy.session_ids ====
 +
 +Returns sessions allocated/​updated in ''​iptrtpproxy_alloc/​update''​.
 +
 +The format is:
 +
 +<​code>​
 +switchboard_name [ ":"​ [ session_id "/"​ created ] * ( ","​ session_id "/"​ created ) ] ]
 +session_id = * ( [0-9] )   ; empty when no session allocated
 +created = timestamp
 +</​code>​
 +
 +==== 6.2. @iptrtpproxy.sdp_ip ====
 +
 +Return first rewritten IP provided at SDP c= line.
 +
 +==== 6.3. @iptrtpproxy.o_name ====
 +
 +Return username from original o= line.
 +
 +==== 6.4. @iptrtpproxy.o_addr ====
 +
 +Return address from original o= line.
 +
 +==== 6.5. @iptrtpproxy.auth_rights ====
 +
 +Result of ''​iptrtpproxy_authorize_media''​.
 +
 +==== 6.6. @iptrtpproxy.active_media_num ====
 +
 +Returns number of active media streams in SDP. ''​iptrtpproxy_authorize_media''​ may disable some streams, i.e. returned value may change after authorization.
iptrtpproxy_nat_traversal_module_using_kernel_for_media_relay_released.txt · 最后更改: 2017/09/11 11:41 由 james_zhu