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