1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
11 <!-- Module User's Guide -->
15 <title>&adminguide;</title>
18 <title>Overview</title>
20 This is a module to help with &nat; traversal and reuse
21 of <acronym>TCP</acronym> connections. In particular,
22 it helps symmetric &ua;s that don't advertise they are symmetric
23 and are not able to determine their public address.
26 The function <function>fix_nated_contact()</function> rewrites the <quote>Contact</quote>
27 header field with request's source address:port pair. The function
28 <function>fix_nated_sdp()</function> adds the active direction indication
29 to &sdp; (flag 0x01) and updates the source &ip; address too (flag 0x02). The function
30 <function>fix_nated_register()</function> exports exports the request's source
31 address:port into an AVP to be used during <function>save()</function> and should
32 be used for <quote>REGISTER</quote> requests.
35 Note: <function>fix_nated_contact</function> changes the <quote>Contact</quote>
36 header, thus it breaks the RFC. Although usually this is not an issue, it may
37 cause problems with strict SIP clients. An alternative is to use
38 <function>add_contact_alias()</function> that together with
39 the <function>handle_ruri_alias()</function> is standards conforming and also
40 supports reuse of TCP/TLS connections.
45 <title>NAT pinging types</title>
47 Currently, the nathelper module supports two types of NAT pings:
52 <emphasis>UDP packet</emphasis> - 4 bytes (zero filled) UDP
53 packets are sent to the contact address.
57 <para><emphasis>Advantages:</emphasis> low bandwidth traffic,
58 easy to generate by &kamailio;;
62 <para><emphasis>Disadvantages:</emphasis> unidirectional
63 traffic through NAT (inbound - from outside to inside); As
64 many NATs do update the bind timeout only on outbound traffic,
65 the bind may expire and closed.
72 <emphasis>SIP request</emphasis> - a stateless SIP request is
73 sent to the UDP contact address.
77 <para><emphasis>Advantages:</emphasis> bidirectional traffic
78 through NAT, since each PING request from &kamailio; (inbound
79 traffic) will force the SIP client to generate a SIP reply
80 (outbound traffic) - the NAT bind will be surely kept open.
84 <para><emphasis>Disadvantages:</emphasis> higher bandwidth
85 traffic, more expensive (as time) to generate by &kamailio;;
94 <title>Dependencies</title>
96 <title>&kamailio; Modules</title>
98 The following modules must be loaded before this module:
102 <emphasis>usrloc</emphasis> module - only if the NATed
103 contacts are to be pinged.
110 <title>External Libraries or Applications</title>
112 The following libraries or applications must be installed before
113 running &kamailio; with this module loaded:
117 <emphasis>None</emphasis>.
126 <title>Parameters</title>
127 <section id="nathelper.p.force_socket">
128 <title><varname>force_socket</varname> (string)</title>
130 Socket to be used when sending NAT pings for UDP communication.
131 If no one specified, the OS will choose a socket.
135 Default value is <quote>NULL</quote>.
139 <title>Set <varname>force_socket</varname> parameter</title>
140 <programlisting format="linespecific">
142 modparam("nathelper", "force_socket", "127.0.0.1:5060")
147 <section id="nathelper.p.natping_interval">
148 <title><varname>natping_interval</varname> (integer)</title>
150 Period of time in seconds between sending the NAT pings to all
151 currently registered &ua;s to keep their &nat; bindings alive.
152 Value of 0 disables this functionality.
155 Enabling the NAT pinging functionality will force the module to
156 bind itself to USRLOC module.
164 <title>Set <varname>natping_interval</varname> parameter</title>
165 <programlisting format="linespecific">
167 modparam("nathelper", "natping_interval", 10)
172 <section id="nathelper.p.ping_nated_only">
173 <title><varname>ping_nated_only</varname> (integer)</title>
175 If this parameter is set to 1 then only contacts that have
176 <quote>behind_NAT</quote> flag in user location database set will
180 If it is 0 and sipping_flag is not set, then the 4-bytes UDP ping is
181 sent to all contacts. If it is 0 and sipping_flag parameter is set, then
182 SIP-request-based pinging is sent to all contacts.
190 <title>Set <varname>ping_nated_only</varname> parameter</title>
191 <programlisting format="linespecific">
193 modparam("nathelper", "ping_nated_only", 1)
198 <section id="nathelper.p.natping_processes">
199 <title><varname>natping_processes</varname> (integer)</title>
201 How many timer processes should be created by the module for the
202 exclusive task of sending the NAT pings.
210 <title>Set <varname>natping_processes</varname> parameter</title>
211 <programlisting format="linespecific">
213 modparam("nathelper", "natping_processes", 3)
218 <section id="nathelper.p.natping_socket">
219 <title><varname>natping_socket</varname> (string)</title>
221 Spoof the natping's source-ip to this address. Works only for IPv4.
225 Default value is NULL.
229 <title>Set <varname>natping_socket</varname> parameter</title>
230 <programlisting format="linespecific">
232 modparam("nathelper", "natping_socket", "192.168.1.1:5006")
237 <section id="nathelper.p.received_avp">
238 <title><varname>received_avp</varname> (str)</title>
240 The name of the Attribute-Value-Pair (AVP) used to store the URI
241 containing the received IP, port, and protocol. The URI is created
242 by fix_nated_register function of nathelper module and the attribute
243 is then used by the registrar to store the received parameters. Do
244 not forget to change the value of corresponding parameter in
245 registrar module if you change the value of this parameter.
249 You must set this parameter if you use <function>fix_nated_register</function>. In such
250 case you must set the parameter with same name in the <quote>registrar</quote>
251 module to same value.
256 Default value is "NULL" (disabled).
260 <title>Set <varname>received_avp</varname> parameter</title>
261 <programlisting format="linespecific">
263 modparam("nathelper", "received_avp", "$avp(i:42)")
268 <section id="nathelper.p.sipping_bflag">
269 <title><varname>sipping_bflag</varname> (integer)</title>
271 Which branch flag should be used by the module to identify NATed
272 contacts for which it should perform NAT ping via a SIP request
273 instead of dummy UDP packet.
277 Default value is -1 (disabled).
281 <title>Set <varname>sipping_bflag</varname> parameter</title>
282 <programlisting format="linespecific">
284 modparam("nathelper", "sipping_bflag", 7)
289 <section id="nathelper.p.sipping_from">
290 <title><varname>sipping_from</varname> (string)</title>
292 The parameter sets the SIP URI to be used in generating the SIP
293 requests for NAT ping purposes. To enable the SIP request pinging
294 feature, you have to set this parameter. The SIP request pinging
295 will be used only for requests marked so.
299 Default value is <quote>NULL</quote>.
303 <title>Set <varname>sipping_from</varname> parameter</title>
304 <programlisting format="linespecific">
306 modparam("nathelper", "sipping_from", "sip:pinger@siphub.net")
311 <section id="nathelper.p.sipping_method">
312 <title><varname>sipping_method</varname> (string)</title>
314 The parameter sets the SIP method to be used in generating the SIP
315 requests for NAT ping purposes.
319 Default value is <quote>OPTIONS</quote>.
323 <title>Set <varname>sipping_method</varname> parameter</title>
324 <programlisting format="linespecific">
326 modparam("nathelper", "sipping_method", "INFO")
331 <section id="nathelper.p.natping_disable_bflag">
332 <title><varname>natping_disable_bflag</varname> (integer)</title>
334 What branch flag should be used by the module to disable NAT pings
335 on a per-registration basis. If the given flag is set for a
336 particular registration, then no NAT pings will be sent at all,
337 regardless of any other conditions.
341 Default value is -1 (disabled).
345 <title>Set <varname>natping_disable_bflag</varname> parameter</title>
346 <programlisting format="linespecific">
348 modparam("nathelper", "natping_disable_bflag", 8)
353 <section id="nathelper.p.nortpproxy_str">
354 <title><varname>nortpproxy_str</varname> (string)</title>
356 The parameter sets the SDP attribute used by nathelper to mark
357 the packet SDP that information have already been mangled.
360 If empty string, no marker will be added or checked.
363 The string must be a complete SDP line, including the EOH (\r\n).
367 Default value is <quote>a=nortpproxy:yes\r\n</quote>.
371 <title>Set <varname>nortpproxy_str</varname> parameter</title>
372 <programlisting format="linespecific">
374 modparam("nathelper", "nortpproxy_str", "a=sdpmangled:yes\r\n")
379 <section id="nathelper.p.keepalive_timeout">
380 <title><varname>keepalive_timeout</varname> (int)</title>
382 The parameter sets the interval in seconds after which a natted
383 contact is removed from location table if it does not reply to SIP
384 keepalives (usually OPTIONS ping requests).
387 The features is available only for UDP contacts that are stored in memory
388 (not working for db only mode for usrloc module).
391 Keepalives are sent stateless, not using TM module. The value of this
392 parameter has to be few times higher than natping_interval.
396 Default value is <quote>0</quote> (feature disabled).
400 <title>Set <varname>keepalive_timeout</varname> parameter</title>
401 <programlisting format="linespecific">
403 modparam("nathelper", "keepalive_timeout", 120)
408 <section id="nathelper.p.udpping_from_path">
409 <title><varname>udpping_from_path</varname> (int)</title>
411 Enable sending UDP pings (keepalives) using raw socket from Path
416 Default value is <quote>0</quote> (feature disabled).
420 <title>Set <varname>udpping_from_path</varname> parameter</title>
421 <programlisting format="linespecific">
423 modparam("nathelper", "udpping_from_path", 1)
428 <section id="nathelper.p.append_sdp_oldmediaip">
429 <title><varname>append_sdp_oldmediaip</varname> (int)</title>
431 The parameter controls if oldmediaip field should be appended to the SDP.
435 Default value is <quote>1</quote> (feature enabled).
439 <title>Set <varname>append_sdp_oldmediaip</varname> parameter</title>
440 <programlisting format="linespecific">
442 modparam("nathelper", "append_sdp_oldmediaip", 1)
448 <section id="nathelper.p.filter_server_id">
449 <title><varname>filter_server_id</varname> (int)</title>
451 Filter contacts by <quote>server_id</quote> core parameter.
452 Use this parameter to limit pinging. When set to <quote>1</quote>,
453 only proxy instances which send packets are those where core server_id
454 matches server_id saved in usrloc.
456 Default value is <quote>0</quote> (disabled).
460 <title>Set <varname>filter_server_id</varname> parameter</title>
461 <programlisting format="linespecific">
463 modparam("nathelper", "filter_server_id", 1)
473 <title>Functions</title>
474 <section id="nathelper.f.fix_nated_contact">
476 <function moreinfo="none">fix_nated_contact()</function>
479 Rewrites the <quote>Contact</quote> header to contain the request's source
483 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.
486 <title><function>fix_nated_contact</function> usage</title>
487 <programlisting format="linespecific">
489 if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
494 <section id="nathelper.f.fix_nated_sdp">
496 <function moreinfo="none">fix_nated_sdp(flags [, ip_address])</function>
499 Alters the SDP information in order to facilitate NAT traversal. What
500 changes to be performed may be controlled via the
501 <quote>flags</quote> parameter. Return value is -1 if error occurred,
502 1 if ip's were replaced, 2 if no ip's were replaced.
504 <para>Meaning of the parameters is as follows:</para>
507 <emphasis>flags</emphasis> - the value may be a bitwise OR of
512 <para><emphasis>0x01</emphasis> - adds
513 <quote>a=direction:active</quote> SDP line;
517 <para><emphasis>0x02</emphasis> - rewrite media
518 &ip; address (c=) with source address of the message
519 or the provided IP address (the provide IP address take
520 precedence over the source address).</para>
523 <para><emphasis>0x04</emphasis> - adds
524 <quote>a=nortpproxy:yes</quote> SDP line;</para>
527 <para><emphasis>0x08</emphasis> - rewrite IP from
528 origin description (o=) with source address of the message
529 or the provided IP address (the provide IP address take
530 precedence over the source address).</para>
535 <emphasis>ip_address</emphasis> - IP to be used for rewriting SDP.
536 If not specified, the received signalling IP will be used. The
537 parameter allows pseudo-variables usage. NOTE: For the IP to be
538 used, you need to use 0x02 or 0x08 flags, otherwise it will have
544 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
545 FAILURE_ROUTE, BRANCH_ROUTE.
548 <title><function>fix_nated_sdp</function> usage</title>
549 <programlisting format="linespecific">
551 if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
556 <section id="nathelper.f.add_rcv_param">
558 <function moreinfo="none">add_rcv_param([flag])</function>,
561 Add a received parameter to the <quote>Contact</quote> header fields
562 (available for all transports) or to the Contact URI (available only
566 The parameter will contain the URI created from the
567 source IP, port, and protocol (if different than UDP) of the packet
568 containing the SIP message. The parameter can be then processed by
569 another registrar. This is useful, for example, when replicating register
570 messages using <function>t_replicate</function> function to another registrar.
572 <para>Meaning of the parameters is as follows:</para>
575 <emphasis>flag</emphasis> - flags to indicate if the parameter
576 should be added to Contact URI or Contact header. If the flag is
577 non-zero, the parameter will be added to the Contact URI. If not
578 used or equal to zero, the parameter will go to the Contact
583 This function can be used from REQUEST_ROUTE.
586 <title><function>add_rcv_paramer</function> usage</title>
587 <programlisting format="linespecific">
589 add_rcv_param(); # add the parameter to the Contact header
591 add_rcv_param("1"); # add the parameter to the Contact URI
596 <section id="nathelper.f.fix_nated_register">
598 <function moreinfo="none">fix_nated_register()</function>
601 The function creates a URI consisting of the source IP, port, and
602 protocol and stores the URI in an Attribute-Value-Pair. The URI will
603 be appended as "received" parameter to Contact in 200 OK and
604 registrar will store it in the received column in the location table.
607 Note: You have to set the <quote>received_avp</quote> parameter of the
608 nathelper module and the registrar module (both module parameters must
609 have the same value) to use this function.
612 This function can be used from REQUEST_ROUTE.
615 <title><function>fix_nated_register</function> usage</title>
616 <programlisting format="linespecific">
618 fix_nated_register();
623 <section id="nathelper.f.nat_uac_test">
625 <function>nat_uac_test(flags)</function>
628 Tries to guess if client's request originated behind a nat.
629 The parameter determines what heuristics is used.
631 <para>Meaning of the flags is as follows:</para>
634 <emphasis>1</emphasis> - The <quote>Contact</quote> header field is searched
635 for occurrence of RFC1918 or RFC6598 addresses.
638 <emphasis>2</emphasis> - the "received" test is used: address
639 in the <quote>Via</quote> header is compared against source
640 IP address of signaling. If the <quote>Via</quote> header contains
641 no port, it uses the default SIP port 5060
644 <emphasis>4</emphasis> - The Top Most <quote>Via</quote> is searched
645 for occurrence of RFC1918 or RFC6598 addresses
648 <emphasis>8</emphasis> - The SDP is searched for occurrence of
649 RFC1918 or RFC6598 addresses
652 <emphasis>16</emphasis> - Test if the source port is different from the port
653 in the <quote>Via</quote> header. If the <quote>Via</quote> header contains
654 no port, it uses the default SIP port 5060
657 <emphasis>32</emphasis> - Test if the source IP address of
658 signaling is a RFC1918 or RFC6598 address
661 <emphasis>64</emphasis> - Test if the source connection of
662 signaling is a WebSocket
665 <emphasis>128</emphasis> - Test if the <quote>Contact</quote> header
666 URI port differs from the source port of the request (Warning: this is
667 might be legal or even intended combination in non NATted scenarios)
670 <emphasis>256</emphasis> - Test if the SDP connection address is different
671 from source IP address. It will work also with multiple connection address
676 All flags can be bitwise combined, the test returns true if any of
677 the tests identified a NAT.
680 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
683 <title><function>nat_uac_test</function> usage</title>
684 <programlisting format="linespecific">
686 if(nat_uac_test("19")) {
687 rtpproxy_manage("co");
694 <section id="nathelper.f.is_rfc1918">
696 <function>is_rfc1918(ip_address)</function>
699 Determines if the address in the parameter is an rfc1918 or rfc6598 address.
700 The parameter allows pseudo-variables usage.
703 This function can be used from ANY_ROUTE.
706 <title><function>is_rfc1918</function> usage</title>
707 <programlisting format="linespecific">
709 if(is_rfc1918("$rd")) {
710 # domain in r-uri is private address
717 <section id="nathelper.f.add_contact_alias">
719 <function moreinfo="none">add_contact_alias([ip_addr, port, proto])</function>
722 Adds an <quote>;alias=ip~port~transport</quote> parameter to
723 the contact URI containing either received ip, port, and
724 transport protocol or those given as parameters. If called
725 without parameters, <quote>;alias</quote> parameter is
726 only added if received ip, port, or transport protocol differs
727 from that in contact URI.
730 This function can be used from
731 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and LOCAL_ROUTE.
734 <title><function>add_contact_alias</function> usage</title>
735 <programlisting format="linespecific">
737 if (!is_present_hf("Record-Route")) {
738 if (!add_contact_alias("$var(src_ip)", "$Rp", "tcp")) {
739 xlog("L_ERR", "Error in aliasing contact $ct\n");
740 send_reply("400", "Bad request");
749 <section id="nathelper.f.handle_ruri_alias">
751 <function moreinfo="none">handle_ruri_alias()</function>
754 Checks if the Request URI has an <quote>alias</quote>
755 parameter and if so, removes it and sets the <quote>$du</quote> based
756 on its value. Note that this means that routing of request is based on
757 <quote>;alias</quote> parameter value of the Request URI rather than
758 the Request URI itself. If you call <function>handle_ruri_alias()</function>
759 on a request, make sure that you screen the alias parameter value of
760 Request URI the same way as you would screen the
764 Returns <emphasis>1</emphasis> if <quote>;alias</quote> parameter was
765 found and <quote>$du</quote> was set and the <quote>$ru</quote> rewritten,
766 <emphasis>2</emphasis> if the alias parameter was not found and
767 nothing was done, or <emphasis>-1</emphasis> in case of error.
770 This function can be used from
771 REQUEST_ROUTE, BRANCH_ROUTE, and LOCAL_ROUTE.
774 <title><function>handle_ruri_alias</function> usage</title>
775 <programlisting format="linespecific">
781 xlog("L_ERR", "Failed to handle alias of R-URI $ru\n");
782 send_reply("400", "Bad request");
785 xlog("L_INFO", "Routing in-dialog $rm from $fu to $du\n");
788 xlog("L_INFO", "Routing in-dialog $rm from $fu to $ru\n");
797 <section id="nathelper.set_contact_alias">
799 <function moreinfo="none">set_contact_alias()</function>
802 Adds an <quote>;alias=ip~port~transport</quote> parameter to the
803 contact URI containing the received ip, port, and transport protocol.
804 The new contact URI is immediately visible to other modules in the
805 way the <function>fix_nated_contact()</function> does it.
808 This function can be used from
809 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and FAILURE_ROUTE.
812 <title><function>set_contact_alias</function> usage</title>
813 <programlisting format="linespecific">
815 if (!is_present_hf("Record-Route")) {
816 if (!set_contact_alias()) {
817 xlog("L_ERR", "Error in aliasing contact $ct\n");
818 send_reply("400", "Bad request");
826 <section id="nathelper.set_alias_to_pv">
828 <function moreinfo="none">set_alias_to_pv(target_avp)</function>
831 Reads <quote>;alias=ip~port~transport</quote> from Contact header then
832 writes to target pseudo-variable as a sip uri.
835 This function can be used from
836 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and FAILURE_ROUTE.
839 <title><function>set_alias_to_pv</function> usage</title>
840 <programlisting format="linespecific">
842 set_alias_to_pv("$avp(aliasuri)");
851 <title>Exported Pseudo Variables</title>
853 <title><function moreinfo="none">$rr_count</function></title>
855 Number of Record Routes in received SIP request
859 <title>$rr_count usage</title>
860 <programlisting format="linespecific">
862 $avp(rr_count) = $rr_count;
869 <title><function moreinfo="none">$rr_top_count</function></title>
871 If topmost Record Route in received SIP request
872 or reply is a double Record Route, value of
873 $rr_top_count is 2. If it a single Record
874 Route, value of $rr_top_count
875 is 1. If there is no Record Route(s), value of
879 <title>$rr_top_count usage</title>
880 <programlisting format="linespecific">
882 if ($rr_count == $avp(rr_count) + $rr_top_count) {
883 route(ADD_CONTACT_ALIAS);
893 <title>RPC Commands</title>
894 <section id="nathelper.r.enable_ping">
895 <title><function moreinfo="none">nathelper.enable_ping</function></title>
897 Enables natping if parameter value different than 0.
898 Disables natping if parameter value is 0.
901 The function takes only one parameter - a number in decimal format.
904 <title><function moreinfo="none">nathelper.enable_ping</function> usage</title>
905 <programlisting format="linespecific">
907 $ &kamcmd; nathelper.enable_ping 1
916 <title>Selects</title>
918 <section id="nathelper.s.rewrite_contact">
919 <title>@nathelper.rewrite_contact[n]</title>
921 Get n-th Contact value with IP:Port rewritten to source ip:port. N is counted from 1.
922 Only IP:port is rewritten, remaining part are left unchanged. Full nameaddr is supported.
925 <title>@nathelper.rewrite_contact usage</title>
928 $c = @nathelper.rewrite_contact[1];
930 $c2 = @nathelper.rewrite_contact[1].nameaddr.uri;