1.1 --- a/opensips/modules/enum/README Wed Feb 10 21:25:01 2010 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,369 +0,0 @@
1.4 -Enum Module
1.5 -
1.6 -Juha Heinanen
1.7 -
1.8 - <jh@song.fi>
1.9 -
1.10 -Otmar Lendl
1.11 -
1.12 - <lendl@nic.at>
1.13 -
1.14 - Copyright © 2002, 2003 Juha Heinanen
1.15 - Revision History
1.16 - Revision $Revision: 5907 $ $Date: 2010-01-18 10:45:05 +0100
1.17 - (Mon, 18 Jan 2010) $
1.18 - __________________________________________________________
1.19 -
1.20 - Table of Contents
1.21 -
1.22 - 1. Admin Guide
1.23 -
1.24 - 1.1. Overview
1.25 - 1.2. Dependencies
1.26 - 1.3. Exported Parameters
1.27 -
1.28 - 1.3.1. domain_suffix (string)
1.29 - 1.3.2. tel_uri_params (string)
1.30 - 1.3.3. i_enum_suffix (string)
1.31 - 1.3.4. isn_suffix (string)
1.32 - 1.3.5. branchlabel (string)
1.33 - 1.3.6. bl_algorithm (string)
1.34 -
1.35 - 1.4. Exported Functions
1.36 -
1.37 - 1.4.1. enum_query(["suffix"[,"service"]])
1.38 - 1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
1.39 - 1.4.3. i_enum_query(["suffix"[,"service"]])
1.40 - 1.4.4. isn_query(["suffix"[,"service"]])
1.41 - 1.4.5. is_from_user_enum()
1.42 -
1.43 - List of Examples
1.44 -
1.45 - 1.1. Setting domain_suffix module parameter
1.46 - 1.2. Setting tel_uri_params module parameter
1.47 - 1.3. Setting i_enum_suffix module parameter
1.48 - 1.4. Setting isn_query usage module parameter
1.49 - 1.5. Setting branchlabel module parameter
1.50 - 1.6. Zone file example
1.51 - 1.7. Zone file example
1.52 - 1.8. Setting the bl_algorithm module parameter
1.53 - 1.9. enum_query usage
1.54 - 1.10. enum_pv_query usage
1.55 - 1.11. isn_query usage
1.56 - 1.12. is_from_user_enum usage
1.57 -
1.58 -Chapter 1. Admin Guide
1.59 -
1.60 -1.1. Overview
1.61 -
1.62 - Enum module implements [i_]enum_query functions that make an
1.63 - enum query based on the user part of the current Request-URI.
1.64 - These functions assume that the user part consists of an
1.65 - international phone number of the form +decimal-digits, where
1.66 - the number of digits is at least 2 and at most 15. Out of this
1.67 - number enum_query forms a domain name, where the digits are in
1.68 - reverse order and separated by dots followed by domain suffix
1.69 - that by default is "e164.arpa.". For example, if the user part
1.70 - is +35831234567, the domain name will be
1.71 - "7.6.5.4.3.2.1.3.8.5.3.e164.arpa.". i_enum_query operates in a
1.72 - similar fashion. The only difference is that it adds a label
1.73 - (default "i") to branch off from the default, user-ENUM tree to
1.74 - an infrastructure ENUM tree.
1.75 -
1.76 - After forming the domain name, enum_query queries DNS for its
1.77 - NAPTR records. From the possible response enum_query chooses
1.78 - those records, whose flags field has string value "u", and
1.79 - whose services field has string value "e2u+[service:]sip" or
1.80 - "e2u+type[:subtype][+type[:subtype]...]" (case is ignored in
1.81 - both cases), and whose regexp field is of the form
1.82 - !pattern!replacement!.
1.83 -
1.84 - Then enum_query sorts the chosen NAPTR records based on their
1.85 - <order, preference>. After sorting, enum_query replaces the
1.86 - current Request URI by applying regexp of the most preferred
1.87 - NAPTR record its user part and appends to the request new
1.88 - branches by applying regexp of each remaining NAPTR record to
1.89 - the user part of the current Request URI. If a new URI is a tel
1.90 - URI, enum_query appends to it as tel URI parameters the value
1.91 - of tel_uri_params module parameter. Finally, enum_query
1.92 - associates a q value with each new URI based on the <order,
1.93 - preference> of the corresponding NAPTR record.
1.94 -
1.95 - When using enum_query without any parameters, it searches for
1.96 - NAPTRs with service type "e2u+sip" in the default enum tree.
1.97 - When using enum_query with a single parameter, this parameter
1.98 - will be used as enum tree. When using enum_query with two
1.99 - parameters, the functionality depends on the first letter in
1.100 - the second parameter. When the first letter is not a '+' sign,
1.101 - the second parameter will be used to search for NAPTRs with
1.102 - service type "e2u+parameter:sip". When the second parameter
1.103 - starts with a '+' sign, the ENUM lookup also supports compound
1.104 - NAPTRs (e.g. "e2u+voice:sip+video:sip") and searching for
1.105 - multiple service types within one lookup. Multiple service
1.106 - types must be separeted by a '+' sign.
1.107 -
1.108 - Most of the time you want to route based on the RURI. On rare
1.109 - occasions you may wish to route based on something else. The
1.110 - function enum_pv_query mimics the behavior of the enum_query
1.111 - function except the E.164 number in its pseudo variable
1.112 - argument is used for the enum lookup instead of the user part
1.113 - of the RURI. Obviously the user part of the RURI is still used
1.114 - in the NAPTR regexp.
1.115 -
1.116 - Enum query returns 1 if the current Request URI was replaced
1.117 - and -1 if not.
1.118 -
1.119 - Enum module also implements is_from_user_enum function. This
1.120 - function does an enum lookup on the from user and returns true
1.121 - if found, false otherwise.
1.122 -
1.123 - In addition to standard ENUM, support for ISN (ITAD Subscriber
1.124 - Numbers) is provided as well. To allow ISN lookups to resolve,
1.125 - a different formatting algorithm is expected by the DNS server.
1.126 - Whereas a ENUM NAPTR record expects a DNS query of the form
1.127 - 9.8.7.6.5.4.3.2.1.<suffix>, ISN method expects a DNS query of
1.128 - the form 6.5.1212.<suffix>. That is, a valid ISN number includes
1.129 - a prefix of '56' in the example. The rest of the number is a
1.130 - ITAD (Internet Telephony Administrative Domain) as defined
1.131 - in RFCs 3872 and 2871, and as allocated by the IANA in
1.132 - http://www.iana.org/assignments/trip-parameters. The ITAD is
1.133 - left intact and not refersed as ENUM requires. To learn more
1.134 - about ISN please refer to documents at www.freenum.org.
1.135 -
1.136 - To complete a ISN lookup on the user part of the Request-URI,
1.137 - isn_query() is used instead of enum_query().
1.138 -
1.139 -1.2. Dependencies
1.140 -
1.141 - The module depends on the following modules (in the other words
1.142 - the listed modules must be loaded before this module):
1.143 - * No dependencies.
1.144 -
1.145 -1.3. Exported Parameters
1.146 -
1.147 -1.3.1. domain_suffix (string)
1.148 -
1.149 - The domain suffix to be added to the domain name obtained from
1.150 - the digits of an E164 number. Can be overridden by a parameter
1.151 - to enum_query.
1.152 -
1.153 - Default value is "e164.arpa."
1.154 -
1.155 - Example 1.1. Setting domain_suffix module parameter
1.156 -modparam("enum", "domain_suffix", "e1234.arpa.")
1.157 -
1.158 -1.3.2. tel_uri_params (string)
1.159 -
1.160 - A string whose contents is appended to each new tel URI in the
1.161 - request as tel URI parameters.
1.162 -
1.163 -Note
1.164 -
1.165 - Currently OpenSIPS does not support tel URIs. This means that
1.166 - at present tel_uri_params is appended as URI parameters to
1.167 - every URI.
1.168 -
1.169 - Default value is ""
1.170 -
1.171 - Example 1.2. Setting tel_uri_params module parameter
1.172 -modparam("enum", "tel_uri_params", ";npdi")
1.173 -
1.174 -1.3.3. i_enum_suffix (string)
1.175 -
1.176 - The domain suffix to be used for i_enum_query() lookups. Can be
1.177 - overridden by a parameter to i_enum_query.
1.178 -
1.179 - Default value is "e164.arpa."
1.180 -
1.181 - Example 1.3. Setting i_enum_suffix module parameter
1.182 -modparam("enum", "i_enum_suffix", "e1234.arpa.")
1.183 -
1.184 -1.3.4. isn_suffix (string)
1.185 -
1.186 - The domain suffix to be used for isn_query() lookups. Can be
1.187 - overridden by a parameter to isn_query.
1.188 -
1.189 - Default value is "freenum.org."
1.190 -
1.191 - Example 1.4. Setting isn_suffix module parameter
1.192 -modparam("enum", "isn_suffix", "freenum.org.")
1.193 -
1.194 -1.3.5. branchlabel (string)
1.195 -
1.196 - This parameter determines which label i_enum_query() will use
1.197 - to branch off to the infrastructure ENUM tree.
1.198 -
1.199 - Default value is ""i""
1.200 -
1.201 - Example 1.5. Setting branchlabel module parameter
1.202 -modparam("enum", "branchlabel", "i")
1.203 -
1.204 -1.3.6. bl_algorithm (string)
1.205 -
1.206 - This parameter determines which algorithm i_enum_query() will
1.207 - use to select the position in the DNS tree where the
1.208 - infrastructure tree branches off the user ENUM tree.
1.209 -
1.210 - If set to "cc", i_enum_query() will always inserts the label at
1.211 - the country-code level. Examples: i.1.e164.arpa,
1.212 - i.3.4.e164.arpa, i.2.5.3.e164.arpa
1.213 -
1.214 - If set to "txt", i_enum_query() will look for a TXT record at
1.215 - [branchlabel].[reverse-country-code].[i_enum_suffix] to
1.216 - indicate after how many digits the label should in inserted.
1.217 -
1.218 - Example 1.6. Zone file example
1.219 -i.1.e164.arpa. IN TXT "4"
1.220 -9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5
1.221 -678 999"
1.222 -
1.223 - If set to "ebl", i_enum_query() will look for an EBL (ENUM
1.224 - Branch Label) record at
1.225 - [branchlabel].[reverse-country-code].[i_enum_suffix]. See
1.226 - http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-loc
1.227 - ation-record-00.txt for a description of that record and the
1.228 - meaning of the fields. The RR type for the EBL has not been
1.229 - allocated yet. This version of the code uses 65300. See
1.230 - resolve.h.
1.231 -
1.232 - Example 1.7. Zone file example
1.233 -i.1.e164.arpa. TYPE65300 \# 14 (
1.234 - 04 ; position
1.235 - 01 69 ; separator
1.236 - 04 65 31 36 34 04 61 72 70 61 00 ; e164.ar
1.237 -pa
1.238 -; )
1.239 -9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5
1.240 -678 999"
1.241 -
1.242 - Default value is "cc"
1.243 -
1.244 - Example 1.8. Setting the bl_algorithm module parameter
1.245 -modparam("enum", "bl_algorithm", "txt")
1.246 -
1.247 -1.4. Exported Functions
1.248 -
1.249 -1.4.1. enum_query(["suffix"[,"service"]])
1.250 -
1.251 - The function performs an enum query and rewrites the
1.252 - Request-URI with the result of the query. See Section 1.1,
1.253 - "Overview" for more information.
1.254 -
1.255 - Meaning of the parameters is as follows:
1.256 - * suffix - Suffix to be appended to the domain name.
1.257 - * service - Service string to be used in the service field.
1.258 -
1.259 - This function can be used from REQUEST_ROUTE.
1.260 -
1.261 - Example 1.9. enum_query usage
1.262 -...
1.263 -# search for "e2u+sip" in freenum.org
1.264 -enum_query("freenum.org.");
1.265 -...
1.266 -# search for "e2u+sip" in default tree (configured as parameter)
1.267 -enum_query();
1.268 -...
1.269 -# search for "e2u+voice:sip" in e164.arpa
1.270 -enum_query("e164.arpa.","voice");
1.271 -...
1.272 -# search for service type "sip" or "voice:sip" or "video:sip"
1.273 -# note the '+' sign in front of the second parameter
1.274 -enum_query("e164.arpa.","+sip+voice:sip+video:sip");
1.275 -...
1.276 -# quering for service sip and voice:sip
1.277 -enum_query("e164.arpa.");
1.278 -enum_query("e164.arpa.","voice");
1.279 -# or use instead
1.280 -enum_query("e164.arpa.","+sip+voice:sip");
1.281 -...
1.282 -
1.283 -1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
1.284 -
1.285 - The function performs an enum query on E.164 number stored in
1.286 - its pseudo variable argument and rewrites the Request-URI with
1.287 - the result of the query. See Section 1.1, "Overview" for more
1.288 - information.
1.289 -
1.290 - Meaning of the parameters is as follows:
1.291 - * pvar - Pseudo variable that holds an E.164 number on which
1.292 - enum query is performed.
1.293 - * suffix - Suffix to be appended to the domain name.
1.294 - * service - Service string to be used in the service field.
1.295 -
1.296 - This function can be used from REQUEST_ROUTE.
1.297 -
1.298 - Example 1.10. enum_pv_query usage
1.299 -...
1.300 -# search for "e2u+sip" in freenum.org
1.301 -enum_pv_query("$avp(i:100)", "freenum.org.");
1.302 -...
1.303 -# search for "e2u+sip" in default tree (configured as parameter)
1.304 -enum_pv_query("$fU");
1.305 -...
1.306 -# search for "e2u+voice:sip" in e164.arpa
1.307 -enum_pv_query("$avp(i:100)","e164.arpa.","voice");
1.308 -...
1.309 -# search for service type "sip" or "voice:sip" or "video:sip"
1.310 -# note the '+' sign in front of the second parameter
1.311 -enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip");
1.312 -...
1.313 -# quering for service sip and voice:sip
1.314 -enum_pv_query("$avp(i:100)","e164.arpa.");
1.315 -enum_pv_query("$avp(i:100)","e164.arpa.","voice");
1.316 -# or use instead
1.317 -enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
1.318 -...
1.319 -
1.320 -1.4.3. i_enum_query(["suffix"[,"service"]])
1.321 -
1.322 - The function performs an enum query and rewrites the
1.323 - Request-URI with the result of the query. This the
1.324 - Infrastructure-ENUM version of enum_query(). The only
1.325 - difference to enum_query() is in the calculation of the FQDN
1.326 - where NAPTR records are looked for.
1.327 -
1.328 - See
1.329 - ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberle
1.330 - r-carrier-enum-01.txt for the rationale behind this function.
1.331 -
1.332 -1.4.4. isn_query(["suffix"[,"service"]])
1.333 -
1.334 - The function performs a ISN query and rewrites the
1.335 - Request-URI with the result of the query. See Section 1.1,
1.336 - "Overview" for more information.
1.337 -
1.338 - Meaning of the parameters is as follows:
1.339 - * suffix - Suffix to be appended to the domain name.
1.340 - * service - Service string to be used in the service field.
1.341 -
1.342 - This function can be used from REQUEST_ROUTE.
1.343 -
1.344 - See ftp://ftp.ietf.org/rfc/rfc3872.txt and
1.345 - ftp://ftp.ietf.org/rfc/rfc2871.txt for information
1.346 - regarding the ITAD part of the ISN string.
1.347 -
1.348 - Example 1.11. isn_query usage
1.349 -...
1.350 -# search for "e2u+sip" in freenum.org
1.351 -isn_query("freenum.org.");
1.352 -...
1.353 -# search for "e2u+sip" in default tree (configured as parameter)
1.354 -enum_query();
1.355 -...
1.356 -# search for "e2u+voice:sip" in freenum.org
1.357 -enum_query("freenum.org.","voice");
1.358 -...
1.359 -
1.360 -1.4.5. is_from_user_enum()
1.361 -
1.362 - Checks if the user part of from URI is found in an enum lookup.
1.363 - Returns 1 if yes and -1 if not.
1.364 -
1.365 - This function can be used from REQUEST_ROUTE.
1.366 -
1.367 - Example 1.12. is_from_user_enum usage
1.368 -...
1.369 -if (is_from_user_enum()) {
1.370 - ....
1.371 -};
1.372 -...
