ipops: added dsn_int_match_ip(hostname, ipaddr)
[sip-router] / modules / ipops / doc / ipops_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 "../../../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          
19     <title>Overview</title>
20          
21     <para>
22       The IPops module offers operations for handling IP addresses, both IPv4 and IPv6.
23     </para>
24     <para>
25       IPv6 is defined in <ulink url="http://tools.ietf.org/html/rfc2460">RFC 2460</ulink>.
26         The same IPv6 address can be represented by different ASCII strings, so binary comparison is required.
27         For example, the following IPv6 addresses are equivalent:
28     </para>
29
30     <itemizedlist>
31       <listitem>
32         <para>2001:DB8:0000:0000:0008:0800:200C:417A</para>
33       </listitem>
34       <listitem>
35         <para>2001:DB8:0:0:8:800:200C:417A</para>
36       </listitem>
37       <listitem>
38         <para>2001:DB8::200C:417A</para>
39       </listitem>
40     </itemizedlist>
41
42     <para>
43         When using IPv6 in an URI (i.e. a SIP URI) the IP address must be written in "IPv6 reference" format 
44         (which is the textual representation of the IPv6 enclosed between [ ] symbols).
45         An example is <quote>sip:alice@[2001:DB8:0:0:8:800:200C:417A]</quote>. This allows separation of
46         address and port number with a :, like <quote>[2001:DB8:0:0:8:800:200C:417A]:5060</quote>.
47         This module also allows comparing an IPv6 address with its IPv6 reference representation.
48     </para>
49            
50   </section>
51            
52   <section>
53              
54     <title>Dependencies</title>
55              
56     <section>
57       <title>&siprouter; Modules</title>
58       <para>
59         The following modules must be loaded before this module:
60         <itemizedlist>
61           <listitem>
62             <para>
63               <emphasis>No dependencies on other &siprouter; modules</emphasis>
64             </para>
65           </listitem>
66         </itemizedlist>
67       </para>
68     </section>
69                
70     <section>
71       <title>External Libraries or Applications</title>
72       <para>
73         The following libraries or applications must be installed before running &siprouter; with this module loaded:
74         <itemizedlist>
75           <listitem>
76             <para>
77               <emphasis>No dependencies on external libraries</emphasis>
78             </para>
79           </listitem>
80         </itemizedlist>
81       </para>
82     </section>
83              
84   </section>
85            
86   <section>
87
88     <title>Parameters</title>
89              
90   </section>
91            
92   <section>
93
94     <title>Functions</title>
95              
96     <section id="ipops.f.is_ip">
97       <title>
98         <function moreinfo="none">is_ip (ip)</function>
99       </title>
100
101       <para>
102         Returns TRUE if the argument is a valid IPv4, IPv6 or IPv6 reference. FALSE otherwise.
103       </para>
104
105       <para>Parameters:</para>
106
107       <itemizedlist>
108         <listitem>
109           <para>
110             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP address to evaluate.
111           </para>
112         </listitem>
113       </itemizedlist>
114
115       <para>
116         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
117       </para>
118
119       <example>
120         <title>
121           <function>is_ip</function> usage
122         </title>
123         <programlisting format="linespecific">
124 ...
125 if (is_ip($rd)) {
126   xlog("L_INFO", "RURI domain is an IP address (not a host name/domain)\n");
127 }
128 ...
129         </programlisting>
130       </example>
131
132     </section>
133
134     <section id="ipops.f.is_pur_ip">
135       <title>
136         <function moreinfo="none">is_pure_ip (ip)</function>
137       </title>
138
139       <para>
140         Returns TRUE if the argument is a valid IPv4 or IPv6. FALSE otherwise.
141       </para>
142
143       <para>Parameters:</para>
144
145       <itemizedlist>
146         <listitem>
147           <para>
148             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
149           </para>
150         </listitem>
151       </itemizedlist>
152
153       <para>
154         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
155       </para>
156
157       <example>
158         <title>
159           <function>is_pure_ip</function> usage
160         </title>
161         <programlisting format="linespecific">
162 ...
163 $var(ip) = "::1";
164 if (is_pure_ip($var(ip))) {
165   xlog("L_INFO", "it's IPv4 or IPv6\n");
166 }
167 ...
168         </programlisting>
169       </example>
170
171     </section>
172
173     <section id="ipops.f.is_ipv4">
174       <title>
175         <function moreinfo="none">is_ipv4 (ip)</function>
176       </title>
177
178       <para>
179         Returns TRUE if the argument is a valid IPv4. FALSE otherwise.
180       </para>
181
182       <para>Parameters:</para>
183
184       <itemizedlist>
185         <listitem>
186           <para>
187             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
188           </para>
189         </listitem>
190       </itemizedlist>
191
192       <para>
193         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
194       </para>
195
196       <example>
197         <title>
198           <function>is_ipv4</function> usage
199         </title>
200         <programlisting format="linespecific">
201 ...
202 if (is_ipv4("1.2.3.4")) {
203   xlog("L_INFO", "it's IPv4\n");
204 }
205 ...
206         </programlisting>
207       </example>
208
209     </section>
210
211     <section id="ipops.f.is_ipv6">
212       <title>
213         <function moreinfo="none">is_ipv6 (ip)</function>
214       </title>
215
216       <para>
217         Returns TRUE if the argument is a valid IPv6. FALSE otherwise.
218       </para>
219
220       <para>Parameters:</para>
221
222       <itemizedlist>
223         <listitem>
224           <para>
225             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
226           </para>
227         </listitem>
228       </itemizedlist>
229
230       <para>
231         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
232       </para>
233
234       <example>
235         <title>
236           <function>is_ipv6</function> usage
237         </title>
238         <programlisting format="linespecific">
239 ...
240 if (is_ipv6("1080:0:0:0:8:800:200C:417A")) {
241   xlog("L_INFO", "it's IPv6\n");
242 }
243 ...
244         </programlisting>
245       </example>
246
247     </section>
248
249     <section id="ipops.f.is_ipv6_reference">
250       <title>
251         <function moreinfo="none">is_ipv6_reference (ip)</function>
252       </title>
253
254       <para>
255         Returns TRUE if the argument is a valid IPv6 reference. FALSE otherwise.
256       </para>
257
258       <para>Parameters:</para>
259
260       <itemizedlist>
261         <listitem>
262           <para>
263             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
264           </para>
265         </listitem>
266       </itemizedlist>
267
268       <para>
269         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
270       </para>
271
272       <example>
273         <title>
274           <function>is_ipv6_reference</function> usage
275         </title>
276         <programlisting format="linespecific">
277 ...
278 if (is_ipv6_reference("[1080:0:0:0:8:800:200C:417A]")) {
279   xlog("L_INFO", "it's IPv6 reference\n");
280 }
281 ...
282         </programlisting>
283       </example>
284
285     </section>
286
287     <section id="ipops.f.is_ip_type">
288       <title>
289         <function moreinfo="none">ip_type (ip)</function>
290       </title>
291
292       <para>
293         Returns the type of the given IP.
294       </para>
295
296       <para>Parameters:</para>
297
298       <itemizedlist>
299         <listitem>
300           <para>
301             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
302           </para>
303         </listitem>
304       </itemizedlist>
305
306       <para>Return value:</para>
307
308       <itemizedlist>
309         <listitem>
310           <para>
311             <emphasis>1</emphasis> - IPv4
312           </para>
313         </listitem>
314         <listitem>
315           <para>
316             <emphasis>2</emphasis> - IPv6
317           </para>
318         </listitem>
319         <listitem>
320           <para>
321             <emphasis>3</emphasis> - IPv6 reference
322           </para>
323         </listitem>
324         <listitem>
325           <para>
326             <emphasis>-1</emphasis> - invalid IP
327           </para>
328         </listitem>
329       </itemizedlist>
330
331       <para>
332         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
333       </para>
334
335       <example>
336         <title>
337           <function>ip_type</function> usage
338         </title>
339         <programlisting format="linespecific">
340 ...
341 ip_type($var(myip));
342 switch($rc) {
343   case 1:
344     xlog("L_INFO", "it's IPv4\n");
345     break;
346   case 2:
347     xlog("L_INFO", "it's IPv6\n");
348     break;
349   case 3:
350     xlog("L_INFO", "it's IPv6 reference\n");
351     break;
352   case -1:
353     xlog("L_INFO", it's type invalid\n");
354     break;
355 }
356 ...
357         </programlisting>
358       </example>
359
360     </section>
361
362     <section id="ipops.f.compare_ips">
363       <title>
364         <function moreinfo="none">compare_ips (ip1, ip2)</function>
365       </title>
366
367       <para>
368         Returns TRUE if both IP addresses are the same. FALSE otherwise.
369         This function also allows comparing an IPv6 address against an IPv6 reference.
370       </para>
371
372       <para>Parameters:</para>
373
374       <itemizedlist>
375         <listitem>
376           <para>
377             <emphasis>ip1</emphasis> - String or pseudo-variable containing the first IP to compare.
378           </para>
379         </listitem>
380         <listitem>
381           <para>
382             <emphasis>ip2</emphasis> - String or pseudo-variable containing the second IP to compare.
383           </para>
384         </listitem>
385       </itemizedlist>
386
387       <para>
388         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
389       </para>
390
391       <example>
392         <title>
393           <function>compare_ips</function> usage
394         </title>
395         <programlisting format="linespecific">
396 ...
397 if (compare_ips("1080:0000:0000:0000:0008:0800:200C:417A", "[1080::8:800:200C:417A]")) {
398   xlog("L_INFO", "both are the same IP\n");
399 }
400 ...
401         </programlisting>
402       </example>
403
404     </section>
405
406     <section id="ipops.f.compare_pure_ips">
407       <title>
408         <function moreinfo="none">compare_pure_ips (ip1, ip2)</function>
409       </title>
410
411       <para>
412         Returns TRUE if both IP's are the same. FALSE otherwise. This function does NOT 
413         allow comparing an IPv6 against an IPv6 reference.
414       </para>
415
416       <para>Parameters:</para>
417
418       <itemizedlist>
419         <listitem>
420           <para>
421             <emphasis>ip1</emphasis> - String or pseudo-variable containing the first IP address to compare.
422           </para>
423         </listitem>
424         <listitem>
425           <para>
426             <emphasis>ip2</emphasis> - String or pseudo-variable containing the second IP address to compare.
427           </para>
428         </listitem>
429       </itemizedlist>
430
431       <para>
432         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
433       </para>
434
435       <example>
436         <title>
437           <function>compare_pure_ips</function> usage
438         </title>
439         <programlisting format="linespecific">
440 ...
441 if (compare_pure_ips($si, "1080::8:800:200C:417A")) {
442   xlog("L_INFO", "both are the same IP\n");
443 }
444 ...
445         </programlisting>
446       </example>
447
448     </section>
449
450     <section id="ipops.f.is_ip_rfc1918">
451       <title>
452         <function moreinfo="none">is_ip_rfc1918 (ip)</function>
453       </title>
454
455       <para>
456         Returns TRUE if the argument is a private IPv4 according to RFC 1918. FALSE otherwise.
457       </para>
458
459       <para>Parameters:</para>
460
461       <itemizedlist>
462         <listitem>
463           <para>
464             <emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
465           </para>
466         </listitem>
467       </itemizedlist>
468
469       <para>
470         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
471       </para>
472
473       <example>
474         <title>
475           <function>is_ip_rfc1918</function> usage
476         </title>
477         <programlisting format="linespecific">
478 ...
479 if (is_ip_rfc1918("10.0.123.123")) {
480   xlog("L_INFO", "it's a private IPv4\n");
481 }
482 ...
483         </programlisting>
484       </example>
485
486     </section>
487  
488     <section id="ipops.f.is_in_subnet">
489       <title>
490         <function moreinfo="none">is_in_subnet (ip, subnet)</function>
491       </title>
492
493       <para>
494         Returns TRUE if the first argument is an IP address within the (CIDR notation)
495         subnet in the second argument. FALSE otherwise.
496       </para>
497
498       <para>Parameters:</para>
499
500       <itemizedlist>
501         <listitem>
502           <para>
503             <emphasis>ip</emphasis> - string or pseudo-variable containing the ip to evaluate.
504           </para>
505         </listitem>
506         <listitem>
507           <para>
508             <emphasis>subnet</emphasis> - string or pseudo-variable containing the (CIDR notation) subnet to evaluate.
509           </para>
510         </listitem>
511       </itemizedlist>
512
513       <para>
514         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
515       </para>
516
517       <example>
518         <title>
519           <function>is_in_subnet</function> usage
520         </title>
521         <programlisting format="linespecific">
522 ...
523 if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
524   xlog("L_INFO", "it's in the subnet\n");
525 }
526 ...
527         </programlisting>
528       </example>
529
530     </section>
531
532     <section id="ipops.f.dns_sys_match_ip">
533       <title>
534         <function moreinfo="none">dns_sys_match_ip(hostname, ipaddr)</function>
535       </title>
536
537       <para>
538                   Returns TRUE if ipaddr is associated by DNS to hostname. FALSE otherwise. It
539                   does not use the internal DNS resolver, but directly getaddrinfo(...). All
540                   addresses returned for the hostname are checked. Note that some hosts may
541                   return different lists of IP addresses for each query, if the DNS server
542                   is configured in that way (e.g., for providing load balancing through DNS).
543       </para>
544
545       <para>Parameters:</para>
546
547       <itemizedlist>
548         <listitem>
549           <para>
550             <emphasis>ipaddr</emphasis> - string or pseudo-variable containing the ip address.
551           </para>
552         </listitem>
553         <listitem>
554           <para>
555                           <emphasis>hostname</emphasis> - string or pseudo-variable containing the hostname.
556                           The resulting IP addresses from DNS query are compared with ipaddr.
557           </para>
558         </listitem>
559       </itemizedlist>
560
561       <para>
562         This function can be used from ANY_ROUTE.
563       </para>
564
565       <example>
566         <title>
567           <function>dns_sys_match_ip</function> usage
568         </title>
569         <programlisting format="linespecific">
570 ...
571 if (!dns_sys_match_ip("myhost.com", "1.2.3.4")) {
572     xdbg("ip address not associated with hostname\n");
573 }
574 ...
575         </programlisting>
576       </example>
577
578     </section>
579
580     <section id="ipops.f.dns_int_match_ip">
581       <title>
582         <function moreinfo="none">dns_int_match_ip(hostname, ipaddr)</function>
583       </title>
584
585       <para>
586                   Returns TRUE if ipaddr is associated by DNS to hostname. FALSE otherwise. It
587                   uses internal DNS resolver. At this moment, the function might not check all
588                   the IP addresses as returned by dns_sys_match_ip(), because the internal
589                   resolver targets to discover the first address to be used for relaying
590                   SIP traffic. Thus is better to use dns_sys_match_ip() if the host you want
591                   to check has many IP addresses, in different address famililies (IPv4/6).
592       </para>
593
594       <para>Parameters:</para>
595
596       <itemizedlist>
597         <listitem>
598           <para>
599             <emphasis>ipaddr</emphasis> - string or pseudo-variable containing the ip address.
600           </para>
601         </listitem>
602         <listitem>
603           <para>
604                           <emphasis>hostname</emphasis> - string or pseudo-variable containing the hostname.
605                           The resulting IP addresses from DNS query are compared with ipaddr.
606           </para>
607         </listitem>
608       </itemizedlist>
609
610       <para>
611         This function can be used from ANY_ROUTE.
612       </para>
613
614       <example>
615         <title>
616           <function>dns_int_match_ip</function> usage
617         </title>
618         <programlisting format="linespecific">
619 ...
620 if (!dns_int_match_ip("myhost.com", "1.2.3.4")) {
621     xdbg("ip address not associated with hostname\n");
622 }
623 ...
624         </programlisting>
625       </example>
626
627     </section>
628
629   </section>
630  
631 </chapter>