kamailio/modules_s/nathelper

nathelper Module

Maxim Sobolev

   PortaOne

Edited by

Maxim Sobolev

   Copyright © 2003 Porta Software Ltd.
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. SER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. natping_interval (integer)
              1.3.2. ping_nated_only (integer)
              1.3.3. received_avp (integer)

        1.4. Exported Functions

              1.4.1. fix_nated_contact()

        1.5. Exported Functions

              1.5.1. fix_nated_sdp(mode)
              1.5.2. force_rtp_proxy()
              1.5.3. add_rcv_param()
              1.5.4. fix_nated_register()
              1.5.5. force_rtp_proxy(ip_address)
              1.5.6. nat_uac_test(mode)

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set natping_interval parameter
   1-2. Set ping_nated_only parameter
   1-3. Set received_avp parameter
   1-4. fix_nated_contact usage
   1-5. fix_nated_sdp usage
   1-6. force_rtp_proxy usage
   1-7. add_rcv_paramer usage
   1-8. fix_nated_register usage
   1-9. force_rtp_proxy usage
     _________________________________________________________

Chapter 1. User's Guide

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/product
   s_feature_guide09186a0080110bf9.html">
     _________________________________________________________

1.2. Dependencies

1.2.1. SER Modules

   The following modules must be loaded before this module:

     * No dependencies on other SER modules.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running SER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.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-1. Set natping_interval parameter
...
modparam("nathelper", "natping_interval", 10)
...
     _________________________________________________________

1.3.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 1-2. Set ping_nated_only parameter
...
modparam("nathelper", "ping_nated_only", 1)
...
     _________________________________________________________

1.3.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 1-3. Set received_avp parameter
...
modparam("nathelper", "received_avp", 43)
...
     _________________________________________________________

1.4. Exported Functions

1.4.1. fix_nated_contact()

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

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

1.5. Exported Functions

1.5.1. 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 1-5. fix_nated_sdp usage
...
if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
...
     _________________________________________________________

1.5.2. force_rtp_proxy()

   Rewrites SDP body to ensure that media is passed through an
   RTP proxy.

   Example 1-6. force_rtp_proxy usage
...
if (search("User-Agent: Cisco ATA.*") {force_rtp_proxy();};
...
     _________________________________________________________

1.5.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 1-7. add_rcv_paramer usage
...
add_rcv_param();
...
     _________________________________________________________

1.5.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 1-8. fix_nated_register usage
...
fix_nated_register();
...
     _________________________________________________________

1.5.5. force_rtp_proxy(ip_address)

   Rewrites SDP body with given IP address to ensure that media
   is passed through an RTP proxy.

   Meaning of the parameters is as follows:

     * ip_address - new SDP IP address.

   Example 1-9. force_rtp_proxy usage
...
if (search("User-Agent: Cisco ATA.*") {force_rtp_proxy("1.2.3.4");};
...
     _________________________________________________________

1.5.6. nat_uac_test(mode)

   Tries to guess if client's request originated behind a nat.
   The parameter determines what heuristics is used. If flag 1 is
   set, the "received" test is used -- address in Via is compared
   against source IP address of signaling. If flag 2 is set,
   Contact header field is searched for occurrence of RFC1918
   addresses. Both flags can be bitwise combined, the test
   returns true if any of the tests identified a NAT.
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any sort of API to use in other
   SER modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about SER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about SER?

   Take a look at http://iptel.org/ser.

   3.2. 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:

     * http://mail.iptel.org/mailman/listinfo/serusers
     * http://mail.iptel.org/mailman/listinfo/serdev

   E-mails regarding any stable version should be sent to
   <serusers@iptel.org> and e-mail regarding development versions
   or CVS snapshots should be send to <serdev@iptel.org>.


   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://iptel.org/ser/bugs