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   (deprecated) 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