kamailio/obsolete/nathelper

1. Nathelper Module

Maxim Sobolev

   Sippy Software, Inc.

   Copyright © 2003-2008 Sippy Software, Inc.
     __________________________________________________________________

   1.1. Overview
   1.2. Parameters

        1.2.1. natping_interval (integer)
        1.2.2. ping_nated_only (integer)
        1.2.3. received_avp (integer)

   1.3. Functions

        1.3.1. fix_nated_contact()
        1.3.2. fix_nated_sdp(mode)
        1.3.3. add_rcv_param()
        1.3.4. fix_nated_register()
        1.3.5. nat_uac_test(mode)
        1.3.6. ping_contact(contact)
        1.3.7. @nathelper.rewrite_contact[n]

1.1. Overview

   This is a module to help with NAT traversal. In particular, it helps
   symmetric UAs that don't advertise they are symmetric and are not able
   to determine their public address. fix_nated_contact rewrites Contact
   header field with request's source address:port pair. fix_nated_sdp
   adds the active direction indication to SDP (flag 0x01) and updates
   source IP address too (flag 0x02).

   Known devices that get along over NATs with nathelper are ATAs (as
   clients) and Cisco Gateways (since 12.2(T)) as servers. See
   http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature
   _guide09186a0080110bf9.html">

1.2. Parameters

1.2.1. natping_interval (integer)

   Period of time in seconds between sending short UDP packets to all
   currently registered UAs to keep their NAT bindings alive. Value of 0
   disables this functionality.

   Default value is 0.

   Example 1. Set natping_interval parameter
...
modparam("nathelper", "natping_interval", 10)
...

1.2.2. ping_nated_only (integer)

   If this variable is set then only contacts that have "behind_NAT" flag
   in user location database set set will get ping.

   Default value is 0.

   Example 2. Set ping_nated_only parameter
...
modparam("nathelper", "ping_nated_only", 1)
...

1.2.3. received_avp (integer)

   The number of the Attribute-Value-Pair (AVP) used to store the URI
   containing the received IP, port, and protocol. The URI is created by
   fix_nated_register function of nathelper module and the attribute is
   then used by the registrar to store the received parameters. Do not
   forget to change the value of corresponding parameter in registrar
   module if you change the value of this parameter.

   Default value is 42.

   Example 3. Set received_avp parameter
...
modparam("nathelper", "received_avp", 43)
...

1.3. Functions

1.3.1.  fix_nated_contact()

   Rewrites Contact HF to contain request's source address:port.

   Example 4. fix_nated_contact usage
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
...

1.3.2.  fix_nated_sdp(mode)

   Rewrites Contact HF to contain request's source address:port.

   Meaning of the parameters is as follows:
     * mode - 0x01 (add direction=active), 0x02 (rewrite media IP address
       with source address of the message).

   Example 5. fix_nated_sdp usage
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
...

1.3.3.  add_rcv_param()

   Add received parameter to Contact header fields. The parameter will
   contain URI created from the source IP, port, and protocol of the
   packet containing the SIP message. The parameter can be then processed
   by another registrar, this is useful, for example, when replicating
   register messages using t_replicate function to another registrar.

   Example 6. add_rcv_paramer usage
...
add_rcv_param();
...

1.3.4.  fix_nated_register()

   The function creates a URI consisting of the source IP, port, and
   protocol and stores the URI in an Attribute-Value-Pair. The URI will be
   appended as "received" parameter to Contact in 200 OK and registrar
   will store it in the user location database.

   Example 7. fix_nated_register usage
...
fix_nated_register();
...

1.3.5.  nat_uac_test(mode)

   Tries to guess if client's request originated behind a nat. The mode
   parameter determines what heuristics is used. If mode contains:
     * 01 - the Contact URI host contains a private IP address (from
       RFC1981).
     * 02 - the address in the topmost Via header differs from the source
       IP address of the request.
     * 04 - the address in the topmost Via contains a private IP address
       (RFC1918).
     * 08 - the SDP body of the request contains a private IP address
       (RFC1918).
     * 16 - the port in the topmost Via differs from the source port of
       the request.
     * 32 - the Contact URI port differs from the source port of the
       request (Warning: this is might be legal or even intended
       combination in non natted scenarios).

   All of them might be bitwise combined (which is equal to the sum of the
   values from the list above). If one of the test matched the function
   returns true.

1.3.6.  ping_contact(contact)

   Ping contact specified by parameter. It enables pinging independently
   on usrloc. It may be processed e.g. via timer module.

   Example 8. ping_contact usage
...
$c = @get_a_contact;
ping_contact($c);
...

1.3.7.  @nathelper.rewrite_contact[n]

   Get n-th Contact value with IP:Port rewritten to source ip:port. N is
   counted from 1. Only IP:port is rewritten, remaining part are left
   unchanged. Full nameaddr is supported.

   Example 9. @nathelper.rewrite_contact usage
...
$c = @nathelper.rewrite_contact[1];
...
$c2 = @nathelper.rewrite_contact[1].nameaddr.uri;