Contributed Logic / file comparison
comparison: opensips/modules/enum/README
opensips/modules/enum/README
- changeset 19
- 3374f578f080
- parent 13
- b63f281afe6b
equal
deleted
inserted
replaced
| 2:bcbe0b63dee2 | -1:000000000000 |
|---|---|
| 1 Enum Module | |
| 2 | |
| 3 Juha Heinanen | |
| 4 | |
| 5 <jh@song.fi> | |
| 6 | |
| 7 Otmar Lendl | |
| 8 | |
| 9 <lendl@nic.at> | |
| 10 | |
| 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 __________________________________________________________ | |
| 16 | |
| 17 Table of Contents | |
| 18 | |
| 19 1. Admin Guide | |
| 20 | |
| 21 1.1. Overview | |
| 22 1.2. Dependencies | |
| 23 1.3. Exported Parameters | |
| 24 | |
| 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) | |
| 31 | |
| 32 1.4. Exported Functions | |
| 33 | |
| 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() | |
| 39 | |
| 40 List of Examples | |
| 41 | |
| 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 | |
| 54 | |
| 55 Chapter 1. Admin Guide | |
| 56 | |
| 57 1.1. Overview | |
| 58 | |
| 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. | |
| 72 | |
| 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!. | |
| 80 | |
| 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. | |
| 91 | |
| 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. | |
| 104 | |
| 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. | |
| 112 | |
| 113 Enum query returns 1 if the current Request URI was replaced | |
| 114 and -1 if not. | |
| 115 | |
| 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. | |
| 119 | |
| 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. | |
| 132 | |
| 133 To complete a ISN lookup on the user part of the Request-URI, | |
| 134 isn_query() is used instead of enum_query(). | |
| 135 | |
| 136 1.2. Dependencies | |
| 137 | |
| 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. | |
| 141 | |
| 142 1.3. Exported Parameters | |
| 143 | |
| 144 1.3.1. domain_suffix (string) | |
| 145 | |
| 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. | |
| 149 | |
| 150 Default value is "e164.arpa." | |
| 151 | |
| 152 Example 1.1. Setting domain_suffix module parameter | |
| 153 modparam("enum", "domain_suffix", "e1234.arpa.") | |
| 154 | |
| 155 1.3.2. tel_uri_params (string) | |
| 156 | |
| 157 A string whose contents is appended to each new tel URI in the | |
| 158 request as tel URI parameters. | |
| 159 | |
| 160 Note | |
| 161 | |
| 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. | |
| 165 | |
| 166 Default value is "" | |
| 167 | |
| 168 Example 1.2. Setting tel_uri_params module parameter | |
| 169 modparam("enum", "tel_uri_params", ";npdi") | |
| 170 | |
| 171 1.3.3. i_enum_suffix (string) | |
| 172 | |
| 173 The domain suffix to be used for i_enum_query() lookups. Can be | |
| 174 overridden by a parameter to i_enum_query. | |
| 175 | |
| 176 Default value is "e164.arpa." | |
| 177 | |
| 178 Example 1.3. Setting i_enum_suffix module parameter | |
| 179 modparam("enum", "i_enum_suffix", "e1234.arpa.") | |
| 180 | |
| 181 1.3.4. isn_suffix (string) | |
| 182 | |
| 183 The domain suffix to be used for isn_query() lookups. Can be | |
| 184 overridden by a parameter to isn_query. | |
| 185 | |
| 186 Default value is "freenum.org." | |
| 187 | |
| 188 Example 1.4. Setting isn_suffix module parameter | |
| 189 modparam("enum", "isn_suffix", "freenum.org.") | |
| 190 | |
| 191 1.3.5. branchlabel (string) | |
| 192 | |
| 193 This parameter determines which label i_enum_query() will use | |
| 194 to branch off to the infrastructure ENUM tree. | |
| 195 | |
| 196 Default value is ""i"" | |
| 197 | |
| 198 Example 1.5. Setting branchlabel module parameter | |
| 199 modparam("enum", "branchlabel", "i") | |
| 200 | |
| 201 1.3.6. bl_algorithm (string) | |
| 202 | |
| 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. | |
| 206 | |
| 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 | |
| 210 | |
| 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. | |
| 214 | |
| 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" | |
| 219 | |
| 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. | |
| 228 | |
| 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" | |
| 238 | |
| 239 Default value is "cc" | |
| 240 | |
| 241 Example 1.8. Setting the bl_algorithm module parameter | |
| 242 modparam("enum", "bl_algorithm", "txt") | |
| 243 | |
| 244 1.4. Exported Functions | |
| 245 | |
| 246 1.4.1. enum_query(["suffix"[,"service"]]) | |
| 247 | |
| 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. | |
| 251 | |
| 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. | |
| 255 | |
| 256 This function can be used from REQUEST_ROUTE. | |
| 257 | |
| 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 ... | |
| 279 | |
| 280 1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]]) | |
| 281 | |
| 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. | |
| 286 | |
| 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. | |
| 292 | |
| 293 This function can be used from REQUEST_ROUTE. | |
| 294 | |
| 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 ... | |
| 316 | |
| 317 1.4.3. i_enum_query(["suffix"[,"service"]]) | |
| 318 | |
| 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. | |
| 324 | |
| 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. | |
| 328 | |
| 329 1.4.4. isn_query(["suffix"[,"service"]]) | |
| 330 | |
| 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. | |
| 334 | |
| 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. | |
| 338 | |
| 339 This function can be used from REQUEST_ROUTE. | |
| 340 | |
| 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. | |
| 344 | |
| 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 ... | |
| 356 | |
| 357 1.4.5. is_from_user_enum() | |
| 358 | |
| 359 Checks if the user part of from URI is found in an enum lookup. | |
| 360 Returns 1 if yes and -1 if not. | |
| 361 | |
| 362 This function can be used from REQUEST_ROUTE. | |
| 363 | |
| 364 Example 1.12. is_from_user_enum usage | |
| 365 ... | |
| 366 if (is_from_user_enum()) { | |
| 367 .... | |
| 368 }; | |
| 369 ... |
