Contributed Logic / file revision

 Enum Module

 Juha Heinanen

    <jh@song.fi>

 Otmar Lendl

    <lendl@nic.at>

    Copyright © 2002, 2003 Juha Heinanen

    Revision History

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

                               (Mon, 18 Jan 2010) $

      __________________________________________________________

    Table of Contents

    1. Admin Guide

         1.1. Overview

         1.2. Dependencies

         1.3. Exported Parameters

               1.3.1. domain_suffix (string)

               1.3.2. tel_uri_params (string)

               1.3.3. i_enum_suffix (string)

               1.3.4. isn_suffix (string)

               1.3.5. branchlabel (string)

               1.3.6. bl_algorithm (string)

         1.4. Exported Functions

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

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

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

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

               1.4.5. is_from_user_enum()

    List of Examples

    1.1. Setting domain_suffix module parameter

    1.2. Setting tel_uri_params module parameter

    1.3. Setting i_enum_suffix module parameter

    1.4. Setting isn_query usage module parameter

    1.5. Setting branchlabel module parameter

    1.6. Zone file example

    1.7. Zone file example

    1.8. Setting the bl_algorithm module parameter

    1.9. enum_query usage

    1.10. enum_pv_query usage

    1.11. isn_query usage

    1.12. is_from_user_enum usage

 Chapter 1. Admin Guide

 1.1. Overview

    Enum module implements [i_]enum_query functions that make an

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

    These functions assume that the user part consists of an

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

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

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

    reverse order and separated by dots followed by domain suffix

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

    is +35831234567, the domain name will be

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

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

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

    an infrastructure ENUM tree.

    After forming the domain name, enum_query queries DNS for its

    NAPTR records. From the possible response enum_query chooses

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

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

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

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

    !pattern!replacement!.

    Then enum_query sorts the chosen NAPTR records based on their

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

    current Request URI by applying regexp of the most preferred

    NAPTR record its user part and appends to the request new

    branches by applying regexp of each remaining NAPTR record to

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

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

    of tel_uri_params module parameter. Finally, enum_query

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

    preference> of the corresponding NAPTR record.

    When using enum_query without any parameters, it searches for

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

    When using enum_query with a single parameter, this parameter

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

    parameters, the functionality depends on the first letter in

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

    the second parameter will be used to search for NAPTRs with

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

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

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

    multiple service types within one lookup. Multiple service

    types must be separeted by a '+' sign.

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

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

    function enum_pv_query mimics the behavior of the enum_query

    function except the E.164 number in its pseudo variable

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

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

    in the NAPTR regexp.

    Enum query returns 1 if the current Request URI was replaced

    and -1 if not.

    Enum module also implements is_from_user_enum function. This

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

    if found, false otherwise.

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

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

    a different formatting algorithm is expected by the DNS server.

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

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

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

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

    ITAD (Internet Telephony Administrative Domain) as defined

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

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

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

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

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

    isn_query() is used instead of enum_query().

 1.2. Dependencies

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

    the listed modules must be loaded before this module):

      * No dependencies.

 1.3. Exported Parameters

 1.3.1. domain_suffix (string)

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

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

    to enum_query.

    Default value is "e164.arpa."

    Example 1.1. Setting domain_suffix module parameter

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

 1.3.2. tel_uri_params (string)

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

    request as tel URI parameters.

 Note

    Currently OpenSIPS does not support tel URIs. This means that

    at present tel_uri_params is appended as URI parameters to

    every URI.

    Default value is ""

    Example 1.2. Setting tel_uri_params module parameter

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

 1.3.3. i_enum_suffix (string)

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

    overridden by a parameter to i_enum_query.

    Default value is "e164.arpa."

    Example 1.3. Setting i_enum_suffix module parameter

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

 1.3.4. isn_suffix (string)

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

    overridden by a parameter to isn_query.

    Default value is "freenum.org."

    Example 1.4. Setting isn_suffix module parameter

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

 1.3.5. branchlabel (string)

    This parameter determines which label i_enum_query() will use

    to branch off to the infrastructure ENUM tree.

    Default value is ""i""

    Example 1.5. Setting branchlabel module parameter

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

 1.3.6. bl_algorithm (string)

    This parameter determines which algorithm i_enum_query() will

    use to select the position in the DNS tree where the

    infrastructure tree branches off the user ENUM tree.

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

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

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

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

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

    indicate after how many digits the label should in inserted.

    Example 1.6. Zone file example

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

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

 678 999"

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

    Branch Label) record at

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

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

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

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

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

    resolve.h.

    Example 1.7. Zone file example

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

                               04    ; position

                               01 69 ; separator

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

 pa

 ;                               )

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

 678 999"

    Default value is "cc"

    Example 1.8. Setting the bl_algorithm module parameter

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

 1.4. Exported Functions

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

    The function performs an enum query and rewrites the

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

    "Overview" for more information.

    Meaning of the parameters is as follows:

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

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

    This function can be used from REQUEST_ROUTE.

    Example 1.9. enum_query usage

 ...

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

 enum_query("freenum.org.");

 ...

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

 enum_query();

 ...

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

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

 ...

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

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

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

 ...

 # quering for service sip and voice:sip

 enum_query("e164.arpa.");

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

 # or use instead

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

 ...

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

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

    its pseudo variable argument and rewrites the Request-URI with

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

    information.

    Meaning of the parameters is as follows:

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

        enum query is performed.

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

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

    This function can be used from REQUEST_ROUTE.

    Example 1.10. enum_pv_query usage

 ...

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

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

 ...

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

 enum_pv_query("$fU");

 ...

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

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

 ...

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

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

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

 ...

 # quering for service sip and voice:sip

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

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

 # or use instead

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

 ...

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

    The function performs an enum query and rewrites the

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

    Infrastructure-ENUM version of enum_query(). The only

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

    where NAPTR records are looked for.

    See

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

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

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

    The function performs a ISN query and rewrites the

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

    "Overview" for more information.

    Meaning of the parameters is as follows:

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

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

    This function can be used from REQUEST_ROUTE.

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

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

    regarding the ITAD part of the ISN string.

    Example 1.11. isn_query usage

 ...

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

 isn_query("freenum.org.");

 ...

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

 enum_query();

 ...

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

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

 ...

 1.4.5. is_from_user_enum()

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

    Returns 1 if yes and -1 if not.

    This function can be used from REQUEST_ROUTE.

    Example 1.12. is_from_user_enum usage

 ...

 if (is_from_user_enum()) {

         ....

 };

 ...