kamailio/modules/iptrtpproxy/README

1. Iptrtpproxy module

Tomas Mandys

   Iptel.org

   Copyright © 2007 Tomas Mandys
   Revision History
   Revision $Revision$ $Date$
     __________________________________________________________________

   1.1. Overview
   1.2. Dependencies
   1.3. Parameters

        1.3.1. config (string)
        1.3.2. switchboard (string)

   1.4. Functions

        1.4.1. iptrtpproxy_alloc(gate_a_to_b, switchboard_id)
        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_find(gate_a, gate_b)
        1.4.6. @iptrtpproxy.session_ids
        1.4.7. @iptrtpproxy.sdp_ip
        1.4.8. @iptrtpproxy.switchboard
        1.4.9. @iptrtpproxy.direction

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 are copied from
   kernel to userspace and back, it reduces load and delay.

   The ser module is written as light-weighted, there is not implemented
   any dialog managment as in nathelper, the reason is that such 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.

   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_RTPROXY & libipt_RTPPROXY, see
       http://www.2p.cz/en/netfilter_rtp_proxy

1.3. Parameters

1.3.1. config (string)

   References iptrtpproxy.cfg, see iptrtpproxy_helper. Default value is
   /etc/iptrtpproxy.cfg.

1.3.2. switchboard (string)

   References xt_RTPPROXY switchboard for usage by ser module.

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

  name =  "name" | "*" | ( "ringing-timeout " ) | ( ( "learning-timeout-" | "alw
ays-learn-") ("a" | "b") )

   The meaning of parameters is described in libipt_RTPROXY and
   iptrtpproxy documentation. ringing timeout is explicit timeout in sec
   regarding ringing. Ringing requires manual callee action, i.e. it may
   takes long time. Default value is 60 sec.

   The name" is identifier that will be used by script functions and
   references switchboard. It's mandatory parameter. More switchboards may
   be declared. The special name * set values for all switchboards.

   Example 1. Declare switchboard
        ...
        modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
        modparam("iptrtpproxy", "switchboard", "name=*;learning-timeout-a=10;lea
rning-timeout-b=10;ringing-timeout=90");
        modparam("iptrtpproxy", "switchboard", "name=my;ringing-timeout=60");
        ...

1.4. Functions

1.4.1.  iptrtpproxy_alloc(gate_a_to_b, switchboard_id)

   Parses SDP content and allocates for each RTP media stream one RTP
   proxy session. SDP is updates to reflect allocated sessions.
     * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
       direction. If bit 1 is set then ringing timeout is used instead of
       learning timeout for particular gate timeout.
     * switchboard_id is reference to a switchboard with name declared as
       switchboard modparam. If empty then use switchboard found by
       iptrtpproxy_find (equal using @iptrtpproxy.switchboard).
     * function returns true is a session was created, identifier is
       available via select @iptrtpproxy.session_ids.

   Example 2. iptrtpproxy_alloc usage
        ...
        if (iptrtpproxy_alloc("1", "my")) {
          $sess_ids = @iptrtpproxy.session_ids;
          # save sess_ids in dialog
        }
        ...

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.
     * if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
       direction. If bit 1 is set then ringing timeout is used instead of
       learning timeout for particular gate timeout.

   Example 3. 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. If bit 1 is set then ringing timeout is used instead of
       learning timeout for particular gate timeout.

   Example 4. iptrtpproxy_adjust_timeout usage
        ...
        # load $sess_ids from dialog
        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.

   Example 5. iptrtpproxy_delete usage
        ...
        # load $sess_ids from dialog
        iptrtpproxy_delete($sess_ids);
        ...

1.4.5.  iptrtpproxy_find(gate_a, gate_b)

   Find corresponding switchboard and set @iptrtpproxy.switchboard and
   @iptrtpproxy.direction.
     * if gate_a/b switchboard identification
     * function returns true if switch was found

   Example 6. iptrtpproxy_find usage
        ...
        if (iptrtpproxy_find("@received.ip", "@next_hop.src_ip")) {
                if (iptrtpproxy_alloc("1", "")) {
                          $sess_ids = @iptrtpproxy.session_ids;

                }
        }
        ...

1.4.6.  @iptrtpproxy.session_ids

   Returns sessions allocated/updated in iptrtpproxy_alloc/update.

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

1.4.7.  @iptrtpproxy.sdp_ip

   Return first rewritten IP provided in SDP c= line.

1.4.8.  @iptrtpproxy.switchboard

   Switchboard found by iptrtpproxy_find.

1.4.9.  @iptrtpproxy.direction

   Direction determined by iptrtpproxy_find. 1..gate A->B, 0..gate B->A