1 <!-- Enum Module User's Guide --> |
|
2 |
|
3 <chapter> |
|
4 |
|
5 <title>&adminguide;</title> |
|
6 |
|
7 <section id="sec-overview"> |
|
8 <title>Overview</title> |
|
9 <para> |
|
10 Enum module implements [i_]enum_query functions that make an enum query |
|
11 based on the user part of the current Request-URI. These functions |
|
12 assume that the user part consists of an international phone number |
|
13 of the form +decimal-digits, where the number of digits is at |
|
14 least 2 and at most 15. Out of this number |
|
15 <function moreinfo="none">enum_query</function> forms a domain name, |
|
16 where the digits are in reverse order and separated by dots followed by |
|
17 domain suffix that by default is <quote>e164.arpa.</quote>. For example, |
|
18 if the user part is +35831234567, the domain |
|
19 name will be <quote>7.6.5.4.3.2.1.3.8.5.3.e164.arpa.</quote>. |
|
20 <function moreinfo="none">i_enum_query</function> operates in a similar |
|
21 fashion. The only difference is that it adds a label (default "i") |
|
22 to branch off from the default, user-ENUM tree to an infrastructure ENUM tree. |
|
23 </para> |
|
24 <para> |
|
25 After forming the domain name, |
|
26 <function moreinfo="none">enum_query</function> queries |
|
27 DNS for its NAPTR records. From the possible response |
|
28 <function moreinfo="none">enum_query</function> chooses those records, |
|
29 whose flags field has string value "u", and whose services field has |
|
30 string value "e2u+[service:]sip" or |
|
31 "e2u+type[:subtype][+type[:subtype]...]" (case is ignored in both |
|
32 cases), and whose regexp field is of the form !pattern!replacement!. |
|
33 </para> |
|
34 <para> |
|
35 Then <function moreinfo="none">enum_query</function> sorts the chosen |
|
36 NAPTR records based on their <order, preference>. After sorting, |
|
37 <function moreinfo="none">enum_query</function> replaces the current |
|
38 Request URI by applying regexp of the most preferred NAPTR record its |
|
39 user part and appends to the request new branches by applying regexp of |
|
40 each remaining NAPTR record to the user part of the |
|
41 current Request URI. If a new URI is a tel URI, |
|
42 <function moreinfo="none">enum_query</function> appends to it as tel |
|
43 URI parameters the value of tel_uri_params module parameter. Finally, |
|
44 <function moreinfo="none">enum_query</function> associates a q value |
|
45 with each new URI based on the <order, preference> of the |
|
46 corresponding NAPTR record. |
|
47 </para> |
|
48 <para> |
|
49 When using <function moreinfo="none">enum_query</function> without any |
|
50 parameters, it searches for NAPTRs with service type "e2u+sip" in the |
|
51 default enum tree. When using |
|
52 <function moreinfo="none">enum_query</function> with a single parameter, |
|
53 this parameter will be used as enum tree. When using |
|
54 <function moreinfo="none">enum_query</function> |
|
55 with two parameters, the functionality depends on the first letter in |
|
56 the second parameter. When the first letter is not a '+' sign, the |
|
57 second parameter will be used to search for NAPTRs with service type |
|
58 "e2u+parameter:sip". When the second parameter starts with a '+' sign, |
|
59 the ENUM lookup also supports compound NAPTRs |
|
60 (e.g. "e2u+voice:sip+video:sip") and searching for multiple service |
|
61 types within one lookup. Multiple service types must be separeted |
|
62 by a '+' sign. |
|
63 </para> |
|
64 <para> |
|
65 Most of the time you want to route based on the RURI. On rare occasions |
|
66 you may wish to route based on something else. The function |
|
67 <function moreinfo="none">enum_pv_query</function> mimics the behavior |
|
68 of the <function moreinfo="none">enum_query</function> function except the |
|
69 E.164 number in its pseudo variable argument is used for the enum lookup instead of the user |
|
70 part of the RURI. Obviously the user part of the RURI is still used in the |
|
71 NAPTR regexp. |
|
72 </para> |
|
73 <para> |
|
74 Enum query returns 1 if the current Request URI was replaced |
|
75 and -1 if not. |
|
76 </para> |
|
77 <para> |
|
78 In addition to standard ENUM, support for ISN (ITAD Subscriber |
|
79 Numbers) is provided as well. To allow ISN lookups to resolve, |
|
80 a different formatting algorithm is expected by the DNS server. |
|
81 Whereas a ENUM NAPTR record expects a DNS query of the form |
|
82 9.8.7.6.5.4.3.2.1.<suffix>, ISN method expects a DNS query of |
|
83 the form 6.5.1212.<suffix>. That is, a valid ISN number includes |
|
84 a prefix of '56' in the example. The rest of the number is a |
|
85 ITAD (Internet Telephony Administrative Domain) as defined |
|
86 in RFCs 3872 and 2871, and as allocated by the IANA in |
|
87 http://www.iana.org/assignments/trip-parameters. The ITAD is |
|
88 left intact and not refersed as ENUM requires. To learn more |
|
89 about ISN please refer to documents at www.freenum.org. |
|
90 </para> |
|
91 <para> |
|
92 To complete a ISN lookup on the user part of the Request-URI, |
|
93 isn_query() is used instead of enum_query(). |
|
94 </para> |
|
95 <para> |
|
96 Enum module also implements is_from_user_enum function. |
|
97 This function does an enum lookup on the from user and |
|
98 returns true if found, false otherwise. |
|
99 </para> |
|
100 </section> |
|
101 |
|
102 <section> |
|
103 <title>Dependencies</title> |
|
104 <para> |
|
105 The module depends on the following modules (in the other words the |
|
106 listed modules must be loaded before this module): |
|
107 <itemizedlist> |
|
108 <listitem> |
|
109 <para>No dependencies.</para> |
|
110 </listitem> |
|
111 </itemizedlist> |
|
112 </para> |
|
113 </section> |
|
114 |
|
115 <section> |
|
116 <title>Exported Parameters</title> |
|
117 <section> |
|
118 <title><varname>domain_suffix</varname> (string)</title> |
|
119 <para> |
|
120 The domain suffix to be added to the domain name obtained from |
|
121 the digits of an <acronym>E164</acronym> number. Can be overridden |
|
122 by a parameter to enum_query. |
|
123 </para> |
|
124 <para> |
|
125 Default value is <quote>e164.arpa.</quote> |
|
126 </para> |
|
127 <example> |
|
128 <title>Setting domain_suffix module parameter</title> |
|
129 <programlisting format="linespecific"> |
|
130 modparam("enum", "domain_suffix", "e1234.arpa.") |
|
131 </programlisting> |
|
132 </example> |
|
133 </section> |
|
134 |
|
135 <section> |
|
136 <title><varname>tel_uri_params</varname> (string)</title> |
|
137 <para> |
|
138 A string whose contents is appended to each new tel URI in the |
|
139 request as tel URI parameters. |
|
140 </para> |
|
141 <note> |
|
142 <para> |
|
143 Currently &osips; does not support tel URIs. This means that at present |
|
144 tel_uri_params is appended as URI parameters to every URI. |
|
145 </para> |
|
146 </note> |
|
147 <para> |
|
148 Default value is <quote></quote> |
|
149 </para> |
|
150 <example> |
|
151 <title>Setting tel_uri_params module parameter</title> |
|
152 <programlisting format="linespecific"> |
|
153 modparam("enum", "tel_uri_params", ";npdi") |
|
154 </programlisting> |
|
155 </example> |
|
156 </section> |
|
157 <section> |
|
158 <title><varname>i_enum_suffix</varname> (string)</title> |
|
159 <para> |
|
160 The domain suffix to be used for i_enum_query() lookups. |
|
161 Can be overridden by a parameter to i_enum_query. |
|
162 </para> |
|
163 <para> |
|
164 Default value is <quote>e164.arpa.</quote> |
|
165 </para> |
|
166 <example> |
|
167 <title>Setting i_enum_suffix module parameter</title> |
|
168 <programlisting format="linespecific"> |
|
169 modparam("enum", "i_enum_suffix", "e1234.arpa.") |
|
170 </programlisting> |
|
171 </example> |
|
172 </section> |
|
173 <section> |
|
174 <title><varname>isn_suffix</varname> (string)</title> |
|
175 <para> |
|
176 The domain suffix to be used for isn_query() lookups. Can |
|
177 be overridden by a parameter to isn_query. |
|
178 </para> |
|
179 <para> |
|
180 Default value is <quote>freenum.org.</quote> |
|
181 </para> |
|
182 <example> |
|
183 <title>Setting isn_suffix module parameter</title> |
|
184 <programlisting format="linespecific"> |
|
185 modparam("enum", "isn_suffix", "freenum.org.") |
|
186 </programlisting> |
|
187 </example> |
|
188 </section> |
|
189 <section> |
|
190 <title><varname>branchlabel</varname> (string)</title> |
|
191 <para> |
|
192 This parameter determines which label i_enum_query() will use |
|
193 to branch off to the infrastructure ENUM tree. |
|
194 </para> |
|
195 <para> |
|
196 Default value is <quote>"i"</quote> |
|
197 </para> |
|
198 <example> |
|
199 <title>Setting branchlabel module parameter</title> |
|
200 <programlisting format="linespecific"> |
|
201 modparam("enum", "branchlabel", "i") |
|
202 </programlisting> |
|
203 </example> |
|
204 </section> |
|
205 <section> |
|
206 <title><varname>bl_algorithm</varname> (string)</title> |
|
207 <para> |
|
208 This parameter determines which algorithm i_enum_query() will use |
|
209 to select the position in the DNS tree where the infrastructure tree |
|
210 branches off the user ENUM tree. |
|
211 </para> |
|
212 <para> |
|
213 If set to "cc", i_enum_query() will always inserts the |
|
214 label at the country-code level. |
|
215 Examples: i.1.e164.arpa, i.3.4.e164.arpa, i.2.5.3.e164.arpa |
|
216 </para> |
|
217 <para> |
|
218 If set to "txt", i_enum_query() will look for a TXT record at |
|
219 [branchlabel].[reverse-country-code].[i_enum_suffix] to indicate after how many digits the |
|
220 label should in inserted. |
|
221 <example> |
|
222 <title>Zone file example</title> |
|
223 <programlisting format="linespecific"> |
|
224 i.1.e164.arpa. IN TXT "4" |
|
225 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5678 999" |
|
226 </programlisting> |
|
227 </example> |
|
228 </para> |
|
229 <para> |
|
230 If set to "ebl", i_enum_query() will look for an EBL (ENUM Branch Label) record at |
|
231 [branchlabel].[reverse-country-code].[i_enum_suffix]. See http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-location-record-00.txt for a description of that record and the |
|
232 meaning of the fields. The RR type for the EBL has not been allocated yet. |
|
233 This version of the code uses 65300. See resolve.h. |
|
234 <example> |
|
235 <title>Zone file example</title> |
|
236 <programlisting format="linespecific"> |
|
237 i.1.e164.arpa. TYPE65300 \# 14 ( |
|
238 04 ; position |
|
239 01 69 ; separator |
|
240 04 65 31 36 34 04 61 72 70 61 00 ; e164.arpa |
|
241 ; ) |
|
242 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5678 999" |
|
243 </programlisting> |
|
244 </example> |
|
245 </para> |
|
246 |
|
247 <para> |
|
248 Default value is <quote>cc</quote> |
|
249 </para> |
|
250 <example> |
|
251 <title>Setting the bl_algorithm module parameter</title> |
|
252 <programlisting format="linespecific"> |
|
253 modparam("enum", "bl_algorithm", "txt") |
|
254 </programlisting> |
|
255 </example> |
|
256 </section> |
|
257 |
|
258 </section> |
|
259 |
|
260 <section> |
|
261 <title>Exported Functions</title> |
|
262 <section> |
|
263 <title> |
|
264 <function moreinfo="none">enum_query(["suffix"[,"service"]])</function> |
|
265 </title> |
|
266 <para> |
|
267 The function performs an enum query and rewrites the Request-URI with |
|
268 the result of the query. See <xref linkend="sec-overview"/> for more |
|
269 information. |
|
270 </para> |
|
271 <para>Meaning of the parameters is as follows:</para> |
|
272 <itemizedlist> |
|
273 <listitem> |
|
274 <para><emphasis>suffix</emphasis> - Suffix to be appended to the |
|
275 domain name. |
|
276 </para> |
|
277 </listitem> |
|
278 <listitem> |
|
279 <para><emphasis>service</emphasis> - Service string to be used in |
|
280 the service field. |
|
281 </para> |
|
282 </listitem> |
|
283 </itemizedlist> |
|
284 <para> |
|
285 This function can be used from REQUEST_ROUTE. |
|
286 </para> |
|
287 <example> |
|
288 <title><function moreinfo="none">enum_query</function> usage</title> |
|
289 <programlisting format="linespecific"> |
|
290 ... |
|
291 # search for "e2u+sip" in freenum.org |
|
292 enum_query("freenum.org."); |
|
293 ... |
|
294 # search for "e2u+sip" in default tree (configured as parameter) |
|
295 enum_query(); |
|
296 ... |
|
297 # search for "e2u+voice:sip" in e164.arpa |
|
298 enum_query("e164.arpa.","voice"); |
|
299 ... |
|
300 # search for service type "sip" or "voice:sip" or "video:sip" |
|
301 # note the '+' sign in front of the second parameter |
|
302 enum_query("e164.arpa.","+sip+voice:sip+video:sip"); |
|
303 ... |
|
304 # quering for service sip and voice:sip |
|
305 enum_query("e164.arpa."); |
|
306 enum_query("e164.arpa.","voice"); |
|
307 # or use instead |
|
308 enum_query("e164.arpa.","+sip+voice:sip"); |
|
309 ... |
|
310 </programlisting> |
|
311 </example> |
|
312 </section> |
|
313 |
|
314 <section> |
|
315 <title> |
|
316 <function moreinfo="none">enum_pv_query("pvar"[,"suffix"[,"service"]])</function> |
|
317 </title> |
|
318 <para> |
|
319 The function performs an enum query on E.164 number stored |
|
320 in its pseudo variable argument and rewrites the Request-URI with |
|
321 the result of the query. See <xref linkend="sec-overview"/> for more |
|
322 information. |
|
323 </para> |
|
324 <para>Meaning of the parameters is as follows:</para> |
|
325 <itemizedlist> |
|
326 <listitem> |
|
327 <para><emphasis>pvar</emphasis> - Pseudo |
|
328 variable that holds an E.164 number on which enum |
|
329 query is performed. |
|
330 </para> |
|
331 </listitem> |
|
332 <listitem> |
|
333 <para><emphasis>suffix</emphasis> - Suffix to be appended to the |
|
334 domain name. |
|
335 </para> |
|
336 </listitem> |
|
337 <listitem> |
|
338 <para><emphasis>service</emphasis> - Service string to be used in |
|
339 the service field. |
|
340 </para> |
|
341 </listitem> |
|
342 </itemizedlist> |
|
343 <para> |
|
344 This function can be used from REQUEST_ROUTE. |
|
345 </para> |
|
346 <example> |
|
347 <title><function moreinfo="none">enum_pv_query</function> usage</title> |
|
348 <programlisting format="linespecific"> |
|
349 ... |
|
350 # search for "e2u+sip" in freenum.org |
|
351 enum_pv_query("$avp(i:100)", "freenum.org."); |
|
352 ... |
|
353 # search for "e2u+sip" in default tree (configured as parameter) |
|
354 enum_pv_query("$fU"); |
|
355 ... |
|
356 # search for "e2u+voice:sip" in e164.arpa |
|
357 enum_pv_query("$avp(i:100)","e164.arpa.","voice"); |
|
358 ... |
|
359 # search for service type "sip" or "voice:sip" or "video:sip" |
|
360 # note the '+' sign in front of the second parameter |
|
361 enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip"); |
|
362 ... |
|
363 # quering for service sip and voice:sip |
|
364 enum_pv_query("$avp(i:100)","e164.arpa."); |
|
365 enum_pv_query("$avp(i:100)","e164.arpa.","voice"); |
|
366 # or use instead |
|
367 enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip"); |
|
368 ... |
|
369 </programlisting> |
|
370 </example> |
|
371 </section> |
|
372 |
|
373 <section> |
|
374 <title> |
|
375 <function moreinfo="none">i_enum_query(["suffix"[,"service"]])</function> |
|
376 </title> |
|
377 <para> |
|
378 The function performs an enum query and rewrites the Request-URI with |
|
379 the result of the query. This the Infrastructure-ENUM version of enum_query(). |
|
380 The only difference to enum_query() is in the calculation of the |
|
381 FQDN where NAPTR records are looked for. |
|
382 </para> |
|
383 <para> |
|
384 See ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberler-carrier-enum-01.txt |
|
385 for the rationale behind this function. |
|
386 </para> |
|
387 </section> |
|
388 |
|
389 <section> |
|
390 <title> |
|
391 <function moreinfo="none">isn_query(["suffix"[,"service"]])</function> |
|
392 </title> |
|
393 <para> |
|
394 The function performs a ISN query and rewrites the Request-URI with |
|
395 the result of the query. See <xref linkend="sec-overview"/> for more |
|
396 information. |
|
397 </para> |
|
398 <para>Meaning of the parameters is as follows:</para> |
|
399 <itemizedlist> |
|
400 <listitem> |
|
401 <para><emphasis>suffix</emphasis> - Suffix to be appended to the |
|
402 domain name. |
|
403 </para> |
|
404 </listitem> |
|
405 <listitem> |
|
406 <para><emphasis>service</emphasis> - Service string to be used in |
|
407 the service field. |
|
408 </para> |
|
409 </listitem> |
|
410 </itemizedlist> |
|
411 <para> |
|
412 This function can be used from REQUEST_ROUTE. |
|
413 </para> |
|
414 <para> |
|
415 See ftp://ftp.ietf.org/rfc/rfc3872.txt and |
|
416 ftp://ftp.ietf.org/rfc/rfc2871.txt for information |
|
417 regarding the ITAD part of the ISN string. |
|
418 </para> |
|
419 <example> |
|
420 <title><function moreinfo="none">isn_query</function> usage</title> |
|
421 <programlisting format="linespecific"> |
|
422 ... |
|
423 # search for "e2u+sip" in freenum.org |
|
424 isn_query("freenum.org."); |
|
425 ... |
|
426 # search for "e2u+sip" in default tree (configured as parameter) |
|
427 isn_query(); |
|
428 ... |
|
429 # search for "e2u+voice:sip" in freenum.org |
|
430 isn_query("freenum.org.","voice"); |
|
431 ... |
|
432 </programlisting> |
|
433 </example> |
|
434 </section> |
|
435 |
|
436 <section> |
|
437 <title><function moreinfo="none">is_from_user_enum()</function></title> |
|
438 <para> |
|
439 Checks if the user part of from <abbrev>URI</abbrev> |
|
440 is found in an enum lookup. |
|
441 Returns 1 if yes and -1 if not. |
|
442 </para> |
|
443 <para> |
|
444 This function can be used from REQUEST_ROUTE. |
|
445 </para> |
|
446 <example> |
|
447 <title><function moreinfo="none">is_from_user_enum</function> usage</title> |
|
448 <programlisting format="linespecific"> |
|
449 ... |
|
450 if (is_from_user_enum()) { |
|
451 .... |
|
452 }; |
|
453 ... |
|
454 </programlisting> |
|
455 </example> |
|
456 </section> |
|
457 </section> |
|
458 </chapter> |
|
459 |
|