kamailio/modules/iptrtpproxy

1. Iptrtpproxy module

Tomas Mandys

   Iptel.org

   Copyright © 2007 Tomas Mandys
     __________________________________________________________________

   1.1. Overview
   1.2. Dependencies
   1.3. Parameters

        1.3.1. config (string)
        1.3.2. switchboard (string)
        1.3.3. rpc_heartbeat_timeout (int)
        1.3.4. hostname (string)
        1.3.5. declare_codec (string)
        1.3.6. codec_set (string)

   1.4. Functions

        1.4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
        1.4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
        1.4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
        1.4.4. iptrtpproxy_delete(session_ids)
        1.4.5. iptrtpproxy_authorize_media()
        1.4.6. iptrtpproxy_set_param(param, value)
        1.4.7.
                iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(
                a/b)", sip_ip)

        1.4.8. iptrtpproxy_set_param("protected_session_ids", sess_ids)
        1.4.9. iptrtpproxy_set_param("o_name", value)
        1.4.10. iptrtpproxy_set_param("o_addr", value)
        1.4.11. iptrtpproxy_set_param("codec_set", value)
        1.4.12. iptrtpproxy_set_param("remove_codec_mask", value)

   1.5. Selects

        1.5.1. @iptrtpproxy.session_ids
        1.5.2. @iptrtpproxy.sdp_ip
        1.5.3. @iptrtpproxy.o_name
        1.5.4. @iptrtpproxy.o_addr
        1.5.5. @iptrtpproxy.auth_rights
        1.5.6. @iptrtpproxy.active_media_num

1.1. Overview

   It provides similar functionality as nathelper but communicates with
   netfilter kernel xt_RTPPROXY module using libipt_RTPPROXY userspace
   library. See http://www.2p.cz/en/netfilter_rtp_proxy 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 for more details.

   The ser module is written as light-weighted, there is not implemented
   any dialog managment as in nathelper, the reason is that such an API
   should be provided by core or specialized dialog manager module.
   Because such module is not in CVS, session information may be stored in
   extra attributes of avp_db module and session id itself in record route
   as cookie, see 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.

   Limitations:
     * only IPv4 addresses are supported.
     * more media streams per session supported

1.2. Dependencies

   The following libraries or applications must be installed before
   running SER with this module loaded:
     * netfilter xt_RTPPROXY & libipt_RTPPROXY, see
       http://www.2p.cz/en/netfilter_rtp_proxy

Note

   The module Makefile must be edited and iptdir setup to the directory
   with the iptable sources (if different from ~/iptables). Alternatively
   compile the module using:
                make -C modules/iptrtpproxy iptdir=path_to_iptables_src

1.3. Parameters

1.3.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.

1.3.2. switchboard (string)

   References xt_RTPPROXY switchboard for usage by ser module.

   The format is:
  "name=" value * ( ";" name "=" value )

  name =  "aggregation" | "sip-addr-"

   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. Declare switchboard
        ...
        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");
        ...

1.3.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.

1.3.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.

1.3.5. declare_codec (string)

   There are basic implicit codecs compiled in module, more codecs may be
   added by this parameter (one codec per modparam).

1.3.6. codec_set (string)

   Declares new codec set. Codecs are declared for each media type
   independently.

   The format is:
  "name=" value * ( ";" name "=" value )

  name =  "media_type" | "rights" | "codecs" | "max_streams" | ( "rtp" | "rtcp"
) "_" ( "bytes" | "packets" )

  media_types = "audio" | "video" | "application" | "text" | "message" | "data"
| "control" | "?" | "*"

   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 2. Declare codec_set
        ...
        # 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 bu
t 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,G72
8,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_byte
s=10000;rtcp_bytes=1000");
        ...

1.4. Functions

1.4.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 3. iptrtpproxy_alloc usage
        ...
        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.agg
regation_a");
                }
                else {
                        iptrtpproxy_set_param("switchboard_b", "@iptrtpproxy.swi
tchboard_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;
        ...

1.4.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 4. iptrtpproxy_update usage
        ...
        # load $sess_ids from dialog
        if (iptrtpproxy_update("0", $sess_ids)) {
          $sess_ids = @iptrtpproxy.session_ids;
          # save sess_ids in dialog
        }
        ...

1.4.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 5. iptrtpproxy_adjust_timeout usage
        ...
        # 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)) {
        }
        ...

1.4.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 6. iptrtpproxy_delete usage
        ...
        # load $sess_ids from dialog
        iptrtpproxy_delete($sess_ids);
        ...

1.4.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 7. iptrtpproxy_authorize_media usage
        ...
        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;

        }
        ...

1.4.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.

1.4.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

1.4.8. iptrtpproxy_set_param("protected_session_ids", sess_ids)

   Used for reusing sessions in iptrtpproxy_alloc, iptrtpproxy_update and
   iptrtpproxy_delete.

1.4.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.

1.4.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.

1.4.11. iptrtpproxy_set_param("codec_set", value)

   Codec set for iptrtpproxy_authorize_media. Current codec set may be
   obtained by @iptrtpproxy.codec_set.

1.4.12. iptrtpproxy_set_param("remove_codec_mask", value)

   Mask used in iptrtpproxy_authorize_media. Current mask may be obtained
   by @iptrtpproxy.remove_codec_mask.

1.5. Selects

1.5.1. @iptrtpproxy.session_ids

   Returns sessions allocated/updated in iptrtpproxy_alloc/update.

   The format is:
        switchboard_name [ ":" [ session_id "/" created ] * ( "," session_id "/"
 created ) ] ]
        session_id = * ( [0-9] )   ; empty when no session allocated
        created = timestamp

1.5.2. @iptrtpproxy.sdp_ip

   Return first rewritten IP provided at SDP c= line.

1.5.3. @iptrtpproxy.o_name

   Return username from original o= line.

1.5.4. @iptrtpproxy.o_addr

   Return address from original o= line.

1.5.5. @iptrtpproxy.auth_rights

   Result of iptrtpproxy_authorize_media.

1.5.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.