ipops: added dsn_int_match_ip(hostname, ipaddr)
[sip-router] / modules / ipops / README
1 ipops Module
2
3 Iñaki Baz Castillo
4
5    <ibc@aliax.net>
6
7 Edited by
8
9 Iñaki Baz Castillo
10
11    <ibc@aliax.net>
12
13    Copyright © 2011 Iñaki Baz Castillo
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Dependencies
22
23               2.1. SIP Router Modules
24               2.2. External Libraries or Applications
25
26         3. Parameters
27         4. Functions
28
29               4.1. is_ip (ip)
30               4.2. is_pure_ip (ip)
31               4.3. is_ipv4 (ip)
32               4.4. is_ipv6 (ip)
33               4.5. is_ipv6_reference (ip)
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
42    List of Examples
43
44    1.1. is_ip usage
45    1.2. is_pure_ip usage
46    1.3. is_ipv4 usage
47    1.4. is_ipv6 usage
48    1.5. is_ipv6_reference usage
49    1.6. ip_type usage
50    1.7. compare_ips usage
51    1.8. compare_pure_ips usage
52    1.9. is_ip_rfc1918 usage
53    1.10. is_in_subnet usage
54    1.11. dns_sys_match_ip usage
55    1.12. dns_int_match_ip usage
56
57 Chapter 1. Admin Guide
58
59    Table of Contents
60
61    1. Overview
62    2. Dependencies
63
64         2.1. SIP Router Modules
65         2.2. External Libraries or Applications
66
67    3. Parameters
68    4. Functions
69
70         4.1. is_ip (ip)
71         4.2. is_pure_ip (ip)
72         4.3. is_ipv4 (ip)
73         4.4. is_ipv6 (ip)
74         4.5. is_ipv6_reference (ip)
75         4.6. ip_type (ip)
76         4.7. compare_ips (ip1, ip2)
77         4.8. compare_pure_ips (ip1, ip2)
78         4.9. is_ip_rfc1918 (ip)
79         4.10. is_in_subnet (ip, subnet)
80         4.11. dns_sys_match_ip(hostname, ipaddr)
81         4.12. dns_int_match_ip(hostname, ipaddr)
82
83 1. Overview
84
85    The IPops module offers operations for handling IP addresses, both IPv4
86    and IPv6.
87
88    IPv6 is defined in RFC 2460. The same IPv6 address can be represented
89    by different ASCII strings, so binary comparison is required. For
90    example, the following IPv6 addresses are equivalent:
91      * 2001:DB8:0000:0000:0008:0800:200C:417A
92      * 2001:DB8:0:0:8:800:200C:417A
93      * 2001:DB8::200C:417A
94
95    When using IPv6 in an URI (i.e. a SIP URI) the IP address must be
96    written in "IPv6 reference" format (which is the textual representation
97    of the IPv6 enclosed between [ ] symbols). An example is
98    "sip:alice@[2001:DB8:0:0:8:800:200C:417A]". This allows separation of
99    address and port number with a :, like
100    "[2001:DB8:0:0:8:800:200C:417A]:5060". This module also allows
101    comparing an IPv6 address with its IPv6 reference representation.
102
103 2. Dependencies
104
105    2.1. SIP Router Modules
106    2.2. External Libraries or Applications
107
108 2.1. SIP Router Modules
109
110    The following modules must be loaded before this module:
111      * No dependencies on other SIP Router modules
112
113 2.2. External Libraries or Applications
114
115    The following libraries or applications must be installed before
116    running SIP Router with this module loaded:
117      * No dependencies on external libraries
118
119 3. Parameters
120
121 4. Functions
122
123    4.1. is_ip (ip)
124    4.2. is_pure_ip (ip)
125    4.3. is_ipv4 (ip)
126    4.4. is_ipv6 (ip)
127    4.5. is_ipv6_reference (ip)
128    4.6. ip_type (ip)
129    4.7. compare_ips (ip1, ip2)
130    4.8. compare_pure_ips (ip1, ip2)
131    4.9. is_ip_rfc1918 (ip)
132    4.10. is_in_subnet (ip, subnet)
133    4.11. dns_sys_match_ip(hostname, ipaddr)
134    4.12. dns_int_match_ip(hostname, ipaddr)
135
136 4.1. is_ip (ip)
137
138    Returns TRUE if the argument is a valid IPv4, IPv6 or IPv6 reference.
139    FALSE otherwise.
140
141    Parameters:
142      * ip - String or pseudo-variable containing the IP address to
143        evaluate.
144
145    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
146    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
147
148    Example 1.1. is_ip usage
149 ...
150 if (is_ip($rd)) {
151   xlog("L_INFO", "RURI domain is an IP address (not a host name/domain)\n");
152 }
153 ...
154
155 4.2. is_pure_ip (ip)
156
157    Returns TRUE if the argument is a valid IPv4 or IPv6. FALSE otherwise.
158
159    Parameters:
160      * ip - String or pseudo-variable containing the IP to evaluate.
161
162    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
163    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
164
165    Example 1.2. is_pure_ip usage
166 ...
167 $var(ip) = "::1";
168 if (is_pure_ip($var(ip))) {
169   xlog("L_INFO", "it's IPv4 or IPv6\n");
170 }
171 ...
172
173 4.3. is_ipv4 (ip)
174
175    Returns TRUE if the argument is a valid IPv4. FALSE otherwise.
176
177    Parameters:
178      * ip - String or pseudo-variable containing the IP to evaluate.
179
180    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
181    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
182
183    Example 1.3. is_ipv4 usage
184 ...
185 if (is_ipv4("1.2.3.4")) {
186   xlog("L_INFO", "it's IPv4\n");
187 }
188 ...
189
190 4.4. is_ipv6 (ip)
191
192    Returns TRUE if the argument is a valid IPv6. FALSE otherwise.
193
194    Parameters:
195      * ip - String or pseudo-variable containing the IP to evaluate.
196
197    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
198    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
199
200    Example 1.4. is_ipv6 usage
201 ...
202 if (is_ipv6("1080:0:0:0:8:800:200C:417A")) {
203   xlog("L_INFO", "it's IPv6\n");
204 }
205 ...
206
207 4.5. is_ipv6_reference (ip)
208
209    Returns TRUE if the argument is a valid IPv6 reference. FALSE
210    otherwise.
211
212    Parameters:
213      * ip - String or pseudo-variable containing the IP to evaluate.
214
215    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
216    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
217
218    Example 1.5. is_ipv6_reference usage
219 ...
220 if (is_ipv6_reference("[1080:0:0:0:8:800:200C:417A]")) {
221   xlog("L_INFO", "it's IPv6 reference\n");
222 }
223 ...
224
225 4.6. ip_type (ip)
226
227    Returns the type of the given IP.
228
229    Parameters:
230      * ip - String or pseudo-variable containing the IP to evaluate.
231
232    Return value:
233      * 1 - IPv4
234      * 2 - IPv6
235      * 3 - IPv6 reference
236      * -1 - invalid IP
237
238    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
239    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
240
241    Example 1.6. ip_type usage
242 ...
243 ip_type($var(myip));
244 switch($rc) {
245   case 1:
246     xlog("L_INFO", "it's IPv4\n");
247     break;
248   case 2:
249     xlog("L_INFO", "it's IPv6\n");
250     break;
251   case 3:
252     xlog("L_INFO", "it's IPv6 reference\n");
253     break;
254   case -1:
255     xlog("L_INFO", it's type invalid\n");
256     break;
257 }
258 ...
259
260 4.7. compare_ips (ip1, ip2)
261
262    Returns TRUE if both IP addresses are the same. FALSE otherwise. This
263    function also allows comparing an IPv6 address against an IPv6
264    reference.
265
266    Parameters:
267      * ip1 - String or pseudo-variable containing the first IP to compare.
268      * ip2 - String or pseudo-variable containing the second IP to
269        compare.
270
271    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
272    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
273
274    Example 1.7. compare_ips usage
275 ...
276 if (compare_ips("1080:0000:0000:0000:0008:0800:200C:417A", "[1080::8:800:200C:41
277 7A]")) {
278   xlog("L_INFO", "both are the same IP\n");
279 }
280 ...
281
282 4.8. compare_pure_ips (ip1, ip2)
283
284    Returns TRUE if both IP's are the same. FALSE otherwise. This function
285    does NOT allow comparing an IPv6 against an IPv6 reference.
286
287    Parameters:
288      * ip1 - String or pseudo-variable containing the first IP address to
289        compare.
290      * ip2 - String or pseudo-variable containing the second IP address to
291        compare.
292
293    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
294    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
295
296    Example 1.8. compare_pure_ips usage
297 ...
298 if (compare_pure_ips($si, "1080::8:800:200C:417A")) {
299   xlog("L_INFO", "both are the same IP\n");
300 }
301 ...
302
303 4.9. is_ip_rfc1918 (ip)
304
305    Returns TRUE if the argument is a private IPv4 according to RFC 1918.
306    FALSE otherwise.
307
308    Parameters:
309      * ip - String or pseudo-variable containing the IP to evaluate.
310
311    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
312    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
313
314    Example 1.9. is_ip_rfc1918 usage
315 ...
316 if (is_ip_rfc1918("10.0.123.123")) {
317   xlog("L_INFO", "it's a private IPv4\n");
318 }
319 ...
320
321 4.10. is_in_subnet (ip, subnet)
322
323    Returns TRUE if the first argument is an IP address within the (CIDR
324    notation) subnet in the second argument. FALSE otherwise.
325
326    Parameters:
327      * ip - string or pseudo-variable containing the ip to evaluate.
328      * subnet - string or pseudo-variable containing the (CIDR notation)
329        subnet to evaluate.
330
331    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
332    ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
333
334    Example 1.10. is_in_subnet usage
335 ...
336 if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
337   xlog("L_INFO", "it's in the subnet\n");
338 }
339 ...
340
341 4.11. dns_sys_match_ip(hostname, ipaddr)
342
343    Returns TRUE if ipaddr is associated by DNS to hostname. FALSE
344    otherwise. It does not use the internal DNS resolver, but directly
345    getaddrinfo(...). All addresses returned for the hostname are checked.
346    Note that some hosts may return different lists of IP addresses for
347    each query, if the DNS server is configured in that way (e.g., for
348    providing load balancing through DNS).
349
350    Parameters:
351      * ipaddr - string or pseudo-variable containing the ip address.
352      * hostname - string or pseudo-variable containing the hostname. The
353        resulting IP addresses from DNS query are compared with ipaddr.
354
355    This function can be used from ANY_ROUTE.
356
357    Example 1.11. dns_sys_match_ip usage
358 ...
359 if (!dns_sys_match_ip("myhost.com", "1.2.3.4")) {
360     xdbg("ip address not associated with hostname\n");
361 }
362 ...
363
364 4.12. dns_int_match_ip(hostname, ipaddr)
365
366    Returns TRUE if ipaddr is associated by DNS to hostname. FALSE
367    otherwise. It uses internal DNS resolver. At this moment, the function
368    might not check all the IP addresses as returned by dns_sys_match_ip(),
369    because the internal resolver targets to discover the first address to
370    be used for relaying SIP traffic. Thus is better to use
371    dns_sys_match_ip() if the host you want to check has many IP addresses,
372    in different address famililies (IPv4/6).
373
374    Parameters:
375      * ipaddr - string or pseudo-variable containing the ip address.
376      * hostname - string or pseudo-variable containing the hostname. The
377        resulting IP addresses from DNS query are compared with ipaddr.
378
379    This function can be used from ANY_ROUTE.
380
381    Example 1.12. dns_int_match_ip usage
382 ...
383 if (!dns_int_match_ip("myhost.com", "1.2.3.4")) {
384     xdbg("ip address not associated with hostname\n");
385 }
386 ...