732a617396c83cd4f5ac0892331a976925216feb
[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>
470
471
472         <section>
473         <title>Functions</title>
474         <section id="nathelper.f.fix_nated_contact">
475                 <title>
476                 <function moreinfo="none">fix_nated_contact()</function>
477                 </title>
478                 <para>
479                 Rewrites the <quote>Contact</quote> header to contain the request's source 
480                 address:port.
481                 </para>
482                 <para>
483                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.
484                 </para>
485                 <example>
486                 <title><function>fix_nated_contact</function> usage</title>
487                 <programlisting format="linespecific">
488 ...
489 if (search("User-Agent: Cisco ATA.*") {fix_nated_contact();};
490 ...
491 </programlisting>
492                 </example>
493         </section>
494         <section id="nathelper.f.fix_nated_sdp">
495                 <title>
496                 <function moreinfo="none">fix_nated_sdp(flags [, ip_address])</function>
497                 </title>
498                 <para>
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.
503                 </para>
504                 <para>Meaning of the parameters is as follows:</para>
505                 <itemizedlist>
506                         <listitem><para>
507                         <emphasis>flags</emphasis> - the value may be a bitwise OR of 
508                         the following flags:
509                         </para>
510                         <itemizedlist>
511                                 <listitem>
512                                         <para><emphasis>0x01</emphasis> - adds 
513                                         <quote>a=direction:active</quote> SDP line;
514                                         </para>
515                                 </listitem>
516                                 <listitem>
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>
521                                 </listitem>
522                                 <listitem>
523                                         <para><emphasis>0x04</emphasis> - adds 
524                                                 <quote>a=nortpproxy:yes</quote> SDP line;</para>
525                                 </listitem>
526                                 <listitem>
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>
531                                 </listitem>
532                         </itemizedlist>
533                         </listitem>
534                         <listitem><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
539                         no effect.
540                         </para>
541                         </listitem>
542                 </itemizedlist>
543                 <para>
544                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
545                 FAILURE_ROUTE, BRANCH_ROUTE.
546                 </para>
547                 <example>
548                 <title><function>fix_nated_sdp</function> usage</title>
549                 <programlisting format="linespecific">
550 ...
551 if (search("User-Agent: Cisco ATA.*") {fix_nated_sdp("3");};
552 ...
553 </programlisting>
554                 </example>
555         </section>
556         <section id="nathelper.f.add_rcv_param">
557                 <title>
558                 <function moreinfo="none">add_rcv_param([flag])</function>,
559                 </title>
560                 <para>
561                 Add a received parameter to the <quote>Contact</quote> header fields
562                 (available for all transports) or to the Contact URI (available only
563                 for UDP traffic).
564                 </para>
565                 <para>
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.
571                 </para>
572                 <para>Meaning of the parameters is as follows:</para>
573                 <itemizedlist>
574                         <listitem><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
579                         header.
580                         </para></listitem>
581                 </itemizedlist>
582                 <para>
583                 This function can be used from REQUEST_ROUTE.
584                 </para>
585                 <example>
586                 <title><function>add_rcv_paramer</function> usage</title>
587                 <programlisting format="linespecific">
588 ...
589 add_rcv_param(); # add the parameter to the Contact header
590 ....
591 add_rcv_param("1"); # add the parameter to the Contact URI
592 ...
593 </programlisting>
594                 </example>
595         </section>
596         <section id="nathelper.f.fix_nated_register">
597                 <title>
598                 <function moreinfo="none">fix_nated_register()</function>
599                 </title>
600                 <para>
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.
605                 </para>
606                 <para>
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.
610                 </para>
611                 <para>
612                 This function can be used from REQUEST_ROUTE.
613                 </para>
614                 <example>
615                 <title><function>fix_nated_register</function> usage</title>
616                 <programlisting format="linespecific">
617 ...
618 fix_nated_register();
619 ...
620 </programlisting>
621                 </example>
622         </section>
623         <section id="nathelper.f.nat_uac_test">
624                 <title>
625                         <function>nat_uac_test(flags)</function>
626                 </title>
627                 <para>
628                         Tries to guess if client's request originated behind a nat.
629                         The parameter determines what heuristics is used.
630                 </para>
631                 <para>Meaning of the flags is as follows:</para>
632                 <itemizedlist>
633                         <listitem><para>
634                         <emphasis>1</emphasis> -  The <quote>Contact</quote> header field is searched 
635                         for occurrence of RFC1918 or RFC6598 addresses.
636                         </para></listitem>
637                         <listitem><para>
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
642                         </para></listitem>
643                         <listitem><para>
644                         <emphasis>4</emphasis> -  The Top Most <quote>Via</quote> is searched 
645                         for occurrence of RFC1918 or RFC6598 addresses
646                         </para></listitem>
647                         <listitem><para>
648                         <emphasis>8</emphasis> -  The SDP is searched for occurrence of 
649                         RFC1918 or RFC6598 addresses
650                         </para></listitem>
651                         <listitem><para>
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
655                         </para></listitem>
656                         <listitem><para>
657                         <emphasis>32</emphasis> -  Test if the source IP address of
658                         signaling is a RFC1918 or RFC6598 address
659                         </para></listitem>
660                         <listitem><para>
661                         <emphasis>64</emphasis> -  Test if the source connection of
662                         signaling is a WebSocket
663                         </para></listitem>
664                         <listitem><para>
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)
668                         </para></listitem>
669                         <listitem><para>
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
672                         lines.
673                         </para></listitem>
674                         </itemizedlist>
675                 <para>
676                 All flags can be bitwise combined, the test returns true if any of 
677                 the tests identified a NAT.
678                 </para>
679                 <para>
680                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
681                 </para>
682                 <example>
683                 <title><function>nat_uac_test</function> usage</title>
684                 <programlisting format="linespecific">
685 ...
686 if(nat_uac_test("19")) {
687     rtpproxy_manage("co");
688 }
689 ...
690 </programlisting>
691                 </example>
692         </section>
693
694         <section id="nathelper.f.is_rfc1918">
695                 <title>
696                 <function>is_rfc1918(ip_address)</function>
697                 </title>
698                 <para>
699                         Determines if the address in the parameter is an rfc1918 or rfc6598 address.
700                         The parameter allows pseudo-variables usage.
701                 </para>
702                 <para>
703                 This function can be used from ANY_ROUTE.
704                 </para>
705                 <example>
706                 <title><function>is_rfc1918</function> usage</title>
707                 <programlisting format="linespecific">
708 ...
709 if(is_rfc1918("$rd")) {
710     # domain in r-uri is private address
711 }
712 ...
713 </programlisting>
714                 </example>
715         </section>
716
717         <section id="nathelper.f.add_contact_alias">
718                 <title>
719                 <function moreinfo="none">add_contact_alias([ip_addr, port, proto])</function>
720                 </title>
721                 <para>
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.
728                 </para>
729                 <para>
730                 This function can be used from
731                 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and LOCAL_ROUTE.
732                 </para>
733                 <example>
734                 <title><function>add_contact_alias</function> usage</title>
735                 <programlisting format="linespecific">
736 ...
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");
741             exit;
742         };
743     };
744 ...
745                 </programlisting>
746                 </example>
747         </section>
748
749         <section id="nathelper.f.handle_ruri_alias">
750                 <title>
751                 <function moreinfo="none">handle_ruri_alias()</function>
752                 </title>
753                 <para>
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
761                 Request URI itself.
762                 </para>
763                 <para>
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.
768                 </para>
769                 <para>
770                 This function can be used from
771                 REQUEST_ROUTE, BRANCH_ROUTE, and LOCAL_ROUTE.
772                 </para>
773                 <example>
774                 <title><function>handle_ruri_alias</function> usage</title>
775                 <programlisting format="linespecific">
776 ...
777     if ($du == "") {
778         handle_ruri_alias();
779         switch ($rc) {
780         case -1:
781             xlog("L_ERR", "Failed to handle alias of R-URI $ru\n");
782             send_reply("400", "Bad request");
783             exit;
784         case 1:
785             xlog("L_INFO", "Routing in-dialog $rm from $fu to $du\n");
786             break;
787         case 2:
788             xlog("L_INFO", "Routing in-dialog $rm from $fu to $ru\n");
789             break;
790          };
791     };
792 ...
793                 </programlisting>
794                 </example>
795         </section>
796
797         <section id="nathelper.set_contact_alias">
798                 <title>
799                 <function moreinfo="none">set_contact_alias()</function>
800                 </title>
801                 <para>
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.
806                 </para>
807                 <para>
808                 This function can be used from
809                 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and FAILURE_ROUTE.
810                 </para>
811                 <example>
812                 <title><function>set_contact_alias</function> usage</title>
813                 <programlisting format="linespecific">
814 ...
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");
819             exit;
820         };
821     };
822 ...
823                 </programlisting>
824                 </example>
825         </section>
826                 <section id="nathelper.set_alias_to_pv">
827                 <title>
828                 <function moreinfo="none">set_alias_to_pv(target_avp)</function>
829                 </title>
830                 <para>
831                 Reads <quote>;alias=ip~port~transport</quote> from Contact header then
832                 writes to target pseudo-variable as a sip uri.
833                 </para>
834                 <para>
835                 This function can be used from
836                 REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, and FAILURE_ROUTE.
837                 </para>
838                 <example>
839                 <title><function>set_alias_to_pv</function> usage</title>
840                 <programlisting format="linespecific">
841 ...
842                 set_alias_to_pv("$avp(aliasuri)");
843 ...
844                 </programlisting>
845                 </example>
846         </section>
847
848         </section>
849
850         <section>
851                 <title>Exported Pseudo Variables</title>
852                 <section>
853                         <title><function moreinfo="none">$rr_count</function></title>
854                         <para>
855                         Number of Record Routes in received SIP request
856                         or reply.
857                         </para>
858                 <example>
859                 <title>$rr_count usage</title>
860                 <programlisting format="linespecific">
861 ...
862     $avp(rr_count) = $rr_count;
863 ...
864                 </programlisting>
865                 </example>
866                 </section>
867
868                 <section>
869                         <title><function moreinfo="none">$rr_top_count</function></title>
870                         <para>
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
876                         $rr_top_count is 0.
877                         </para>
878                 <example>
879                 <title>$rr_top_count usage</title>
880                 <programlisting format="linespecific">
881 ...
882     if ($rr_count == $avp(rr_count) + $rr_top_count) {
883         route(ADD_CONTACT_ALIAS);
884     };
885 ...
886                 </programlisting>
887                 </example>
888                 </section>
889
890         </section>
891
892         <section>
893                 <title>RPC Commands</title>
894                 <section id="nathelper.r.enable_ping">
895                         <title><function moreinfo="none">nathelper.enable_ping</function></title>
896                         <para>
897                         Enables natping if parameter value different than 0.
898                         Disables natping if parameter value is 0.
899                         </para>
900                         <para>
901                         The function takes only one parameter - a number in decimal format.
902                         </para>
903                         <example>
904                         <title><function moreinfo="none">nathelper.enable_ping</function> usage</title>
905                         <programlisting format="linespecific">
906 ...
907 $ &kamcmd; nathelper.enable_ping 1
908 ...
909                         </programlisting>
910                         </example>
911                 </section>
912
913         </section>
914
915         <section>
916                 <title>Selects</title>
917
918                 <section id="nathelper.s.rewrite_contact">
919                 <title>@nathelper.rewrite_contact[n]</title>
920                 <para>
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.
923                 </para>
924                 <example>
925                         <title>@nathelper.rewrite_contact usage</title>
926                         <programlisting>
927 ...
928 $c = @nathelper.rewrite_contact[1];
929 ...
930 $c2 = @nathelper.rewrite_contact[1].nameaddr.uri;
931                         </programlisting>
932                 </example>
933                 </section>
934
935         </section>
936
937 </chapter>
938