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