Browse code

Updating documentation

Lucian Balaceanu authored on 31/08/2016 08:43:24
Showing 2 changed files
... ...
@@ -1,16 +1,16 @@
1 1
 ipops Module
2 2
 
3
-I�aki Baz Castillo
3
+Iñaki Baz Castillo
4 4
 
5 5
    <ibc@aliax.net>
6 6
 
7 7
 Edited by
8 8
 
9
-I�aki Baz Castillo
9
+Iñaki Baz Castillo
10 10
 
11 11
    <ibc@aliax.net>
12 12
 
13
-   Copyright � 2011 I�aki Baz Castillo
13
+   Copyright © 2011 Iñaki Baz Castillo
14 14
      __________________________________________________________________
15 15
 
16 16
    Table of Contents
... ...
@@ -32,13 +32,16 @@ I
32 32
               4.4. is_ipv6 (ip)
33 33
               4.5. is_ipv6_reference (ip)
34 34
               4.6. ip_type (ip)
35
-              4.7. compare_ips (ip1, ip2)
36
-              4.8. compare_pure_ips (ip1, ip2)
37
-              4.9. is_ip_rfc1918 (ip)
38
-              4.10. is_in_subnet (ip, subnet)
39
-              4.11. dns_sys_match_ip(hostname, ipaddr)
40
-              4.12. dns_int_match_ip(hostname, ipaddr)
41
-              4.13. dns_query(hostname, pvid)
35
+              4.7. detailed_ip_type (ip, result)
36
+              4.8. detailed_ipv4_type (ip, result)
37
+              4.9. detailed_ipv6_type (ip, result)
38
+              4.10. compare_ips (ip1, ip2)
39
+              4.11. compare_pure_ips (ip1, ip2)
40
+              4.12. is_ip_rfc1918 (ip)
41
+              4.13. is_in_subnet (ip, subnet)
42
+              4.14. dns_sys_match_ip(hostname, ipaddr)
43
+              4.15. dns_int_match_ip(hostname, ipaddr)
44
+              4.16. dns_query(hostname, pvid)
42 45
 
43 46
    List of Examples
44 47
 
... ...
@@ -48,13 +51,16 @@ I
48 51
    1.4. is_ipv6 usage
49 52
    1.5. is_ipv6_reference usage
50 53
    1.6. ip_type usage
51
-   1.7. compare_ips usage
52
-   1.8. compare_pure_ips usage
53
-   1.9. is_ip_rfc1918 usage
54
-   1.10. is_in_subnet usage
55
-   1.11. dns_sys_match_ip usage
56
-   1.12. dns_int_match_ip usage
57
-   1.13. dns_query usage
54
+   1.7. detailed_ip_type usage
55
+   1.8. detailed_ipv4_type usage
56
+   1.9. detailed_ipv6_type usage
57
+   1.10. compare_ips usage
58
+   1.11. compare_pure_ips usage
59
+   1.12. is_ip_rfc1918 usage
60
+   1.13. is_in_subnet usage
61
+   1.14. dns_sys_match_ip usage
62
+   1.15. dns_int_match_ip usage
63
+   1.16. dns_query usage
58 64
 
59 65
 Chapter 1. Admin Guide
60 66
 
... ...
@@ -75,13 +81,16 @@ Chapter 1. Admin Guide
75 81
         4.4. is_ipv6 (ip)
76 82
         4.5. is_ipv6_reference (ip)
77 83
         4.6. ip_type (ip)
78
-        4.7. compare_ips (ip1, ip2)
79
-        4.8. compare_pure_ips (ip1, ip2)
80
-        4.9. is_ip_rfc1918 (ip)
81
-        4.10. is_in_subnet (ip, subnet)
82
-        4.11. dns_sys_match_ip(hostname, ipaddr)
83
-        4.12. dns_int_match_ip(hostname, ipaddr)
84
-        4.13. dns_query(hostname, pvid)
84
+        4.7. detailed_ip_type (ip, result)
85
+        4.8. detailed_ipv4_type (ip, result)
86
+        4.9. detailed_ipv6_type (ip, result)
87
+        4.10. compare_ips (ip1, ip2)
88
+        4.11. compare_pure_ips (ip1, ip2)
89
+        4.12. is_ip_rfc1918 (ip)
90
+        4.13. is_in_subnet (ip, subnet)
91
+        4.14. dns_sys_match_ip(hostname, ipaddr)
92
+        4.15. dns_int_match_ip(hostname, ipaddr)
93
+        4.16. dns_query(hostname, pvid)
85 94
 
86 95
 1. Overview
87 96
 
... ...
@@ -98,9 +107,9 @@ Chapter 1. Admin Guide
98 107
    When using IPv6 in an URI (i.e. a SIP URI) the IP address must be
99 108
    written in "IPv6 reference" format (which is the textual representation
100 109
    of the IPv6 enclosed between [ ] symbols). An example is
101
-   "sip:alice@[2001:DB8:0:0:8:800:200C:417A]". This allows separation of
110
+   “sip:alice@[2001:DB8:0:0:8:800:200C:417A]”. This allows separation of
102 111
    address and port number with a :, like
103
-   "[2001:DB8:0:0:8:800:200C:417A]:5060". This module also allows
112
+   “[2001:DB8:0:0:8:800:200C:417A]:5060”. This module also allows
104 113
    comparing an IPv6 address with its IPv6 reference representation.
105 114
 
106 115
 2. Dependencies
... ...
@@ -129,15 +138,18 @@ Chapter 1. Admin Guide
129 138
    4.4. is_ipv6 (ip)
130 139
    4.5. is_ipv6_reference (ip)
131 140
    4.6. ip_type (ip)
132
-   4.7. compare_ips (ip1, ip2)
133
-   4.8. compare_pure_ips (ip1, ip2)
134
-   4.9. is_ip_rfc1918 (ip)
135
-   4.10. is_in_subnet (ip, subnet)
136
-   4.11. dns_sys_match_ip(hostname, ipaddr)
137
-   4.12. dns_int_match_ip(hostname, ipaddr)
138
-   4.13. dns_query(hostname, pvid)
139
-
140
-4.1. is_ip (ip)
141
+   4.7. detailed_ip_type (ip, result)
142
+   4.8. detailed_ipv4_type (ip, result)
143
+   4.9. detailed_ipv6_type (ip, result)
144
+   4.10. compare_ips (ip1, ip2)
145
+   4.11. compare_pure_ips (ip1, ip2)
146
+   4.12. is_ip_rfc1918 (ip)
147
+   4.13. is_in_subnet (ip, subnet)
148
+   4.14. dns_sys_match_ip(hostname, ipaddr)
149
+   4.15. dns_int_match_ip(hostname, ipaddr)
150
+   4.16. dns_query(hostname, pvid)
151
+
152
+4.1.  is_ip (ip)
141 153
 
142 154
    Returns TRUE if the argument is a valid IPv4, IPv6 or IPv6 reference.
143 155
    FALSE otherwise.
... ...
@@ -149,14 +161,14 @@ Chapter 1. Admin Guide
149 161
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
150 162
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
151 163
 
152
-   Example 1.1. is_ip usage
164
+   Example 1.1.  is_ip usage
153 165
 ...
154 166
 if (is_ip($rd)) {
155 167
   xlog("L_INFO", "RURI domain is an IP address (not a host name/domain)\n");
156 168
 }
157 169
 ...
158 170
 
159
-4.2. is_pure_ip (ip)
171
+4.2.  is_pure_ip (ip)
160 172
 
161 173
    Returns TRUE if the argument is a valid IPv4 or IPv6. FALSE otherwise.
162 174
 
... ...
@@ -166,7 +178,7 @@ if (is_ip($rd)) {
166 178
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
167 179
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
168 180
 
169
-   Example 1.2. is_pure_ip usage
181
+   Example 1.2.  is_pure_ip usage
170 182
 ...
171 183
 $var(ip) = "::1";
172 184
 if (is_pure_ip($var(ip))) {
... ...
@@ -174,7 +186,7 @@ if (is_pure_ip($var(ip))) {
174 186
 }
175 187
 ...
176 188
 
177
-4.3. is_ipv4 (ip)
189
+4.3.  is_ipv4 (ip)
178 190
 
179 191
    Returns TRUE if the argument is a valid IPv4. FALSE otherwise.
180 192
 
... ...
@@ -184,14 +196,14 @@ if (is_pure_ip($var(ip))) {
184 196
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
185 197
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
186 198
 
187
-   Example 1.3. is_ipv4 usage
199
+   Example 1.3.  is_ipv4 usage
188 200
 ...
189 201
 if (is_ipv4("1.2.3.4")) {
190 202
   xlog("L_INFO", "it's IPv4\n");
191 203
 }
192 204
 ...
193 205
 
194
-4.4. is_ipv6 (ip)
206
+4.4.  is_ipv6 (ip)
195 207
 
196 208
    Returns TRUE if the argument is a valid IPv6. FALSE otherwise.
197 209
 
... ...
@@ -201,14 +213,14 @@ if (is_ipv4("1.2.3.4")) {
201 213
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
202 214
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
203 215
 
204
-   Example 1.4. is_ipv6 usage
216
+   Example 1.4.  is_ipv6 usage
205 217
 ...
206 218
 if (is_ipv6("1080:0:0:0:8:800:200C:417A")) {
207 219
   xlog("L_INFO", "it's IPv6\n");
208 220
 }
209 221
 ...
210 222
 
211
-4.5. is_ipv6_reference (ip)
223
+4.5.  is_ipv6_reference (ip)
212 224
 
213 225
    Returns TRUE if the argument is a valid IPv6 reference. FALSE
214 226
    otherwise.
... ...
@@ -219,14 +231,14 @@ if (is_ipv6("1080:0:0:0:8:800:200C:417A")) {
219 231
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
220 232
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
221 233
 
222
-   Example 1.5. is_ipv6_reference usage
234
+   Example 1.5.  is_ipv6_reference usage
223 235
 ...
224 236
 if (is_ipv6_reference("[1080:0:0:0:8:800:200C:417A]")) {
225 237
   xlog("L_INFO", "it's IPv6 reference\n");
226 238
 }
227 239
 ...
228 240
 
229
-4.6. ip_type (ip)
241
+4.6.  ip_type (ip)
230 242
 
231 243
    Returns the type of the given IP.
232 244
 
... ...
@@ -242,7 +254,7 @@ if (is_ipv6_reference("[1080:0:0:0:8:800:200C:417A]")) {
242 254
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
243 255
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
244 256
 
245
-   Example 1.6. ip_type usage
257
+   Example 1.6.  ip_type usage
246 258
 ...
247 259
 ip_type($var(myip));
248 260
 switch($rc) {
... ...
@@ -261,7 +273,93 @@ switch($rc) {
261 273
 }
262 274
 ...
263 275
 
264
-4.7. compare_ips (ip1, ip2)
276
+4.7.  detailed_ip_type (ip, result)
277
+
278
+   Returns the detailed type of the given IP () (see
279
+   http://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.t
280
+   xt,
281
+   http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-sp
282
+   ecial-registry.txt, RFC 5735 and RFC 6598: PRIVATE, SHARED, LOOPBACK,
283
+   IPV4MAP, DISCARD etc).
284
+
285
+   Parameters:
286
+     * ip - String or pseudo-variable containing the IP to evaluate.
287
+     * result - String or pseudo-variable containing the detailed type of
288
+       the IP.
289
+          + IPv4 - PUBLIC, RIVATE, SHARED, LOOPBACK, LINK-LOCAL, RESERVED,
290
+            TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST
291
+          + IPv6 - UNSPECIFIED, LOOPBACK, IPV4MAP, RESERVED, DISCARD,
292
+            GLOBAL-UNICAST, TEREDO, BMWG, DOCUMENTATION, ORCHID, 6TO4,
293
+            UNIQUE-LOCAL-UNICAST, LINK-LOCAL-UNICAST, MULTICAST
294
+
295
+   Return value:
296
+     * 1 - successful operation
297
+     * negative value - error occured
298
+
299
+   This function can be used from ALL ROUTES
300
+
301
+   Example 1.7.  detailed_ip_type usage
302
+...
303
+    detailed_ip_type("192.168.1.2","$var(result)");
304
+    xlog("L_ERR","IP address is of detailed type: $var(result) ");
305
+...
306
+
307
+4.8.  detailed_ipv4_type (ip, result)
308
+
309
+   Returns the detailed type of the given IP () (see RFC 5735 and RFC
310
+   6598).
311
+
312
+   Parameters:
313
+     * ip - String or pseudo-variable containing the IP to evaluate.
314
+     * result - String or pseudo-variable containing the detailed type of
315
+       the IP.
316
+          + IPv4 - PUBLIC, PRIVATE, SHARED, LOOPBACK, LINK-LOCAL,
317
+            RESERVED, TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST
318
+
319
+   Return value:
320
+     * 1 - successful operation
321
+     * negative value - error occured
322
+
323
+   This function can be used from ALL ROUTES
324
+
325
+   Example 1.8.  detailed_ipv4_type usage
326
+...
327
+    detailed_ipv4_type("192.168.1.2","$var(result)");
328
+    xlog("L_ERR","IP address is of detailed type: $var(result) ");
329
+...
330
+
331
+4.9.  detailed_ipv6_type (ip, result)
332
+
333
+   Returns the detailed type of the given IP () (see
334
+   http://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.t
335
+   xt,
336
+   http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-sp
337
+   ecial-registry.txt).
338
+
339
+   Parameters:
340
+     * ip - String or pseudo-variable containing the IP to evaluate.
341
+     * result - String or pseudo-variable containing the detailed type of
342
+       the IP.
343
+          + IPv6 - UNSPECIFIED, LOOPBACK, IPV4MAP, RESERVED, DISCARD,
344
+            GLOBAL-UNICAST, TEREDO, BMWG, DOCUMENTATION, ORCHID, 6TO4,
345
+            UNIQUE-LOCAL-UNICAST, LINK-LOCAL-UNICAST, MULTICAST
346
+
347
+   Return value:
348
+     * 1 - successful operation
349
+     * negative value - error occured
350
+
351
+   This function can be used from ALL ROUTES
352
+
353
+   Example 1.9.  detailed_ipv6_type usage
354
+...
355
+    detailed_ipv6_type("2001:8d8:7c0:402:217:72:194:30","$var(result)");
356
+    xlog("L_ERR","IP address is of detailed type: $var(result) ");
357
+
358
+    detailed_ipv6_type("[2001:8d8:7c0:402:217:72:194:30]","$var(result)");
359
+    xlog("L_ERR","IP address is of detailed type: $var(result) ");
360
+...
361
+
362
+4.10.  compare_ips (ip1, ip2)
265 363
 
266 364
    Returns TRUE if both IP addresses are the same. FALSE otherwise. This
267 365
    function also allows comparing an IPv6 address against an IPv6
... ...
@@ -275,7 +373,7 @@ switch($rc) {
275 373
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
276 374
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
277 375
 
278
-   Example 1.7. compare_ips usage
376
+   Example 1.10.  compare_ips usage
279 377
 ...
280 378
 if (compare_ips("1080:0000:0000:0000:0008:0800:200C:417A", "[1080::8:800:200C:41
281 379
 7A]")) {
... ...
@@ -283,7 +381,7 @@ if (compare_ips("1080:0000:0000:0000:0008:0800:200C:417A", "[1080::8:800:200C:41
283 381
 }
284 382
 ...
285 383
 
286
-4.8. compare_pure_ips (ip1, ip2)
384
+4.11.  compare_pure_ips (ip1, ip2)
287 385
 
288 386
    Returns TRUE if both IP's are the same. FALSE otherwise. This function
289 387
    does NOT allow comparing an IPv6 against an IPv6 reference.
... ...
@@ -297,14 +395,14 @@ if (compare_ips("1080:0000:0000:0000:0008:0800:200C:417A", "[1080::8:800:200C:41
297 395
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
298 396
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
299 397
 
300
-   Example 1.8. compare_pure_ips usage
398
+   Example 1.11.  compare_pure_ips usage
301 399
 ...
302 400
 if (compare_pure_ips($si, "1080::8:800:200C:417A")) {
303 401
   xlog("L_INFO", "both are the same IP\n");
304 402
 }
305 403
 ...
306 404
 
307
-4.9. is_ip_rfc1918 (ip)
405
+4.12.  is_ip_rfc1918 (ip)
308 406
 
309 407
    Returns TRUE if the argument is a private IPv4 according to RFC 1918.
310 408
    FALSE otherwise.
... ...
@@ -315,14 +413,14 @@ if (compare_pure_ips($si, "1080::8:800:200C:417A")) {
315 413
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
316 414
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
317 415
 
318
-   Example 1.9. is_ip_rfc1918 usage
416
+   Example 1.12.  is_ip_rfc1918 usage
319 417
 ...
320 418
 if (is_ip_rfc1918("10.0.123.123")) {
321 419
   xlog("L_INFO", "it's a private IPv4\n");
322 420
 }
323 421
 ...
324 422
 
325
-4.10. is_in_subnet (ip, subnet)
423
+4.13.  is_in_subnet (ip, subnet)
326 424
 
327 425
    Returns TRUE if the first argument is an IP address within the (CIDR
328 426
    notation) subnet in the second argument. FALSE otherwise.
... ...
@@ -335,14 +433,14 @@ if (is_ip_rfc1918("10.0.123.123")) {
335 433
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
336 434
    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
337 435
 
338
-   Example 1.10. is_in_subnet usage
436
+   Example 1.13.  is_in_subnet usage
339 437
 ...
340 438
 if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
341 439
   xlog("L_INFO", "it's in the subnet\n");
342 440
 }
343 441
 ...
344 442
 
345
-4.11. dns_sys_match_ip(hostname, ipaddr)
443
+4.14.  dns_sys_match_ip(hostname, ipaddr)
346 444
 
347 445
    Returns TRUE if ipaddr is associated by DNS to hostname. FALSE
348 446
    otherwise. It does not use the internal DNS resolver, but directly
... ...
@@ -358,14 +456,14 @@ if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
358 456
 
359 457
    This function can be used from ANY_ROUTE.
360 458
 
361
-   Example 1.11. dns_sys_match_ip usage
459
+   Example 1.14.  dns_sys_match_ip usage
362 460
 ...
363 461
 if (!dns_sys_match_ip("myhost.com", "1.2.3.4")) {
364 462
     xdbg("ip address not associated with hostname\n");
365 463
 }
366 464
 ...
367 465
 
368
-4.12. dns_int_match_ip(hostname, ipaddr)
466
+4.15.  dns_int_match_ip(hostname, ipaddr)
369 467
 
370 468
    Returns TRUE if ipaddr is associated by DNS to hostname. FALSE
371 469
    otherwise. It uses internal DNS resolver. At this moment, the function
... ...
@@ -382,14 +480,14 @@ if (!dns_sys_match_ip("myhost.com", "1.2.3.4")) {
382 480
 
383 481
    This function can be used from ANY_ROUTE.
384 482
 
385
-   Example 1.12. dns_int_match_ip usage
483
+   Example 1.15.  dns_int_match_ip usage
386 484
 ...
387 485
 if (!dns_int_match_ip("myhost.com", "1.2.3.4")) {
388 486
     xdbg("ip address not associated with hostname\n");
389 487
 }
390 488
 ...
391 489
 
392
-4.13. dns_query(hostname, pvid)
490
+4.16.  dns_query(hostname, pvid)
393 491
 
394 492
    Store the IP addresses and their type that correspond to hostname in a
395 493
    config variable $dns(pvid=>key).
... ...
@@ -401,7 +499,7 @@ if (!dns_int_match_ip("myhost.com", "1.2.3.4")) {
401 499
 
402 500
    This function can be used from ANY_ROUTE.
403 501
 
404
-   Example 1.13. dns_query usage
502
+   Example 1.16.  dns_query usage
405 503
 ...
406 504
 if(dns_query("test.com", "xyz"))
407 505
 {
... ...
@@ -383,7 +383,7 @@ switch($rc) {
383 383
           <para>
384 384
             <itemizedlist>
385 385
               <listitem>  
386
-		<emphasis> IPv4 </emphasis> - PRIVATE, SHARED, LOOPBACK, LINK-LOCAL, RESERVED, TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST     
386
+		<emphasis> IPv4 </emphasis> - PUBLIC, RIVATE, SHARED, LOOPBACK, LINK-LOCAL, RESERVED, TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST     
387 387
  	      </listitem>
388 388
 	      <listitem>  
389 389
 		<emphasis> IPv6 </emphasis> - UNSPECIFIED,  LOOPBACK, IPV4MAP, RESERVED, DISCARD, GLOBAL-UNICAST, TEREDO, BMWG, DOCUMENTATION, ORCHID, 6TO4, UNIQUE-LOCAL-UNICAST, LINK-LOCAL-UNICAST, MULTICAST     
... ...
@@ -450,7 +450,7 @@ switch($rc) {
450 450
           <para>
451 451
             <itemizedlist>
452 452
               <listitem>  
453
-		<emphasis> IPv4 </emphasis> - PRIVATE, SHARED, LOOPBACK, LINK-LOCAL, RESERVED, TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST     
453
+		<emphasis> IPv4 </emphasis> - PUBLIC, PRIVATE, SHARED, LOOPBACK, LINK-LOCAL, RESERVED, TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST     
454 454
  	      </listitem>	                 
455 455
   	    </itemizedlist>		
456 456
 	  </para>	
... ...
@@ -514,7 +514,7 @@ switch($rc) {
514 514
           <para>
515 515
             <itemizedlist>
516 516
               <listitem>  
517
-		<emphasis> IPv6 </emphasis> - PRIVATE, SHARED, LOOPBACK, LINK-LOCAL, RESERVED, TEST-NET, 6TO4-RELAY, MULTICAST, BROADCAST     
517
+		<emphasis> IPv6 </emphasis> - UNSPECIFIED,  LOOPBACK, IPV4MAP, RESERVED, DISCARD, GLOBAL-UNICAST, TEREDO, BMWG, DOCUMENTATION, ORCHID, 6TO4, UNIQUE-LOCAL-UNICAST, LINK-LOCAL-UNICAST, MULTICAST    
518 518
  	      </listitem>	                 
519 519
   	    </itemizedlist>		
520 520
 	  </para>