Contributed Logic: opensips/modules/enum/README@7ae8da2fe7c8

     1 Enum Module

     3 Juha Heinanen

     5    <jh@song.fi>

     7 Otmar Lendl

     9    <lendl@nic.at>

    11    Copyright © 2002, 2003 Juha Heinanen

    12    Revision History

    13    Revision $Revision: 5907 $ $Date: 2010-01-18 10:45:05 +0100

    14                               (Mon, 18 Jan 2010) $

    15      __________________________________________________________

    17    Table of Contents

    19    1. Admin Guide

    21         1.1. Overview

    22         1.2. Dependencies

    23         1.3. Exported Parameters

    25               1.3.1. domain_suffix (string)

    26               1.3.2. tel_uri_params (string)

    27               1.3.3. i_enum_suffix (string)

    28               1.3.4. isn_suffix (string)

    29               1.3.5. branchlabel (string)

    30               1.3.6. bl_algorithm (string)

    32         1.4. Exported Functions

    34               1.4.1. enum_query(["suffix"[,"service"]])

    35               1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])

    36               1.4.3. i_enum_query(["suffix"[,"service"]])

    37               1.4.4. isn_query(["suffix"[,"service"]])

    38               1.4.5. is_from_user_enum()

    40    List of Examples

    42    1.1. Setting domain_suffix module parameter

    43    1.2. Setting tel_uri_params module parameter

    44    1.3. Setting i_enum_suffix module parameter

    45    1.4. Setting isn_query usage module parameter

    46    1.5. Setting branchlabel module parameter

    47    1.6. Zone file example

    48    1.7. Zone file example

    49    1.8. Setting the bl_algorithm module parameter

    50    1.9. enum_query usage

    51    1.10. enum_pv_query usage

    52    1.11. isn_query usage

    53    1.12. is_from_user_enum usage

    55 Chapter 1. Admin Guide

    57 1.1. Overview

    59    Enum module implements [i_]enum_query functions that make an

    60    enum query based on the user part of the current Request-URI.

    61    These functions assume that the user part consists of an

    62    international phone number of the form +decimal-digits, where

    63    the number of digits is at least 2 and at most 15. Out of this

    64    number enum_query forms a domain name, where the digits are in

    65    reverse order and separated by dots followed by domain suffix

    66    that by default is "e164.arpa.". For example, if the user part

    67    is +35831234567, the domain name will be

    68    "7.6.5.4.3.2.1.3.8.5.3.e164.arpa.". i_enum_query operates in a

    69    similar fashion. The only difference is that it adds a label

    70    (default "i") to branch off from the default, user-ENUM tree to

    71    an infrastructure ENUM tree.

    73    After forming the domain name, enum_query queries DNS for its

    74    NAPTR records. From the possible response enum_query chooses

    75    those records, whose flags field has string value "u", and

    76    whose services field has string value "e2u+[service:]sip" or

    77    "e2u+type[:subtype][+type[:subtype]...]" (case is ignored in

    78    both cases), and whose regexp field is of the form

    79    !pattern!replacement!.

    81    Then enum_query sorts the chosen NAPTR records based on their

    82    <order, preference>. After sorting, enum_query replaces the

    83    current Request URI by applying regexp of the most preferred

    84    NAPTR record its user part and appends to the request new

    85    branches by applying regexp of each remaining NAPTR record to

    86    the user part of the current Request URI. If a new URI is a tel

    87    URI, enum_query appends to it as tel URI parameters the value

    88    of tel_uri_params module parameter. Finally, enum_query

    89    associates a q value with each new URI based on the <order,

    90    preference> of the corresponding NAPTR record.

    92    When using enum_query without any parameters, it searches for

    93    NAPTRs with service type "e2u+sip" in the default enum tree.

    94    When using enum_query with a single parameter, this parameter

    95    will be used as enum tree. When using enum_query with two

    96    parameters, the functionality depends on the first letter in

    97    the second parameter. When the first letter is not a '+' sign,

    98    the second parameter will be used to search for NAPTRs with

    99    service type "e2u+parameter:sip". When the second parameter

   100    starts with a '+' sign, the ENUM lookup also supports compound

   101    NAPTRs (e.g. "e2u+voice:sip+video:sip") and searching for

   102    multiple service types within one lookup. Multiple service

   103    types must be separeted by a '+' sign.

   105    Most of the time you want to route based on the RURI. On rare

   106    occasions you may wish to route based on something else. The

   107    function enum_pv_query mimics the behavior of the enum_query

   108    function except the E.164 number in its pseudo variable

   109    argument is used for the enum lookup instead of the user part

   110    of the RURI. Obviously the user part of the RURI is still used

   111    in the NAPTR regexp.

   113    Enum query returns 1 if the current Request URI was replaced

   114    and -1 if not.

   116    Enum module also implements is_from_user_enum function. This

   117    function does an enum lookup on the from user and returns true

   118    if found, false otherwise.

   120    In addition to standard ENUM, support for ISN (ITAD Subscriber

   121    Numbers) is provided as well. To allow ISN lookups to resolve,

   122    a different formatting algorithm is expected by the DNS server.

   123    Whereas a ENUM NAPTR record expects a DNS query of the form

   124    9.8.7.6.5.4.3.2.1.<suffix>, ISN method expects a DNS query of

   125    the form 6.5.1212.<suffix>. That is, a valid ISN number includes

   126    a prefix of '56' in the example. The rest of the number is a

   127    ITAD (Internet Telephony Administrative Domain) as defined

   128    in RFCs 3872 and 2871, and as allocated by the IANA in

   129    http://www.iana.org/assignments/trip-parameters. The ITAD is

   130    left intact and not refersed as ENUM requires. To learn more

   131    about ISN please refer to documents at www.freenum.org.

   133    To complete a ISN lookup on the user part of the Request-URI,

   134    isn_query() is used instead of enum_query().

   136 1.2. Dependencies

   138    The module depends on the following modules (in the other words

   139    the listed modules must be loaded before this module):

   140      * No dependencies.

   142 1.3. Exported Parameters

   144 1.3.1. domain_suffix (string)

   146    The domain suffix to be added to the domain name obtained from

   147    the digits of an E164 number. Can be overridden by a parameter

   148    to enum_query.

   150    Default value is "e164.arpa."

   152    Example 1.1. Setting domain_suffix module parameter

   153 modparam("enum", "domain_suffix", "e1234.arpa.")

   155 1.3.2. tel_uri_params (string)

   157    A string whose contents is appended to each new tel URI in the

   158    request as tel URI parameters.

   160 Note

   162    Currently OpenSIPS does not support tel URIs. This means that

   163    at present tel_uri_params is appended as URI parameters to

   164    every URI.

   166    Default value is ""

   168    Example 1.2. Setting tel_uri_params module parameter

   169 modparam("enum", "tel_uri_params", ";npdi")

   171 1.3.3. i_enum_suffix (string)

   173    The domain suffix to be used for i_enum_query() lookups. Can be

   174    overridden by a parameter to i_enum_query.

   176    Default value is "e164.arpa."

   178    Example 1.3. Setting i_enum_suffix module parameter

   179 modparam("enum", "i_enum_suffix", "e1234.arpa.")

   181 1.3.4. isn_suffix (string)

   183    The domain suffix to be used for isn_query() lookups. Can be

   184    overridden by a parameter to isn_query.

   186    Default value is "freenum.org."

   188    Example 1.4. Setting isn_suffix module parameter

   189 modparam("enum", "isn_suffix", "freenum.org.")

   191 1.3.5. branchlabel (string)

   193    This parameter determines which label i_enum_query() will use

   194    to branch off to the infrastructure ENUM tree.

   196    Default value is ""i""

   198    Example 1.5. Setting branchlabel module parameter

   199 modparam("enum", "branchlabel", "i")

   201 1.3.6. bl_algorithm (string)

   203    This parameter determines which algorithm i_enum_query() will

   204    use to select the position in the DNS tree where the

   205    infrastructure tree branches off the user ENUM tree.

   207    If set to "cc", i_enum_query() will always inserts the label at

   208    the country-code level. Examples: i.1.e164.arpa,

   209    i.3.4.e164.arpa, i.2.5.3.e164.arpa

   211    If set to "txt", i_enum_query() will look for a TXT record at

   212    [branchlabel].[reverse-country-code].[i_enum_suffix] to

   213    indicate after how many digits the label should in inserted.

   215    Example 1.6. Zone file example

   216 i.1.e164.arpa.                     IN TXT   "4"

   217 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5

   218 678 999"

   220    If set to "ebl", i_enum_query() will look for an EBL (ENUM

   221    Branch Label) record at

   222    [branchlabel].[reverse-country-code].[i_enum_suffix]. See

   223    http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-loc

   224    ation-record-00.txt for a description of that record and the

   225    meaning of the fields. The RR type for the EBL has not been

   226    allocated yet. This version of the code uses 65300. See

   227    resolve.h.

   229    Example 1.7. Zone file example

   230 i.1.e164.arpa.     TYPE65300  \# 14 (

   231                               04    ; position

   232                               01 69 ; separator

   233                               04 65 31 36 34 04 61 72 70 61 00 ; e164.ar

   234 pa

   235 ;                               )

   236 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5

   237 678 999"

   239    Default value is "cc"

   241    Example 1.8. Setting the bl_algorithm module parameter

   242 modparam("enum", "bl_algorithm", "txt")

   244 1.4. Exported Functions

   246 1.4.1.  enum_query(["suffix"[,"service"]])

   248    The function performs an enum query and rewrites the

   249    Request-URI with the result of the query. See Section 1.1,

   250    "Overview" for more information.

   252    Meaning of the parameters is as follows:

   253      * suffix - Suffix to be appended to the domain name.

   254      * service - Service string to be used in the service field.

   256    This function can be used from REQUEST_ROUTE.

   258    Example 1.9. enum_query usage

   259 ...

   260 # search for "e2u+sip" in freenum.org

   261 enum_query("freenum.org.");

   262 ...

   263 # search for "e2u+sip" in default tree (configured as parameter)

   264 enum_query();

   265 ...

   266 # search for "e2u+voice:sip" in e164.arpa

   267 enum_query("e164.arpa.","voice");

   268 ...

   269 # search for service type "sip" or "voice:sip" or "video:sip"

   270 # note the '+' sign in front of the second parameter

   271 enum_query("e164.arpa.","+sip+voice:sip+video:sip");

   272 ...

   273 # quering for service sip and voice:sip

   274 enum_query("e164.arpa.");

   275 enum_query("e164.arpa.","voice");

   276 # or use instead

   277 enum_query("e164.arpa.","+sip+voice:sip");

   278 ...

   280 1.4.2.  enum_pv_query("pvar"[,"suffix"[,"service"]])

   282    The function performs an enum query on E.164 number stored in

   283    its pseudo variable argument and rewrites the Request-URI with

   284    the result of the query. See Section 1.1, "Overview" for more

   285    information.

   287    Meaning of the parameters is as follows:

   288      * pvar - Pseudo variable that holds an E.164 number on which

   289        enum query is performed.

   290      * suffix - Suffix to be appended to the domain name.

   291      * service - Service string to be used in the service field.

   293    This function can be used from REQUEST_ROUTE.

   295    Example 1.10. enum_pv_query usage

   296 ...

   297 # search for "e2u+sip" in freenum.org

   298 enum_pv_query("$avp(i:100)", "freenum.org.");

   299 ...

   300 # search for "e2u+sip" in default tree (configured as parameter)

   301 enum_pv_query("$fU");

   302 ...

   303 # search for "e2u+voice:sip" in e164.arpa

   304 enum_pv_query("$avp(i:100)","e164.arpa.","voice");

   305 ...

   306 # search for service type "sip" or "voice:sip" or "video:sip"

   307 # note the '+' sign in front of the second parameter

   308 enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip");

   309 ...

   310 # quering for service sip and voice:sip

   311 enum_pv_query("$avp(i:100)","e164.arpa.");

   312 enum_pv_query("$avp(i:100)","e164.arpa.","voice");

   313 # or use instead

   314 enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");

   315 ...

   317 1.4.3.  i_enum_query(["suffix"[,"service"]])

   319    The function performs an enum query and rewrites the

   320    Request-URI with the result of the query. This the

   321    Infrastructure-ENUM version of enum_query(). The only

   322    difference to enum_query() is in the calculation of the FQDN

   323    where NAPTR records are looked for.

   325    See

   326    ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberle

   327    r-carrier-enum-01.txt for the rationale behind this function.

   329 1.4.4.  isn_query(["suffix"[,"service"]])

   331    The function performs a ISN query and rewrites the

   332    Request-URI with the result of the query. See Section 1.1,

   333    "Overview" for more information.

   335    Meaning of the parameters is as follows:

   336      * suffix - Suffix to be appended to the domain name.

   337      * service - Service string to be used in the service field.

   339    This function can be used from REQUEST_ROUTE.

   341    See ftp://ftp.ietf.org/rfc/rfc3872.txt and

   342    ftp://ftp.ietf.org/rfc/rfc2871.txt for information

   343    regarding the ITAD part of the ISN string.

   345    Example 1.11. isn_query usage

   346 ...

   347 # search for "e2u+sip" in freenum.org

   348 isn_query("freenum.org.");

   349 ...

   350 # search for "e2u+sip" in default tree (configured as parameter)

   351 enum_query();

   352 ...

   353 # search for "e2u+voice:sip" in freenum.org

   354 enum_query("freenum.org.","voice");

   355 ...

   357 1.4.5. is_from_user_enum()

   359    Checks if the user part of from URI is found in an enum lookup.

   360    Returns 1 if yes and -1 if not.

   362    This function can be used from REQUEST_ROUTE.

   364    Example 1.12. is_from_user_enum usage

   365 ...

   366 if (is_from_user_enum()) {

   367         ....

   368 };

   369 ...

Contributed Logic / file revision

opensips/modules/enum/README@7ae8da2fe7c8

opensips/modules/enum/README