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