opensips/modules/enum/doc/enum_admin.xml

Wed, 10 Feb 2010 21:25:01 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Wed, 10 Feb 2010 21:25:01 +0100
changeset 18
8ec65b8f6e2c
parent 13
b63f281afe6b
permissions
-rw-r--r--

Extend uac_auth() of the UAC module to workaround CSEQ problems.
This logic is meant to complement that of changeset 17, which
added rich authentication credentials to the gw table and its
associated logic in the LCR module.

michael@12 1 <!-- Enum Module User's Guide -->
michael@12 2
michael@12 3 <chapter>
michael@12 4
michael@12 5 <title>&adminguide;</title>
michael@12 6
michael@12 7 <section id="sec-overview">
michael@12 8 <title>Overview</title>
michael@12 9 <para>
michael@12 10 Enum module implements [i_]enum_query functions that make an enum query
michael@12 11 based on the user part of the current Request-URI. These functions
michael@12 12 assume that the user part consists of an international phone number
michael@12 13 of the form +decimal-digits, where the number of digits is at
michael@12 14 least 2 and at most 15. Out of this number
michael@12 15 <function moreinfo="none">enum_query</function> forms a domain name,
michael@12 16 where the digits are in reverse order and separated by dots followed by
michael@12 17 domain suffix that by default is <quote>e164.arpa.</quote>. For example,
michael@12 18 if the user part is +35831234567, the domain
michael@12 19 name will be <quote>7.6.5.4.3.2.1.3.8.5.3.e164.arpa.</quote>.
michael@12 20 <function moreinfo="none">i_enum_query</function> operates in a similar
michael@12 21 fashion. The only difference is that it adds a label (default "i")
michael@12 22 to branch off from the default, user-ENUM tree to an infrastructure ENUM tree.
michael@12 23 </para>
michael@12 24 <para>
michael@12 25 After forming the domain name,
michael@12 26 <function moreinfo="none">enum_query</function> queries
michael@12 27 DNS for its NAPTR records. From the possible response
michael@12 28 <function moreinfo="none">enum_query</function> chooses those records,
michael@12 29 whose flags field has string value "u", and whose services field has
michael@12 30 string value "e2u+[service:]sip" or
michael@12 31 "e2u+type[:subtype][+type[:subtype]...]" (case is ignored in both
michael@12 32 cases), and whose regexp field is of the form !pattern!replacement!.
michael@12 33 </para>
michael@12 34 <para>
michael@12 35 Then <function moreinfo="none">enum_query</function> sorts the chosen
michael@12 36 NAPTR records based on their &lt;order, preference&gt;. After sorting,
michael@12 37 <function moreinfo="none">enum_query</function> replaces the current
michael@12 38 Request URI by applying regexp of the most preferred NAPTR record its
michael@12 39 user part and appends to the request new branches by applying regexp of
michael@12 40 each remaining NAPTR record to the user part of the
michael@12 41 current Request URI. If a new URI is a tel URI,
michael@12 42 <function moreinfo="none">enum_query</function> appends to it as tel
michael@12 43 URI parameters the value of tel_uri_params module parameter. Finally,
michael@12 44 <function moreinfo="none">enum_query</function> associates a q value
michael@12 45 with each new URI based on the &lt;order, preference&gt; of the
michael@12 46 corresponding NAPTR record.
michael@12 47 </para>
michael@12 48 <para>
michael@12 49 When using <function moreinfo="none">enum_query</function> without any
michael@12 50 parameters, it searches for NAPTRs with service type "e2u+sip" in the
michael@12 51 default enum tree. When using
michael@12 52 <function moreinfo="none">enum_query</function> with a single parameter,
michael@12 53 this parameter will be used as enum tree. When using
michael@12 54 <function moreinfo="none">enum_query</function>
michael@12 55 with two parameters, the functionality depends on the first letter in
michael@12 56 the second parameter. When the first letter is not a '+' sign, the
michael@12 57 second parameter will be used to search for NAPTRs with service type
michael@12 58 "e2u+parameter:sip". When the second parameter starts with a '+' sign,
michael@12 59 the ENUM lookup also supports compound NAPTRs
michael@12 60 (e.g. "e2u+voice:sip+video:sip") and searching for multiple service
michael@12 61 types within one lookup. Multiple service types must be separeted
michael@12 62 by a '+' sign.
michael@12 63 </para>
michael@12 64 <para>
michael@12 65 Most of the time you want to route based on the RURI. On rare occasions
michael@12 66 you may wish to route based on something else. The function
michael@12 67 <function moreinfo="none">enum_pv_query</function> mimics the behavior
michael@12 68 of the <function moreinfo="none">enum_query</function> function except the
michael@12 69 E.164 number in its pseudo variable argument is used for the enum lookup instead of the user
michael@12 70 part of the RURI. Obviously the user part of the RURI is still used in the
michael@12 71 NAPTR regexp.
michael@12 72 </para>
michael@12 73 <para>
michael@12 74 Enum query returns 1 if the current Request URI was replaced
michael@12 75 and -1 if not.
michael@12 76 </para>
michael@12 77 <para>
michael@13 78 In addition to standard ENUM, support for ISN (ITAD Subscriber
michael@13 79 Numbers) is provided as well. To allow ISN lookups to resolve,
michael@13 80 a different formatting algorithm is expected by the DNS server.
michael@13 81 Whereas a ENUM NAPTR record expects a DNS query of the form
michael@13 82 9.8.7.6.5.4.3.2.1.<suffix>, ISN method expects a DNS query of
michael@13 83 the form 6.5.1212.<suffix>. That is, a valid ISN number includes
michael@13 84 a prefix of '56' in the example. The rest of the number is a
michael@13 85 ITAD (Internet Telephony Administrative Domain) as defined
michael@13 86 in RFCs 3872 and 2871, and as allocated by the IANA in
michael@13 87 http://www.iana.org/assignments/trip-parameters. The ITAD is
michael@13 88 left intact and not refersed as ENUM requires. To learn more
michael@13 89 about ISN please refer to documents at www.freenum.org.
michael@13 90 </para>
michael@13 91 <para>
michael@13 92 To complete a ISN lookup on the user part of the Request-URI,
michael@13 93 isn_query() is used instead of enum_query().
michael@13 94 </para>
michael@13 95 <para>
michael@12 96 Enum module also implements is_from_user_enum function.
michael@12 97 This function does an enum lookup on the from user and
michael@12 98 returns true if found, false otherwise.
michael@12 99 </para>
michael@12 100 </section>
michael@12 101
michael@12 102 <section>
michael@12 103 <title>Dependencies</title>
michael@12 104 <para>
michael@12 105 The module depends on the following modules (in the other words the
michael@12 106 listed modules must be loaded before this module):
michael@12 107 <itemizedlist>
michael@12 108 <listitem>
michael@12 109 <para>No dependencies.</para>
michael@12 110 </listitem>
michael@12 111 </itemizedlist>
michael@12 112 </para>
michael@12 113 </section>
michael@12 114
michael@12 115 <section>
michael@12 116 <title>Exported Parameters</title>
michael@12 117 <section>
michael@12 118 <title><varname>domain_suffix</varname> (string)</title>
michael@12 119 <para>
michael@12 120 The domain suffix to be added to the domain name obtained from
michael@12 121 the digits of an <acronym>E164</acronym> number. Can be overridden
michael@12 122 by a parameter to enum_query.
michael@12 123 </para>
michael@12 124 <para>
michael@12 125 Default value is <quote>e164.arpa.</quote>
michael@12 126 </para>
michael@12 127 <example>
michael@12 128 <title>Setting domain_suffix module parameter</title>
michael@12 129 <programlisting format="linespecific">
michael@12 130 modparam("enum", "domain_suffix", "e1234.arpa.")
michael@12 131 </programlisting>
michael@12 132 </example>
michael@12 133 </section>
michael@12 134
michael@12 135 <section>
michael@12 136 <title><varname>tel_uri_params</varname> (string)</title>
michael@12 137 <para>
michael@12 138 A string whose contents is appended to each new tel URI in the
michael@12 139 request as tel URI parameters.
michael@12 140 </para>
michael@12 141 <note>
michael@12 142 <para>
michael@12 143 Currently &osips; does not support tel URIs. This means that at present
michael@12 144 tel_uri_params is appended as URI parameters to every URI.
michael@12 145 </para>
michael@12 146 </note>
michael@12 147 <para>
michael@12 148 Default value is <quote></quote>
michael@12 149 </para>
michael@12 150 <example>
michael@12 151 <title>Setting tel_uri_params module parameter</title>
michael@12 152 <programlisting format="linespecific">
michael@12 153 modparam("enum", "tel_uri_params", ";npdi")
michael@12 154 </programlisting>
michael@12 155 </example>
michael@12 156 </section>
michael@12 157 <section>
michael@12 158 <title><varname>i_enum_suffix</varname> (string)</title>
michael@12 159 <para>
michael@12 160 The domain suffix to be used for i_enum_query() lookups.
michael@12 161 Can be overridden by a parameter to i_enum_query.
michael@12 162 </para>
michael@12 163 <para>
michael@12 164 Default value is <quote>e164.arpa.</quote>
michael@12 165 </para>
michael@12 166 <example>
michael@12 167 <title>Setting i_enum_suffix module parameter</title>
michael@12 168 <programlisting format="linespecific">
michael@12 169 modparam("enum", "i_enum_suffix", "e1234.arpa.")
michael@12 170 </programlisting>
michael@12 171 </example>
michael@12 172 </section>
michael@12 173 <section>
michael@13 174 <title><varname>isn_suffix</varname> (string)</title>
michael@13 175 <para>
michael@13 176 The domain suffix to be used for isn_query() lookups. Can
michael@13 177 be overridden by a parameter to isn_query.
michael@13 178 </para>
michael@13 179 <para>
michael@13 180 Default value is <quote>freenum.org.</quote>
michael@13 181 </para>
michael@13 182 <example>
michael@13 183 <title>Setting isn_suffix module parameter</title>
michael@13 184 <programlisting format="linespecific">
michael@13 185 modparam("enum", "isn_suffix", "freenum.org.")
michael@13 186 </programlisting>
michael@13 187 </example>
michael@13 188 </section>
michael@13 189 <section>
michael@12 190 <title><varname>branchlabel</varname> (string)</title>
michael@12 191 <para>
michael@12 192 This parameter determines which label i_enum_query() will use
michael@12 193 to branch off to the infrastructure ENUM tree.
michael@12 194 </para>
michael@12 195 <para>
michael@12 196 Default value is <quote>"i"</quote>
michael@12 197 </para>
michael@12 198 <example>
michael@13 199 <title>Setting branchlabel module parameter</title>
michael@12 200 <programlisting format="linespecific">
michael@12 201 modparam("enum", "branchlabel", "i")
michael@12 202 </programlisting>
michael@12 203 </example>
michael@12 204 </section>
michael@12 205 <section>
michael@12 206 <title><varname>bl_algorithm</varname> (string)</title>
michael@12 207 <para>
michael@12 208 This parameter determines which algorithm i_enum_query() will use
michael@12 209 to select the position in the DNS tree where the infrastructure tree
michael@12 210 branches off the user ENUM tree.
michael@12 211 </para>
michael@12 212 <para>
michael@12 213 If set to "cc", i_enum_query() will always inserts the
michael@12 214 label at the country-code level.
michael@12 215 Examples: i.1.e164.arpa, i.3.4.e164.arpa, i.2.5.3.e164.arpa
michael@12 216 </para>
michael@12 217 <para>
michael@12 218 If set to "txt", i_enum_query() will look for a TXT record at
michael@12 219 [branchlabel].[reverse-country-code].[i_enum_suffix] to indicate after how many digits the
michael@12 220 label should in inserted.
michael@12 221 <example>
michael@12 222 <title>Zone file example</title>
michael@12 223 <programlisting format="linespecific">
michael@12 224 i.1.e164.arpa. IN TXT "4"
michael@12 225 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5678 999"
michael@12 226 </programlisting>
michael@12 227 </example>
michael@12 228 </para>
michael@12 229 <para>
michael@12 230 If set to "ebl", i_enum_query() will look for an EBL (ENUM Branch Label) record at
michael@12 231 [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
michael@12 232 meaning of the fields. The RR type for the EBL has not been allocated yet.
michael@12 233 This version of the code uses 65300. See resolve.h.
michael@12 234 <example>
michael@12 235 <title>Zone file example</title>
michael@12 236 <programlisting format="linespecific">
michael@12 237 i.1.e164.arpa. TYPE65300 \# 14 (
michael@12 238 04 ; position
michael@12 239 01 69 ; separator
michael@12 240 04 65 31 36 34 04 61 72 70 61 00 ; e164.arpa
michael@12 241 ; )
michael@12 242 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for +1 234 5678 999"
michael@12 243 </programlisting>
michael@12 244 </example>
michael@12 245 </para>
michael@12 246
michael@12 247 <para>
michael@12 248 Default value is <quote>cc</quote>
michael@12 249 </para>
michael@12 250 <example>
michael@12 251 <title>Setting the bl_algorithm module parameter</title>
michael@12 252 <programlisting format="linespecific">
michael@12 253 modparam("enum", "bl_algorithm", "txt")
michael@12 254 </programlisting>
michael@12 255 </example>
michael@12 256 </section>
michael@12 257
michael@12 258 </section>
michael@12 259
michael@12 260 <section>
michael@12 261 <title>Exported Functions</title>
michael@12 262 <section>
michael@12 263 <title>
michael@12 264 <function moreinfo="none">enum_query(["suffix"[,"service"]])</function>
michael@12 265 </title>
michael@12 266 <para>
michael@12 267 The function performs an enum query and rewrites the Request-URI with
michael@12 268 the result of the query. See <xref linkend="sec-overview"/> for more
michael@12 269 information.
michael@12 270 </para>
michael@12 271 <para>Meaning of the parameters is as follows:</para>
michael@12 272 <itemizedlist>
michael@12 273 <listitem>
michael@12 274 <para><emphasis>suffix</emphasis> - Suffix to be appended to the
michael@12 275 domain name.
michael@12 276 </para>
michael@12 277 </listitem>
michael@12 278 <listitem>
michael@12 279 <para><emphasis>service</emphasis> - Service string to be used in
michael@12 280 the service field.
michael@12 281 </para>
michael@12 282 </listitem>
michael@12 283 </itemizedlist>
michael@12 284 <para>
michael@12 285 This function can be used from REQUEST_ROUTE.
michael@12 286 </para>
michael@12 287 <example>
michael@12 288 <title><function moreinfo="none">enum_query</function> usage</title>
michael@12 289 <programlisting format="linespecific">
michael@12 290 ...
michael@12 291 # search for "e2u+sip" in freenum.org
michael@12 292 enum_query("freenum.org.");
michael@12 293 ...
michael@12 294 # search for "e2u+sip" in default tree (configured as parameter)
michael@12 295 enum_query();
michael@12 296 ...
michael@12 297 # search for "e2u+voice:sip" in e164.arpa
michael@12 298 enum_query("e164.arpa.","voice");
michael@12 299 ...
michael@12 300 # search for service type "sip" or "voice:sip" or "video:sip"
michael@12 301 # note the '+' sign in front of the second parameter
michael@12 302 enum_query("e164.arpa.","+sip+voice:sip+video:sip");
michael@12 303 ...
michael@12 304 # quering for service sip and voice:sip
michael@12 305 enum_query("e164.arpa.");
michael@12 306 enum_query("e164.arpa.","voice");
michael@12 307 # or use instead
michael@12 308 enum_query("e164.arpa.","+sip+voice:sip");
michael@12 309 ...
michael@12 310 </programlisting>
michael@12 311 </example>
michael@12 312 </section>
michael@12 313
michael@12 314 <section>
michael@12 315 <title>
michael@12 316 <function moreinfo="none">enum_pv_query("pvar"[,"suffix"[,"service"]])</function>
michael@12 317 </title>
michael@12 318 <para>
michael@12 319 The function performs an enum query on E.164 number stored
michael@12 320 in its pseudo variable argument and rewrites the Request-URI with
michael@12 321 the result of the query. See <xref linkend="sec-overview"/> for more
michael@12 322 information.
michael@12 323 </para>
michael@12 324 <para>Meaning of the parameters is as follows:</para>
michael@12 325 <itemizedlist>
michael@12 326 <listitem>
michael@12 327 <para><emphasis>pvar</emphasis> - Pseudo
michael@12 328 variable that holds an E.164 number on which enum
michael@12 329 query is performed.
michael@12 330 </para>
michael@12 331 </listitem>
michael@12 332 <listitem>
michael@12 333 <para><emphasis>suffix</emphasis> - Suffix to be appended to the
michael@12 334 domain name.
michael@12 335 </para>
michael@12 336 </listitem>
michael@12 337 <listitem>
michael@12 338 <para><emphasis>service</emphasis> - Service string to be used in
michael@12 339 the service field.
michael@12 340 </para>
michael@12 341 </listitem>
michael@12 342 </itemizedlist>
michael@12 343 <para>
michael@12 344 This function can be used from REQUEST_ROUTE.
michael@12 345 </para>
michael@12 346 <example>
michael@12 347 <title><function moreinfo="none">enum_pv_query</function> usage</title>
michael@12 348 <programlisting format="linespecific">
michael@12 349 ...
michael@12 350 # search for "e2u+sip" in freenum.org
michael@12 351 enum_pv_query("$avp(i:100)", "freenum.org.");
michael@12 352 ...
michael@12 353 # search for "e2u+sip" in default tree (configured as parameter)
michael@12 354 enum_pv_query("$fU");
michael@12 355 ...
michael@12 356 # search for "e2u+voice:sip" in e164.arpa
michael@12 357 enum_pv_query("$avp(i:100)","e164.arpa.","voice");
michael@12 358 ...
michael@12 359 # search for service type "sip" or "voice:sip" or "video:sip"
michael@12 360 # note the '+' sign in front of the second parameter
michael@12 361 enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip");
michael@12 362 ...
michael@12 363 # quering for service sip and voice:sip
michael@12 364 enum_pv_query("$avp(i:100)","e164.arpa.");
michael@12 365 enum_pv_query("$avp(i:100)","e164.arpa.","voice");
michael@12 366 # or use instead
michael@12 367 enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
michael@12 368 ...
michael@12 369 </programlisting>
michael@12 370 </example>
michael@12 371 </section>
michael@12 372
michael@12 373 <section>
michael@12 374 <title>
michael@12 375 <function moreinfo="none">i_enum_query(["suffix"[,"service"]])</function>
michael@12 376 </title>
michael@12 377 <para>
michael@12 378 The function performs an enum query and rewrites the Request-URI with
michael@12 379 the result of the query. This the Infrastructure-ENUM version of enum_query().
michael@12 380 The only difference to enum_query() is in the calculation of the
michael@12 381 FQDN where NAPTR records are looked for.
michael@12 382 </para>
michael@12 383 <para>
michael@12 384 See ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberler-carrier-enum-01.txt
michael@12 385 for the rationale behind this function.
michael@12 386 </para>
michael@12 387 </section>
michael@12 388
michael@12 389 <section>
michael@13 390 <title>
michael@13 391 <function moreinfo="none">isn_query(["suffix"[,"service"]])</function>
michael@13 392 </title>
michael@13 393 <para>
michael@13 394 The function performs a ISN query and rewrites the Request-URI with
michael@13 395 the result of the query. See <xref linkend="sec-overview"/> for more
michael@13 396 information.
michael@13 397 </para>
michael@13 398 <para>Meaning of the parameters is as follows:</para>
michael@13 399 <itemizedlist>
michael@13 400 <listitem>
michael@13 401 <para><emphasis>suffix</emphasis> - Suffix to be appended to the
michael@13 402 domain name.
michael@13 403 </para>
michael@13 404 </listitem>
michael@13 405 <listitem>
michael@13 406 <para><emphasis>service</emphasis> - Service string to be used in
michael@13 407 the service field.
michael@13 408 </para>
michael@13 409 </listitem>
michael@13 410 </itemizedlist>
michael@13 411 <para>
michael@13 412 This function can be used from REQUEST_ROUTE.
michael@13 413 </para>
michael@13 414 <para>
michael@15 415 See ftp://ftp.ietf.org/rfc/rfc3872.txt and
michael@15 416 ftp://ftp.ietf.org/rfc/rfc2871.txt for information
michael@13 417 regarding the ITAD part of the ISN string.
michael@13 418 </para>
michael@13 419 <example>
michael@13 420 <title><function moreinfo="none">isn_query</function> usage</title>
michael@13 421 <programlisting format="linespecific">
michael@13 422 ...
michael@13 423 # search for "e2u+sip" in freenum.org
michael@13 424 isn_query("freenum.org.");
michael@13 425 ...
michael@13 426 # search for "e2u+sip" in default tree (configured as parameter)
michael@13 427 isn_query();
michael@13 428 ...
michael@13 429 # search for "e2u+voice:sip" in freenum.org
michael@13 430 isn_query("freenum.org.","voice");
michael@13 431 ...
michael@13 432 </programlisting>
michael@13 433 </example>
michael@13 434 </section>
michael@13 435
michael@13 436 <section>
michael@12 437 <title><function moreinfo="none">is_from_user_enum()</function></title>
michael@12 438 <para>
michael@12 439 Checks if the user part of from <abbrev>URI</abbrev>
michael@12 440 is found in an enum lookup.
michael@12 441 Returns 1 if yes and -1 if not.
michael@12 442 </para>
michael@12 443 <para>
michael@12 444 This function can be used from REQUEST_ROUTE.
michael@12 445 </para>
michael@12 446 <example>
michael@12 447 <title><function moreinfo="none">is_from_user_enum</function> usage</title>
michael@12 448 <programlisting format="linespecific">
michael@12 449 ...
michael@12 450 if (is_from_user_enum()) {
michael@12 451 ....
michael@12 452 };
michael@12 453 ...
michael@12 454 </programlisting>
michael@12 455 </example>
michael@12 456 </section>
michael@12 457 </section>
michael@12 458 </chapter>
michael@12 459

mercurial