nathelper: docs for nat_addr_mode parameter
[sip-router] / src / modules / nathelper / doc / nathelper_admin.xml
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" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14
15         <title>&adminguide;</title>
16
17         <section>
18         <title>Overview</title>
19         <para>
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.
24         </para>
25         <para>
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.
33         </para>
34         <para>
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.
41         </para>
42         </section>
43
44         <section>
45         <title>NAT pinging types</title>
46         <para>
47                 Currently, the nathelper module supports two types of NAT pings:
48         </para>
49         <itemizedlist>
50                 <listitem>
51                         <para>
52                         <emphasis>UDP packet</emphasis> - 4 bytes (zero filled) UDP 
53                         packets are sent to the contact address.
54                         </para>
55                         <itemizedlist>
56                                 <listitem>
57                                 <para><emphasis>Advantages:</emphasis> low bandwidth traffic,
58                                 easy to generate by &kamailio;;
59                                 </para>
60                                 </listitem>
61                                 <listitem>
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.
66                                 </para>
67                                 </listitem>
68                         </itemizedlist>
69                 </listitem>
70                 <listitem>
71                         <para>
72                         <emphasis>SIP request</emphasis> - a stateless SIP request is 
73                         sent to the UDP contact address.
74                         </para>
75                         <itemizedlist>
76                                 <listitem>
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.
81                                 </para>
82                                 </listitem>
83                                 <listitem>
84                                 <para><emphasis>Disadvantages:</emphasis> higher bandwidth 
85                                 traffic, more expensive (as time) to generate by &kamailio;;
86                                 </para>
87                                 </listitem>
88                         </itemizedlist>
89                 </listitem>
90         </itemizedlist>
91         </section>
92
93         <section>
94         <title>Dependencies</title>
95         <section>
96                 <title>&kamailio; Modules</title>
97                 <para>
98                 The following modules must be loaded before this module:
99                         <itemizedlist>
100                         <listitem>
101                         <para>
102                                 <emphasis>usrloc</emphasis> module - only if the NATed 
103                                 contacts are to be pinged.
104                         </para>
105                         </listitem>
106                         </itemizedlist>
107                 </para>
108         </section>
109         <section>
110                 <title>External Libraries or Applications</title>
111                 <para>
112                 The following libraries or applications must be installed before 
113                 running &kamailio; with this module loaded:
114                         <itemizedlist>
115                         <listitem>
116                         <para>
117                                 <emphasis>None</emphasis>.
118                         </para>
119                         </listitem>
120                         </itemizedlist>
121                 </para>
122         </section>
123         </section>
124
125         <section>
126         <title>Parameters</title>
127         <section id="nathelper.p.force_socket">
128                 <title><varname>force_socket</varname> (string)</title>
129                 <para>
130                 Socket to be used when sending NAT pings for UDP communication.
131                 If no one specified, the OS will choose a socket.
132                 </para>
133                 <para>
134                 <emphasis>
135                         Default value is <quote>NULL</quote>.
136                 </emphasis>
137                 </para>
138                 <example>
139                 <title>Set <varname>force_socket</varname> parameter</title>
140                 <programlisting format="linespecific">
141 ...
142 modparam("nathelper", "force_socket", "127.0.0.1:5060")
143 ...
144 </programlisting>
145                 </example>
146         </section>
147         <section id="nathelper.p.natping_interval">
148                 <title><varname>natping_interval</varname> (integer)</title>
149                 <para>
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.
153                 </para>
154                 <note><para>
155                 Enabling the NAT pinging functionality will force the module to
156                 bind itself to USRLOC module.
157                 </para></note>
158                 <para>
159                 <emphasis>
160                         Default value is 0.
161                 </emphasis>
162                 </para>
163                 <example>
164                 <title>Set <varname>natping_interval</varname> parameter</title>
165                 <programlisting format="linespecific">
166 ...
167 modparam("nathelper", "natping_interval", 10)
168 ...
169 </programlisting>
170                 </example>
171         </section>
172         <section id="nathelper.p.ping_nated_only">
173                 <title><varname>ping_nated_only</varname> (integer)</title>
174                 <para>
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
177                 get ping.
178                 </para>
179                 <para>
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.
183                 </para>
184                 <para>
185                 <emphasis>
186                         Default value is 0.
187                 </emphasis>
188                 </para>
189                 <example>
190                 <title>Set <varname>ping_nated_only</varname> parameter</title>
191                 <programlisting format="linespecific">
192 ...
193 modparam("nathelper", "ping_nated_only", 1)
194 ...
195 </programlisting>
196                 </example>
197         </section>
198         <section id="nathelper.p.natping_processes">
199                 <title><varname>natping_processes</varname> (integer)</title>
200                 <para>
201                 How many timer processes should be created by the module for the
202                 exclusive task of sending the NAT pings.
203                 </para>
204                 <para>
205                 <emphasis>
206                         Default value is 1.
207                 </emphasis>
208                 </para>
209                 <example>
210                 <title>Set <varname>natping_processes</varname> parameter</title>
211                 <programlisting format="linespecific">
212 ...
213 modparam("nathelper", "natping_processes", 3)
214 ...
215 </programlisting>
216                 </example>
217         </section>
218         <section id="nathelper.p.natping_socket">
219                 <title><varname>natping_socket</varname> (string)</title>
220                 <para>
221                 Spoof the natping's source-ip to this address. Works only for IPv4.
222                 </para>
223                 <para>
224                 <emphasis>
225                         Default value is NULL.
226                 </emphasis>
227                 </para>
228                 <example>
229                 <title>Set <varname>natping_socket</varname> parameter</title>
230                 <programlisting format="linespecific">
231 ...
232 modparam("nathelper", "natping_socket", "192.168.1.1:5006")
233 ...
234 </programlisting>
235                 </example>
236         </section>
237         <section id="nathelper.p.received_avp">
238                 <title><varname>received_avp</varname> (str)</title>
239                 <para>
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.
246                 </para>
247                 <note>
248                 <para>
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.
252                 </para>
253                 </note>
254                 <para>
255                 <emphasis>
256                         Default value is "NULL" (disabled).
257                 </emphasis>
258                 </para>
259                 <example>
260                 <title>Set <varname>received_avp</varname> parameter</title>
261                 <programlisting format="linespecific">
262 ...
263 modparam("nathelper", "received_avp", "$avp(i:42)")
264 ...
265 </programlisting>
266                 </example>
267         </section>
268         <section id="nathelper.p.sipping_bflag">
269                 <title><varname>sipping_bflag</varname> (integer)</title>
270                 <para>
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.
274                 </para>
275                 <para>
276                 <emphasis>
277                         Default value is -1 (disabled).
278                 </emphasis>
279                 </para>
280                 <example>
281                 <title>Set <varname>sipping_bflag</varname> parameter</title>
282                 <programlisting format="linespecific">
283 ...
284 modparam("nathelper", "sipping_bflag", 7)
285 ...
286 </programlisting>
287                 </example>
288         </section>
289         <section id="nathelper.p.sipping_from">
290                 <title><varname>sipping_from</varname> (string)</title>
291                 <para>
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.
296                 </para>
297                 <para>
298                 <emphasis>
299                         Default value is <quote>NULL</quote>.
300                 </emphasis>
301                 </para>
302                 <example>
303                 <title>Set <varname>sipping_from</varname> parameter</title>
304                 <programlisting format="linespecific">
305 ...
306 modparam("nathelper", "sipping_from", "sip:pinger@siphub.net")
307 ...
308 </programlisting>
309                 </example>
310         </section>
311         <section id="nathelper.p.sipping_method">
312                 <title><varname>sipping_method</varname> (string)</title>
313                 <para>
314                 The parameter sets the SIP method to be used in generating the SIP
315                 requests for NAT ping purposes.
316                 </para>
317                 <para>
318                 <emphasis>
319                         Default value is <quote>OPTIONS</quote>.
320                 </emphasis>
321                 </para>
322                 <example>
323                 <title>Set <varname>sipping_method</varname> parameter</title>
324                 <programlisting format="linespecific">
325 ...
326 modparam("nathelper", "sipping_method", "INFO")
327 ...
328 </programlisting>
329                 </example>
330         </section>
331         <section id="nathelper.p.natping_disable_bflag">
332                 <title><varname>natping_disable_bflag</varname> (integer)</title>
333                 <para>
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.
338                 </para>
339                 <para>
340                 <emphasis>
341                         Default value is -1 (disabled).
342                 </emphasis>
343                 </para>
344                 <example>
345                 <title>Set <varname>natping_disable_bflag</varname> parameter</title>
346                 <programlisting format="linespecific">
347 ...
348 modparam("nathelper", "natping_disable_bflag", 8)
349 ...
350 </programlisting>
351                 </example>
352         </section>
353         <section id="nathelper.p.nortpproxy_str">
354                 <title><varname>nortpproxy_str</varname> (string)</title>
355                 <para>
356                 The parameter sets the SDP attribute used by nathelper to mark
357                 the packet SDP that information have already been mangled.
358                 </para>
359                 <para>
360                 If empty string, no marker will be added or checked.
361                 </para>
362                 <note><para>
363                 The string must be a complete SDP line, including the EOH (\r\n).
364                 </para></note>
365                 <para>
366                 <emphasis>
367                         Default value is <quote>a=nortpproxy:yes\r\n</quote>.
368                 </emphasis>
369                 </para>
370                 <example>
371                 <title>Set <varname>nortpproxy_str</varname> parameter</title>
372                 <programlisting format="linespecific">
373 ...
374 modparam("nathelper", "nortpproxy_str", "a=sdpmangled:yes\r\n")
375 ...
376 </programlisting>
377                 </example>
378         </section>
379         <section id="nathelper.p.keepalive_timeout">
380                 <title><varname>keepalive_timeout</varname> (int)</title>
381                 <para>
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).
385                 </para>
386                 <para>
387                 The features is available only for UDP contacts that are stored in memory
388                 (not working for db only mode for usrloc module).
389                 </para>
390                 <para>
391                 Keepalives are sent stateless, not using TM module. The value of this
392                 parameter has to be few times higher than natping_interval.
393                 </para>
394                 <para>
395                 <emphasis>
396                         Default value is <quote>0</quote> (feature disabled).
397                 </emphasis>
398                 </para>
399                 <example>
400                 <title>Set <varname>keepalive_timeout</varname> parameter</title>
401                 <programlisting format="linespecific">
402 ...
403 modparam("nathelper", "keepalive_timeout", 120)
404 ...
405 </programlisting>
406                 </example>
407         </section>
408         <section id="nathelper.p.udpping_from_path">
409                 <title><varname>udpping_from_path</varname> (int)</title>
410                 <para>
411                 Enable sending UDP pings (keepalives) using raw socket from Path
412                 address.
413                 </para>
414                 <para>
415                 <emphasis>
416                         Default value is <quote>0</quote> (feature disabled).
417                 </emphasis>
418                 </para>
419                 <example>
420                 <title>Set <varname>udpping_from_path</varname> parameter</title>
421                 <programlisting format="linespecific">
422 ...
423 modparam("nathelper", "udpping_from_path", 1)
424 ...
425 </programlisting>
426                 </example>
427         </section>
428         <section id="nathelper.p.append_sdp_oldmediaip">
429                 <title><varname>append_sdp_oldmediaip</varname> (int)</title>
430                 <para>
431                 The parameter controls if oldmediaip field should be appended to the SDP.
432                 </para>
433                 <para>
434                 <emphasis>
435                         Default value is <quote>1</quote> (feature enabled).
436                 </emphasis>
437                 </para>
438                 <example>
439                 <title>Set <varname>append_sdp_oldmediaip</varname> parameter</title>
440                 <programlisting format="linespecific">
441 ...
442 modparam("nathelper", "append_sdp_oldmediaip", 1)
443 ...
444 </programlisting>
445                 </example>
446         </section>
447
448         <section id="nathelper.p.filter_server_id">
449                 <title><varname>filter_server_id</varname> (int)</title>
450                 <para>
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.
455                 <emphasis>
456                         Default value is <quote>0</quote> (disabled).
457                 </emphasis>
458                 </para>
459                 <example>
460                 <title>Set <varname>filter_server_id</varname> parameter</title>
461                 <programlisting format="linespecific">
462 ...
463 modparam("nathelper", "filter_server_id", 1)
464 ...
465 </programlisting>
466                 </example>
467         </section>
468
469         <section id="nathelper.p.nat_addr_mode">
470                 <title><varname>nat_addr_mode</varname> (int)</title>
471                 <para>
472                         If set to 0, only default private net addresses are checked by
473                         nat_uac_test(). If set to 1, other reserved net addresses are
474                         checked by nat_uac_test() as well.
475                 </para>
476                 <para>Default private net addresses are:</para>
477                 <itemizedlist>
478                         <listitem>
479                                 <para>10.0.0.0/8</para>
480                         <listitem>
481                         <listitem>
482                                 <para>172.16.0.0/12</para>
483                         <listitem>
484                         <listitem>
485                                 <para>192.168.0.0/16</para>
486                         <listitem>
487                         <listitem>
488                                 <para>100.64.0.0/10 - RFC6598 - Carrier Grade NAT</para>
489                         <listitem>
490                         <listitem>
491                                 <para>192.0.0.0/29 - RFC7335 - IPv4 Service Continuity Prefix</para>
492                         <listitem>
493                 <itemizedlist>
494                 <para>Reserved net addresses are:</para>
495                 <itemizedlist>
496                         <listitem>
497                                 <para>192.0.0.0/24 - RFC7335 - IETF Protocol Assignments</para>
498                         <listitem>
499                 <itemizedlist>
500                 <para>
501                 <emphasis>
502                         Default value is <quote>1</quote>.
503                 </emphasis>
504                 </para>
505                 <example>
506                 <title>Set <varname>nat_addr_mode</varname> parameter</title>
507                 <programlisting format="linespecific">
508 ...
509 modparam("nathelper", "nat_addr_mode", 0)
510 ...
511 </programlisting>
512                 </example>
513         </section>
514
515         </section>
516
517
518         <section>
519         <title>Functions</title>
520         <section id="nathelper.f.fix_nated_contact">
521                 <title>
522                 <function moreinfo="none">fix_nated_contact()</function>
523                 </title>
524                 <para>
525                 Rewrites the <quote>Contact</quote> header to contain the request's source 
526                 address:port.
527                 </para>
528                 <para>
529                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.
530                 </para>
531                 <example>
532                 <title><function>fix_nated_contact</function> usage</title>
533                 <programlisting format="linespecific">
534 ...
535 if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
536 ...
537 </programlisting>
538                 </example>
539         </section>
540         <section id="nathelper.f.fix_nated_sdp">
541                 <title>
542                 <function moreinfo="none">fix_nated_sdp(flags [, ip_address])</function>
543                 </title>
544                 <para>
545                 Alters the SDP information in order to facilitate NAT traversal. What
546                 changes to be performed may be controlled via the 
547                 <quote>flags</quote> parameter. Return value is -1 if error occurred,
548                 1 if ip's were replaced, 2 if no ip's were replaced.
549                 </para>
550                 <para>Meaning of the parameters is as follows:</para>
551                 <itemizedlist>
552                         <listitem><para>
553                         <emphasis>flags</emphasis> - the value may be a bitwise OR of 
554                         the following flags:
555                         </para>
556                         <itemizedlist>
557                                 <listitem>
558                                         <para><emphasis>0x01</emphasis> - adds 
559                                         <quote>a=direction:active</quote> SDP line;
560                                         </para>
561                                 </listitem>
562                                 <listitem>
563                                         <para><emphasis>0x02</emphasis> - rewrite media
564                                         &ip; address (c=) with source address of the message
565                                         or the provided IP address (the provide IP address take
566                                         precedence over the source address).</para>
567                                 </listitem>
568                                 <listitem>
569                                         <para><emphasis>0x04</emphasis> - adds 
570                                                 <quote>a=nortpproxy:yes</quote> SDP line;</para>
571                                 </listitem>
572                                 <listitem>
573                                         <para><emphasis>0x08</emphasis> - rewrite IP from
574                                         origin description (o=) with source address of the message
575                                         or the provided IP address (the provide IP address take
576                                         precedence over the source address).</para>
577                                 </listitem>
578                         </itemizedlist>
579                         </listitem>
580                         <listitem><para>
581                         <emphasis>ip_address</emphasis> - IP to be used for rewriting SDP.
582                         If not specified, the received signalling IP will be used. The
583                         parameter allows pseudo-variables usage. NOTE: For the IP to be
584                         used, you need to use 0x02 or 0x08 flags, otherwise it will have
585                         no effect.
586                         </para>
587                         </listitem>
588                 </itemizedlist>
589                 <para>
590                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
591                 FAILURE_ROUTE, BRANCH_ROUTE.
592                 </para>
593                 <example>
594                 <title><function>fix_nated_sdp</function> usage</title>
595                 <programlisting format="linespecific">
596 ...
597 if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
598 ...
599 </programlisting>
600                 </example>
601         </section>
602         <section id="nathelper.f.add_rcv_param">
603                 <title>
604                 <function moreinfo="none">add_rcv_param([flag])</function>,
605                 </title>
606                 <para>
607                 Add a received parameter to the <quote>Contact</quote> header fields
608                 (available for all transports) or to the Contact URI (available only
609                 for UDP traffic).
610                 </para>
611                 <para>
612                 The parameter will contain the URI created from the
613                 source IP, port, and protocol (if different than UDP) of the packet
614                 containing the SIP message. The parameter can be then processed by
615                 another registrar. This is useful, for example, when replicating register
616                 messages using <function>t_replicate</function> function to another registrar.
617                 </para>
618                 <para>Meaning of the parameters is as follows:</para>
619                 <itemizedlist>
620                         <listitem><para>
621                         <emphasis>flag</emphasis> - flags to indicate if the parameter
622                         should be added to Contact URI or Contact header. If the flag is
623                         non-zero, the parameter will be added to the Contact URI. If not
624                         used or equal to zero, the parameter will go to the Contact
625                         header.
626                         </para></listitem>
627                 </itemizedlist>
628                 <para>
629                 This function can be used from REQUEST_ROUTE.
630                 </para>
631                 <example>
632                 <title><function>add_rcv_paramer</function> usage</title>
633                 <programlisting format="linespecific">
634 ...
635 add_rcv_param(); # add the parameter to the Contact header
636 ....
637 add_rcv_param("1"); # add the parameter to the Contact URI
638 ...
639 </programlisting>
640                 </example>
641         </section>
642         <section id="nathelper.f.fix_nated_register">
643                 <title>
644                 <function moreinfo="none">fix_nated_register()</function>
645                 </title>
646                 <para>
647                 The function creates a URI consisting of the source IP, port, and 
648                 protocol and stores the URI in an Attribute-Value-Pair. The URI will 
649                 be appended as "received" parameter to Contact in 200 OK and 
650                 registrar will store it in the received column in the location table.
651                 </para>
652                 <para>
653                 Note: You have to set the <quote>received_avp</quote> parameter of the
654                 nathelper module and the registrar module (both module parameters must
655                 have the same value) to use this function.
656                 </para>
657                 <para>
658                 This function can be used from REQUEST_ROUTE.
659                 </para>
660                 <example>
661                 <title><function>fix_nated_register</function> usage</title>
662                 <programlisting format="linespecific">
663 ...
664 fix_nated_register();
665 ...
666 </programlisting>
667                 </example>
668         </section>
669         <section id="nathelper.f.nat_uac_test">
670                 <title>
671                         <function>nat_uac_test(flags)</function>
672                 </title>
673                 <para>
674                         Tries to guess if client's request originated behind a nat.
675                         The parameter determines what heuristics is used.
676                 </para>
677                 <para>Meaning of the flags is as follows:</para>
678                 <itemizedlist>
679                         <listitem><para>
680                         <emphasis>1</emphasis> -  The <quote>Contact</quote> header field is searched 
681                         for occurrence of RFC1918 or RFC6598 addresses.
682                         </para></listitem>
683                         <listitem><para>
684                         <emphasis>2</emphasis> -  the "received" test is used: address
685                         in the <quote>Via</quote> header is compared against source
686                         IP address of signaling. If the <quote>Via</quote> header contains
687                         no port, it uses the default SIP port 5060
688                         </para></listitem>
689                         <listitem><para>
690                         <emphasis>4</emphasis> -  The Top Most <quote>Via</quote> is searched 
691                         for occurrence of RFC1918 or RFC6598 addresses
692                         </para></listitem>
693                         <listitem><para>
694                         <emphasis>8</emphasis> -  The SDP is searched for occurrence of 
695                         RFC1918 or RFC6598 addresses
696                         </para></listitem>
697                         <listitem><para>
698                         <emphasis>16</emphasis> -  Test if the source port is different from the port
699                         in the <quote>Via</quote> header. If the <quote>Via</quote> header contains
700                         no port, it uses the default SIP port 5060
701                         </para></listitem>
702                         <listitem><para>
703                         <emphasis>32</emphasis> -  Test if the source IP address of
704                         signaling is a RFC1918 or RFC6598 address
705                         </para></listitem>
706                         <listitem><para>
707                         <emphasis>64</emphasis> -  Test if the source connection of
708                         signaling is a WebSocket
709                         </para></listitem>
710                         <listitem><para>
711                         <emphasis>128</emphasis> -  Test if the <quote>Contact</quote> header
712                         URI port differs from the source port of the request (Warning: this is
713                         might be legal or even intended combination in non NATted scenarios)
714                         </para></listitem>
715                         <listitem><para>
716                         <emphasis>256</emphasis> -  Test if the SDP connection address is different
717                         from source IP address. It will work also with multiple connection address
718                         lines.
719                         </para></listitem>
720                         </itemizedlist>
721                 <para>
722                 All flags can be bitwise combined, the test returns true if any of 
723                 the tests identified a NAT.
724                 </para>
725                 <para>
726                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
727                 </para>
728                 <example>
729                 <title><function>nat_uac_test</function> usage</title>
730                 <programlisting format="linespecific">
731 ...
732 if(nat_uac_test("19")) {
733     rtpproxy_manage("co");
734 }
735 ...
736 </programlisting>
737                 </example>
738         </section>
739
740         <section id="nathelper.f.is_rfc1918">
741                 <title>
742                 <function>is_rfc1918(ip_address)</function>
743                 </title>
744                 <para>
745                         Determines if the address in the parameter is an rfc1918 or rfc6598 address.
746                         The parameter allows pseudo-variables usage.
747                 </para>
748                 <para>
749                 This function can be used from ANY_ROUTE.
750                 </para>
751                 <example>
752                 <title><function>is_rfc1918</function> usage</title>
753                 <programlisting format="linespecific">
754 ...
755 if(is_rfc1918("$rd")) {
756     # domain in r-uri is private address
757 }
758 ...
759 </programlisting>
760                 </example>
761         </section>
762
763         <section id="nathelper.f.add_contact_alias">
764                 <title>
765                 <function moreinfo="none">add_contact_alias([ip_addr, port, proto])</function>
766                 </title>
767                 <para>
768                 Adds an <quote>;alias=ip~port~transport</quote> parameter to
769                 the contact URI containing either received ip, port, and
770                 transport protocol or those given as parameters.  If called
771                 without parameters, <quote>;alias</quote> parameter is
772                 only added if received ip, port, or transport protocol differs
773         from that in contact URI.
774                 </para>
775                 <para>
776                 This function can be used from
777                 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and LOCAL_ROUTE.
778                 </para>
779                 <example>
780                 <title><function>add_contact_alias</function> usage</title>
781                 <programlisting format="linespecific">
782 ...
783     if (!is_present_hf("Record-Route")) {
784         if (!add_contact_alias("$var(src_ip)", "$Rp", "tcp")) {
785             xlog("L_ERR", "Error in aliasing contact $ct\n");
786             send_reply("400", "Bad request");
787             exit;
788         };
789     };
790 ...
791                 </programlisting>
792                 </example>
793         </section>
794
795         <section id="nathelper.f.handle_ruri_alias">
796                 <title>
797                 <function moreinfo="none">handle_ruri_alias()</function>
798                 </title>
799                 <para>
800                 Checks if the Request URI has an <quote>alias</quote>
801                 parameter and if so, removes it and sets the <quote>$du</quote> based
802                 on its value.  Note that this means that routing of request is based on 
803                 <quote>;alias</quote> parameter value of the Request URI rather than 
804                 the Request URI itself. If you call <function>handle_ruri_alias()</function>
805                 on a request, make sure that you screen the alias parameter value of
806                 Request URI the same way as you would screen the
807                 Request URI itself.
808                 </para>
809                 <para>
810                 Returns <emphasis>1</emphasis> if <quote>;alias</quote> parameter was
811                 found and <quote>$du</quote> was set and the <quote>$ru</quote> rewritten,
812                 <emphasis>2</emphasis> if the alias parameter was not found and
813                 nothing was done, or <emphasis>-1</emphasis> in case of error.
814                 </para>
815                 <para>
816                 This function can be used from
817                 REQUEST_ROUTE, BRANCH_ROUTE, and LOCAL_ROUTE.
818                 </para>
819                 <example>
820                 <title><function>handle_ruri_alias</function> usage</title>
821                 <programlisting format="linespecific">
822 ...
823     if ($du == "") {
824         handle_ruri_alias();
825         switch ($rc) {
826         case -1:
827             xlog("L_ERR", "Failed to handle alias of R-URI $ru\n");
828             send_reply("400", "Bad request");
829             exit;
830         case 1:
831             xlog("L_INFO", "Routing in-dialog $rm from $fu to $du\n");
832             break;
833         case 2:
834             xlog("L_INFO", "Routing in-dialog $rm from $fu to $ru\n");
835             break;
836          };
837     };
838 ...
839                 </programlisting>
840                 </example>
841         </section>
842
843         <section id="nathelper.set_contact_alias">
844                 <title>
845                 <function moreinfo="none">set_contact_alias()</function>
846                 </title>
847                 <para>
848                 Adds an <quote>;alias=ip~port~transport</quote> parameter to the
849                 contact URI containing the received ip, port, and transport protocol.
850                 The new contact URI is immediately visible to other modules in the
851                 way the <function>fix_nated_contact()</function> does it.
852                 </para>
853                 <para>
854                 This function can be used from
855                 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and FAILURE_ROUTE.
856                 </para>
857                 <example>
858                 <title><function>set_contact_alias</function> usage</title>
859                 <programlisting format="linespecific">
860 ...
861     if (!is_present_hf("Record-Route")) {
862         if (!set_contact_alias()) {
863             xlog("L_ERR", "Error in aliasing contact $ct\n");
864             send_reply("400", "Bad request");
865             exit;
866         };
867     };
868 ...
869                 </programlisting>
870                 </example>
871         </section>
872                 <section id="nathelper.set_alias_to_pv">
873                 <title>
874                 <function moreinfo="none">set_alias_to_pv(target_avp)</function>
875                 </title>
876                 <para>
877                 Reads <quote>;alias=ip~port~transport</quote> from Contact header then
878                 writes to target pseudo-variable as a sip uri.
879                 </para>
880                 <para>
881                 This function can be used from
882                 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and FAILURE_ROUTE.
883                 </para>
884                 <example>
885                 <title><function>set_alias_to_pv</function> usage</title>
886                 <programlisting format="linespecific">
887 ...
888                 set_alias_to_pv("$avp(aliasuri)");
889 ...
890                 </programlisting>
891                 </example>
892         </section>
893
894         </section>
895
896         <section>
897                 <title>Exported Pseudo Variables</title>
898                 <section>
899                         <title><function moreinfo="none">$rr_count</function></title>
900                         <para>
901                         Number of Record Routes in received SIP request
902                         or reply.
903                         </para>
904                 <example>
905                 <title>$rr_count usage</title>
906                 <programlisting format="linespecific">
907 ...
908     $avp(rr_count) = $rr_count;
909 ...
910                 </programlisting>
911                 </example>
912                 </section>
913
914                 <section>
915                         <title><function moreinfo="none">$rr_top_count</function></title>
916                         <para>
917                         If topmost Record Route in received SIP request
918                         or reply is a double Record Route, value of
919                         $rr_top_count is 2.  If it a single Record
920                         Route, value of $rr_top_count 
921                         is 1.  If there is no Record Route(s), value of
922                         $rr_top_count is 0.
923                         </para>
924                 <example>
925                 <title>$rr_top_count usage</title>
926                 <programlisting format="linespecific">
927 ...
928     if ($rr_count == $avp(rr_count) + $rr_top_count) {
929         route(ADD_CONTACT_ALIAS);
930     };
931 ...
932                 </programlisting>
933                 </example>
934                 </section>
935
936         </section>
937
938         <section>
939                 <title>RPC Commands</title>
940                 <section id="nathelper.r.enable_ping">
941                         <title><function moreinfo="none">nathelper.enable_ping</function></title>
942                         <para>
943                         Enables natping if parameter value different than 0.
944                         Disables natping if parameter value is 0.
945                         </para>
946                         <para>
947                         The function takes only one parameter - a number in decimal format.
948                         </para>
949                         <example>
950                         <title><function moreinfo="none">nathelper.enable_ping</function> usage</title>
951                         <programlisting format="linespecific">
952 ...
953 $ &kamcmd; nathelper.enable_ping 1
954 ...
955                         </programlisting>
956                         </example>
957                 </section>
958
959         </section>
960
961         <section>
962                 <title>Selects</title>
963
964                 <section id="nathelper.s.rewrite_contact">
965                 <title>@nathelper.rewrite_contact[n]</title>
966                 <para>
967                         Get n-th Contact value with IP:Port rewritten to source ip:port. N is counted from 1.
968                     Only IP:port is rewritten, remaining part are left unchanged. Full nameaddr is supported.
969                 </para>
970                 <example>
971                         <title>@nathelper.rewrite_contact usage</title>
972                         <programlisting>
973 ...
974 $c = @nathelper.rewrite_contact[1];
975 ...
976 $c2 = @nathelper.rewrite_contact[1].nameaddr.uri;
977                         </programlisting>
978                 </example>
979                 </section>
980
981         </section>
982
983 </chapter>
984