merge new_loader_completion branch, including (at least):
[asterisk/asterisk.git] / doc / enum.txt
1 Enum support in the ENUMLOOKUP dialplan function
2 ------------------------------------------------
3 2005-09-06 
4 jtodd@loligo.com
5
6 The ENUMLOOKUP function is more complex than it first may appear, and
7 this guide is to give a general overview and set of examples that may
8 be well-suited for the advanced user to evaluate in their
9 consideration of ENUM or ENUM-like lookup strategies.  This document
10 assumes a familiarity with ENUM (RFC3761) or ENUM-like methods, as
11 well as familiarity with NAPTR DNS records (RFC2915, RFC3401-3404).
12 For an overview of NAPTR records, and the use of NAPTRs in the ENUM
13 global phone-number-to-DNS mapping scheme, please see
14 http://www.voip-info.org/tiki-index.php?page=ENUM for more detail.
15
16 Using ENUM within Asterisk can be simple or complex, depending on how
17 many failover methods and redundancy procedures you wish to utilize.
18 Implementation of ENUM paths is supposedly defined by the person
19 creating the NAPTR records, but the local administrator may choose to
20 ignore certain NAPTR response methods (URI types) or prefer some over
21 others, which is in contradiction to the RFC.  The ENUMLOOKUP method
22 simply provides administrators a method for determining NAPTR results
23 in either the globally unique ENUM (e164.arpa) DNS tree, or in other
24 ENUM-like DNS trees which are not globally unique.  The methods to
25 actually create channels ("dial") results given by the ENUMLOOKUP
26 function is then up to the administrator to implement in a way that
27 best suits their environment.
28
29 Function: ENUMLOOKUP(number[|Method-type[|options[|record#[|zone-suffix]]]])
30
31   Performs an ENUM tree lookup on the specified number, method type, and
32   ordinal record offset, and returns one of four different values:
33
34    1) post-parsed NAPTR of one method (URI) type
35    2) count of elements of one method (URI) type
36    3) count of all method types
37    4) full URI of method at a particular point in the list of all possible methods 
38
39 Arguments:
40
41 number = telephone number or search string.  Only numeric values
42 within this string are parsed; all other digits are ignored for
43 search, but are re-written during NAPTR regexp expansion.
44
45 service_type = tel, sip, h323, iax2, mailto, ...[any other string],
46      ALL. Default type is "sip".
47      Special name of "ALL" will create a list of method types across
48      all NAPTR records for the search number, and then put the results
49      in an ordinal list starting with 1. The position <number>
50      specified will then be returned, starting with 1 as the first
51      record (lowest value) in the list.  The service types are not
52      hardcoded in Asterisk except for the default (sip) if no other
53      service type specified; any method type string (IANA-approved or
54      not) may be used except for the string "ALL".  
55
56 options = optional specifiers.
57     c = count. Returns the number of records of this type are returned
58     (regardless of order or priority.)  If "ALL" is the specified
59     service_type, then a count of all methods will be returned for the
60     DNS record.
61
62 record# = which record to present if multiple answers are returned
63     <integer> = The record in priority/order sequence based on the
64     total count of records passed back by the query. If a service_type
65     is specified, all entries of that type will be sorted into an
66     ordinal list starting with 1 (by order first, then priority).
67     The default of <options> is "1"
68  
69 zone_suffix = allows customization of the ENUM zone. Default is e164.arpa.
70
71
72 EXAMPLE USES:
73
74 Let's use this ENUM list as an example (note that these examples exist
75 in the DNS, and will hopefully remain in place as example
76 destinations, but they may change or become invalid over time.  The
77 end result URIs are not guaranteed to actually work, since some of
78 these hostnames or SIP proxies are imaginary.  Of course, the tel:
79 replies go to directory assistance for New York City and San
80 Francisco...)  Also note that the complex SIP NAPTR at weight 30 will
81 strip off the leading "+" from the dialed string if it exists.  This
82 is probably a better NAPTR than hard-coding the number into the NAPTR,
83 and it is included as a more complex regexp example, though other
84 simpler NAPTRs will work just as well.
85
86
87 0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 10 100 "u" "E2U+tel" "!^\\+13015611020$!tel:+12125551212!" .
88 0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 21 100 "u" "E2U+tel" "!^\\+13015611020$!tel:+14155551212!" .
89 0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 25 100 "u" "E2U+sip" "!^\\+13015611020$!sip:2203@sip.fox-den.com!" .
90 0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 26 100 "u" "E2U+sip" "!^\\+13015611020$!sip:1234@sip-2.fox-den.com!" .
91 0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 30 100 "u" "E2U+sip" "!^\\+*([^\\*]*)!sip:\\1@sip-3.fox-den.com!" .
92 0.2.0.1.1.6.5.1.0.3.1.loligo.com. 3600 IN NAPTR 55 100 "u" "E2U+mailto" "!^\\+13015611020$!mailto:jtodd@fox-den.com!" .
93
94 Example 1: Simplest case, using first SIP return (use all defaults
95 except for domain name)
96 exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,,,,loligo.com)})
97   returns: ${foo}="2203@sip.fox-den.com"
98
99 Example 2: What is the first "tel" pointer type for this number?
100 (after sorting by order/preference; default of "1" is assumed in
101 options field)
102 exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,,loligo.com)})
103   returns: ${foo}="+12125551212"
104
105 Example 3: How many "sip" pointer type entries are there for this number?
106 exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,sip,c,,loligo.com)})
107   returns: ${foo}=3
108
109 Example 4: For all the "tel" pointer type entries, what is the second
110 one in the list? (after sorting by preference)
111 exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,tel,,2,loligo.com)})
112   returns: ${foo}="+14155551212"
113
114 Example 5: How many NAPTRs (tel, sip, mailto, etc.) are in the list for this number?
115 exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,c,,loligo.com)})
116   returns: ${foo}=6
117
118 Example 6: Give back the second full URI in the sorted list of all NAPTR URIs:
119 exten => 100,1,Set(foo=${ENUMLOOKUP(+13015611020,ALL,,2,loligo.com)})
120   returns: ${foo}="tel:+14155551212"  [note the "tel:" prefix in the string]
121
122 Example 7: Look up first SIP entry for the number in the e164.arpa zone (all defaults)
123 exten => 100,1,Set(foo=${ENUMLOOKUP(+437203001721)})
124   returns: ${foo}="enum-test@sip.nemox.net"  [note: this result is
125   subject to change as it is "live" DNS and not under my control]
126
127
128 Example 8: Look up the ISN mapping in freenum.org alpha test zone
129 exten => 100,1,Set(foo=${ENUMLOOKUP(1234*256,,,,freenum.org)})
130   returns: ${foo}="1234@204.91.156.10"  [note: this result is subject
131   to change as it is "live" DNS]
132
133 Example 9: Give back the first SIP pointer for a number in the
134 enum.yoydynelabs.com zone (invalid lookup)
135 exten => 100,1,Set(foo=${ENUMLOOKUP(1234567890,sip,,1,enum.yoyodynelabs.com)})
136   returns: ${foo}=""
137
138
139 Usage notes and subtle features:
140
141   a) The use of "+" in lookups is confusing, and warrants further
142   explanation.  All E.164 numbers ("global phone numbers") by
143   definition need a leading "+" during ENUM lookup.  If you neglect to
144   add a leading "+", you may discover that numbers that seem to exist
145   in the DNS aren't getting matched by the system or are returned with
146   a null string result.  This is due to the NAPTR reply requiring a
147   "+" in the regular expression matching sequence.  Older versions of
148   Asterisk add a "+" from within the code, which may confuse
149   administrators converting to the new function.  Please ensure that
150   all ENUM (e164.arpa) lookups contain a leading "+" before lookup, so
151   ensure your lookup includes the leading plus sign.  Other DNS trees
152   may or may not require a leading "+" - check before using those
153   trees, as it is possible the parsed NAPTRs will not provide correct
154   results unless you have the correct dialed string.  If you get
155   console messages like "WARNING[24907]: enum.c:222 parse_naptr: NAPTR
156   Regex match failed." then it is very possible that the returned
157   NAPTR expects a leading "+" in the search string (or the returned
158   NAPTR is mis-formed.)
159
160   b) If a query is performed of type "c" ("count") and let's say you
161   get back 5 records and then some seconds later a query is made
162   against record 5 in the list, it may not be the case that the DNS
163   resolver has the same answers as it did a second or two ago - maybe
164   there are only 4 records in the list in the newest query.  The
165   resolver should be the canonical storage location for DNS records,
166   since that is the intent of ENUM.  However, some obscure future
167   cases may have wildly changing NAPTR records within several seconds.
168   This is a corner case, and probably only worth noting as a very rare
169   circumstance. (note: I do not object to Asterisk's dnsmgr method of
170   locally caching DNS replies, but this method needs to honor the TTL
171   given by the remote zone master.  Currently, the ENUMLOOKUP function
172   does not use the dnsmgr method of caching local DNS replies.)
173
174   c) If you want strict NAPTR value ordering, then it will be
175   necessary to use the "ALL" method to incrementally step through the
176   different returned NAPTR pointers.  You will need to use string
177   manipulation to strip off the returned method types, since the
178   results will look like "sip:12125551212" in the returned value.
179   This is a non-trivial task, though it is required in order to have
180   strict RFC compliance and to comply with the desires of the remote
181   party who is presenting NAPTRs in a particular order for a reason.
182
183   d) Default behavior for the function (even in event of an error) is
184   to move to the next priority, and the result is a null value.  Most
185   ENUM lookups are going to be failures, and it is the responsibility
186   of the dialplan administrator to manage error conditions within
187   their dialplan.  This is a change from the old app_enumlookup method
188   and it's arbitrary priority jumping based on result type or failure.
189
190   e) Anything other than digits will be ignored in lookup strings.
191   Example: a search string of "+4372030blah01721" will turn into
192   1.2.7.1.0.0.3.0.2.7.3.4.e164.arpa. for the lookup.  The NAPTR
193   parsing may cause unexpected results if there are strings inside
194   your NAPTR lookups.
195
196   f) If there exist multiple records with the same weight and order as
197   a result of your query, the function will RANDOMLY select a single
198   NAPTR from those equal results.
199
200   g) Currently, the function ignores the settings in enum.conf as the
201   search zone name is now specified within the function, and the H323
202   driver can be chosen by the user via the dialplan.  There were no
203   other values in this file, and so it becomes deprecated.
204
205   h) The function will digest and return NAPTRs which use older
206   (depricated) style, reversed method strings such as "sip+E2U"
207   instead of the more modern "E2U+sip"
208
209   i) There is no provision for multi-part methods at this time.  If
210   there are multiple NAPTRs with (as an example) a method of
211   "E2U+voice:sip" and then another NAPTR in the same DNS record with a
212   method of ""E2U+sip", the system will treat these both as method
213   "sip" and they will be separate records from the perspective of the
214   function.  Of course, if both records point to the same URI and have
215   equal priority/weight (as is often the case) then this will cause no
216   serious difficulty, but it bears mentioning.
217
218   j) ISN (ITAD Subscriber Number) usage:  If the search number is of
219   the form ABC*DEF (where ABC and DEF are at least one numeric digit)
220   then perform an ISN-style lookup where the lookup is manipulated to
221   C.B.A.DEF.domain.tld (all other settings and options apply.)  See
222   http://www.freenum.org/ for more details on ISN lookups.  In the
223   unlikely event you wish to avoid ISN re-writes, put an "n" as the
224   first digit of the search string - the "n" will be ignored for the search.
225
226
227 ==EXAMPLES==
228
229 All examples below except where noted use "e164.arpa" as the
230 referenced domain, which is the default domain name for ENUMLOOKUP.
231 All numbers are assumed to not have a leading "+" as dialed by the
232 inbound channel, so that character is added where necessary during
233 ENUMLOOKUP function calls.
234
235 ; example 1
236 ;
237 ; Assumes North American international dialing (011) prefix.
238 ; Look up the first SIP result and send the call there, otherwise
239 ;  send the call out a PRI.  This is the most simple possible
240 ;  ENUM example, but only uses the first SIP reply in the list of
241 ;  NAPTR(s). 
242 ;
243 exten => _011.,1,Set(enumresult=${ENUMLOOKUP(+${EXTEN:3})})
244 exten => _011.,n,Dial(SIP/${enumresult})
245 exten => _011.,n,Dial(Zap/g1/${EXTEN})
246
247 ; end example 1
248
249 ; example 2
250 ;
251 ; Assumes North American international dialing (011) prefix.
252 ; Check to see if there are multiple SIP NAPTRs returned by 
253 ;  the lookup, and dial each in order.  If none work (or none
254 ;  exist) then send the call out a PRI, group 1.
255 ;
256 exten => _011.,1,Set(sipcount=${ENUMLOOKUP(${EXTEN:3},sip,c)}|counter=0)
257 exten => _011.,n,While($["${counter}"<"${sipcount}"])
258 exten => _011.,n,Set(counter=$[${counter}+1])
259 exten => _011.,n,Dial(SIP/${ENUMLOOKUP(+${EXTEN:3},sip,,${counter})})
260 exten => _011.,n,EndWhile
261 exten => _011.,n,Dial(Zap/g1/${EXTEN})
262 ;
263 ; end example 2
264
265 ; example 3
266 ;
267 ; This example expects an ${EXTEN} that is an e.164 number (like
268 ;  14102241145 or 437203001721)
269 ; Search through e164.arpa and then also search through e164.org
270 ;  to see if there are any valid SIP or IAX termination capabilities.
271 ;  If none, send call out via Zap channel 1.
272 ;
273 ; Start first with e164.arpa zone...
274 ;
275 exten => _X.,1,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c)}|counter=0)
276 exten => _X.,2,GotoIf($["${counter}"<"${sipcount}"]?3:6)
277 exten => _X.,3,Set(counter=$[${counter}+1])
278 exten => _X.,4,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter})})
279 exten => _X.,5,GotoIf($["${counter}"<"${sipcount}"]?3:6)
280 ;
281 exten => _X.,6,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c)}|counter=0)
282 exten => _X.,7,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
283 exten => _X.,8,Set(counter=$[${counter}+1])
284 exten => _X.,9,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter})})
285 exten => _X.,10,GotoIf($["${counter}"<"${iaxcount}"]?8:11)
286 ;
287 exten => _X.,11,NoOp("No valid entries in e164.arpa for ${EXTEN} - checking in e164.org")
288 ;
289 ; ...then also try e164.org, and look for SIP and IAX NAPTRs...
290 ;
291 exten => _X.,12,Set(sipcount=${ENUMLOOKUP(+${EXTEN},sip,c,,e164.org)}|counter=0)
292 exten => _X.,13,GotoIf($["${counter}"<"${sipcount}"]?14:17)
293 exten => _X.,14,Set(counter=$[${counter}+1])
294 exten => _X.,15,Dial(SIP/${ENUMLOOKUP(+${EXTEN},sip,,${counter},e164.org)})
295 exten => _X.,16,GotoIf($["${counter}"<"${sipcount}"]?14:17)
296 ;
297 exten => _X.,17,Set(iaxcount=${ENUMLOOKUP(+${EXTEN},iax2,c,,e164.org)}|counter=0)
298 exten => _X.,18,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
299 exten => _X.,19,Set(counter=$[${counter}+1])
300 exten => _X.,20,Dial(IAX2/${ENUMLOOKUP(+${EXTEN},iax2,,${counter},e164.org)})
301 exten => _X.,21,GotoIf($["${counter}"<"${iaxcount}"]?19:22)
302 ;
303 ; ...then send out PRI.
304 ;
305 exten => _X.,22,NoOp("No valid entries in e164.org for ${EXTEN} - sending out via Zap")
306 exten => _X.,23,Dial(Zap/g1/${EXTEN})
307 ;
308 ; end example 3