nathelper(k): documented keepalive_timeout parameter

modules_k/nathelper/README

@@ -24,13 +24,13 @@ Edited by
 
 Ovidiu Sas
 
-   Copyright © 2003-2008 Sippy Software, Inc.
+   Copyright © 2003-2008 Sippy Software, Inc.
 
-   Copyright © 2005 Voice Sistem SRL
+   Copyright © 2005 Voice Sistem SRL
 
-   Copyright © 2009 TuTPro Inc.
+   Copyright © 2009 TuTPro Inc.
 
-   Copyright © 2010 VoIPEmbedded Inc.
+   Copyright © 2010 VoIPEmbedded Inc.
      __________________________________________________________________
 
    Table of Contents
@@ -55,6 +55,7 @@ Ovidiu Sas
               4.7. sipping_from (string)
               4.8. sipping_method (string)
               4.9. nortpproxy_str (string)
+              4.10. keepalive_timeout (int)
 
         5. Functions
 
@@ -90,16 +91,17 @@ Ovidiu Sas
    1.7. Set sipping_from parameter
    1.8. Set sipping_method parameter
    1.9. Set nortpproxy_str parameter
-   1.10. fix_nated_contact usage
-   1.11. fix_nated_sdp usage
-   1.12. fix_nated_contact usage
-   1.13. add_rcv_paramer usage
-   1.14. fix_nated_register usage
-   1.15. add_contact_alias usage
-   1.16. handle_ruri_alias usage
-   1.17. $rr_count usage
-   1.18. $rr_top_count usage
-   1.19. nh_enable_ping usage
+   1.10. Set keepalive_timeout parameter
+   1.11. fix_nated_contact usage
+   1.12. fix_nated_sdp usage
+   1.13. fix_nated_contact usage
+   1.14. add_rcv_paramer usage
+   1.15. fix_nated_register usage
+   1.16. add_contact_alias usage
+   1.17. handle_ruri_alias usage
+   1.18. $rr_count usage
+   1.19. $rr_top_count usage
+   1.20. nh_enable_ping usage
 
 Chapter 1. Admin Guide
 
@@ -123,6 +125,7 @@ Chapter 1. Admin Guide
         4.7. sipping_from (string)
         4.8. sipping_method (string)
         4.9. nortpproxy_str (string)
+        4.10. keepalive_timeout (int)
 
    5. Functions
 
@@ -216,6 +219,7 @@ Chapter 1. Admin Guide
    4.7. sipping_from (string)
    4.8. sipping_method (string)
    4.9. nortpproxy_str (string)
+   4.10. keepalive_timeout (int)
 
 4.1. natping_interval (integer)
 
@@ -237,7 +241,7 @@ modparam("nathelper", "natping_interval", 10)
 
 4.2. ping_nated_only (integer)
 
-   If this variable is set then only contacts that have “behind_NAT� flag
+   If this variable is set then only contacts that have "behind_NAT" flag
    in user location database set will get ping.
 
    Default value is 0.
@@ -312,7 +316,7 @@ modparam("nathelper", "sipping_bflag", 7)
    feature, you have to set this parameter. The SIP request pinging will
    be used only for requests marked so.
 
-   Default value is “NULL�.
+   Default value is "NULL".
 
    Example 1.7. Set sipping_from parameter
 ...
@@ -324,7 +328,7 @@ modparam("nathelper", "sipping_from", "sip:[email protected]")
    The parameter sets the SIP method to be used in generating the SIP
    requests for NAT ping purposes.
 
-   Default value is “OPTIONS�.
+   Default value is "OPTIONS".
 
    Example 1.8. Set sipping_method parameter
 ...
@@ -342,13 +346,32 @@ Note
 
    The string must be a complete SDP line, including the EOH (\r\n).
 
-   Default value is “a=nortpproxy:yes\r\n�.
+   Default value is "a=nortpproxy:yes\r\n".
 
    Example 1.9. Set nortpproxy_str parameter
 ...
 modparam("nathelper", "nortpproxy_str", "a=sdpmangled:yes\r\n")
 ...
 
+4.10. keepalive_timeout (int)
+
+   The parameter sets the interval in secods after which a natted contact
+   is removed from location table if it does not reply to SIP keepalives
+   (usually OPTIONS ping requests).
+
+   The features is available only for UDP contacts that are stored in
+   memory (not working for db only mode for usrloc module).
+
+   Keepalives are sent stateless, not using TM module. The value of this
+   parameter has to be few times higher than natping_interval.
+
+   Default value is "0" (feature disabled).
+
+   Example 1.10. Set keepalive_timeout parameter
+...
+modparam("nathelper", "keepalive_timeout", 120)
+...
+
 5. Functions
 
    5.1. fix_nated_contact()
@@ -361,30 +384,30 @@ modparam("nathelper", "nortpproxy_str", "a=sdpmangled:yes\r\n")
    5.8. add_contact_alias()
    5.9. handle_ruri_alias()
 
-5.1.  fix_nated_contact()
+5.1. fix_nated_contact()
 
    Rewrites Contact HF to contain request's source address:port.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    BRANCH_ROUTE.
 
-   Example 1.10. fix_nated_contact usage
+   Example 1.11. fix_nated_contact usage
 ...
 if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
 ...
 
-5.2.  fix_nated_sdp(flags [, ip_address])
+5.2. fix_nated_sdp(flags [, ip_address])
 
    Alters the SDP information in orer to facilitate NAT traversal. What
-   changes to be performed may be controled via the “flags� parameter.
+   changes to be performed may be controled via the "flags" parameter.
 
    Meaning of the parameters is as follows:
      * flags - the value may be a bitwise OR of the following flags:
-          + 0x01 - adds “a=direction:active� SDP line;
+          + 0x01 - adds "a=direction:active" SDP line;
           + 0x02 - rewrite media IP address (c=) with source address of
             the message or the provided IP address (the provide IP address
             take precedence over the source address).
-          + 0x04 - adds “a=nortpproxy:yes� SDP line;
+          + 0x04 - adds "a=nortpproxy:yes" SDP line;
           + 0x08 - rewrite IP from origin description (o=) with source
             address of the message or the provided IP address (the provide
             IP address take precedence over the source address).
@@ -396,12 +419,12 @@ if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
-   Example 1.11. fix_nated_sdp usage
+   Example 1.12. fix_nated_sdp usage
 ...
 if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
 ...
 
-5.3.  set_rtp_proxy_set()
+5.3. set_rtp_proxy_set()
 
    Sets the Id of the rtpproxy set to be used for the next
    [un]force_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() command.
@@ -409,13 +432,13 @@ if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    BRANCH_ROUTE.
 
-   Example 1.12. fix_nated_contact usage
+   Example 1.13. fix_nated_contact usage
 ...
 set_rtp_proxy_set("2");
 force_rtp_proxy();
 ...
 
-5.4.  add_rcv_param([flag]),
+5.4. add_rcv_param([flag]),
 
    Add received parameter to Contact header fields or Contact URI. The
    parameter will contain URI created from the source IP, port, and
@@ -432,14 +455,14 @@ force_rtp_proxy();
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.13. add_rcv_paramer usage
+   Example 1.14. add_rcv_paramer usage
 ...
 add_rcv_param(); # add the parameter to the Contact header
 ....
 add_rcv_param("1"); # add the parameter to the Contact URI
 ...
 
-5.5.  fix_nated_register()
+5.5. 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
@@ -452,12 +475,12 @@ add_rcv_param("1"); # add the parameter to the Contact URI
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.14. fix_nated_register usage
+   Example 1.15. fix_nated_register usage
 ...
 fix_nated_register();
 ...
 
-5.6.  nat_uac_test(flags)
+5.6. nat_uac_test(flags)
 
    Tries to guess if client's request originated behind a nat. The
    parameter determines what heuristics is used.
@@ -480,14 +503,14 @@ fix_nated_register();
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
-5.7.  is_rfc1918(ip_address)
+5.7. is_rfc1918(ip_address)
 
    Determines if the address in the parameter is an rfc1918 address. The
    parameter allows pseudo-variables usage.
 
    This function can be used from ANY_ROUTE.
 
-5.8.  add_contact_alias()
+5.8. add_contact_alias()
 
    Adds ;alias=ip:port parameter to contact URI containing received
    ip:port if contact uri ip:port does not match received ip:port.
@@ -495,7 +518,7 @@ fix_nated_register();
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    BRANCH_ROUTE, and LOCAL_ROUTE.
 
-   Example 1.15. add_contact_alias usage
+   Example 1.16. add_contact_alias usage
 ...
     if (!is_present_hf("Record-Route")) {
         if (!add_contact_alias()) {
@@ -506,7 +529,7 @@ fix_nated_register();
     };
 ...
 
-5.9.  handle_ruri_alias()
+5.9. handle_ruri_alias()
 
    Checks if Request URI has alias param and if so, removes it and sets
    $du based on its value. Note that this means that routing of request is
@@ -522,7 +545,7 @@ fix_nated_register();
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, and
    LOCAL_ROUTE.
 
-   Example 1.16. handle_ruri_alias usage
+   Example 1.17. handle_ruri_alias usage
 ...
     if ($du == "") {
         handle_ruri_alias();
@@ -550,7 +573,7 @@ fix_nated_register();
 
    Number of Record Routes in received SIP request or reply.
 
-   Example 1.17. $rr_count usage
+   Example 1.18. $rr_count usage
 ...
     $avp(rr_count) = $rr_count;
 ...
@@ -562,7 +585,7 @@ fix_nated_register();
    value of $rr_top_count is 1. If there is no Record Route(s), value of
    $rr_top_count is 0.
 
-   Example 1.18. $rr_top_count usage
+   Example 1.19. $rr_top_count usage
 ...
     if ($rr_count == $avp(rr_count) + $rr_top_count) {
         route(ADD_CONTACT_ALIAS);
@@ -580,23 +603,23 @@ fix_nated_register();
 
    The function takes only one parameter - a number in decimal format.
 
-   Example 1.19. nh_enable_ping usage
+   Example 1.20. nh_enable_ping usage
 ...
 $ kamctl fifo nh_enable_ping 1
 ...
 
 Chapter 2. Frequently Asked Questions
 
-   2.1. What happend with “rtpproxy_disable� parameter?
+   2.1. What happend with "rtpproxy_disable" parameter?
    2.2. Where can I find more about Kamailio?
    2.3. Where can I post a question about this module?
    2.4. How can I report a bug?
 
    2.1.
 
-   What happend with “rtpproxy_disable� parameter?
+   What happend with "rtpproxy_disable" parameter?
 
-   It was removed as it became obsolete - now “rtpproxy_sock� can take
+   It was removed as it became obsolete - now "rtpproxy_sock" can take
    empty value to disable the rtpproxy functionality.
 
    2.2.

modules_k/nathelper/doc/nathelper_admin.xml

@@ -330,6 +330,35 @@ modparam("nathelper", "sipping_method", "INFO")
 ...
 modparam("nathelper", "nortpproxy_str", "a=sdpmangled:yes\r\n")
 ...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title><varname>keepalive_timeout</varname> (int)</title>
+		<para>
+		The parameter sets the interval in secods after which a natted
+		contact is removed from location table if it does not reply to SIP
+		keepalives (usually OPTIONS ping requests).
+		</para>
+		<para>
+		The features is available only for UDP contacts that are stored in memory
+		(not working for db only mode for usrloc module).
+		</para>
+		<para>
+		Keepalives are sent stateless, not using TM module. The value of this
+		parameter has to be few times higher than natping_interval.
+		</para>
+		<para>
+		<emphasis>
+			Default value is <quote>0</quote> (feature disabled).
+		</emphasis>
+		</para>
+		<example>
+		<title>Set <varname>keepalive_timeout</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("nathelper", "keepalive_timeout", 120)
+...
 </programlisting>
 		</example>
 	</section>