Table of Contents
List of Examples
exact_type parameterresponse_time parameterlocation_type parameterpost_request parameterlocation_profile parameterlocation_3d parametergeoheader_type parametergeoheader_order parameterrecursion parameterverbose parameterlost_held_query() usagelost_held_dereference() usagelost() usageTable of Contents
SIP requests may be forwarded based on a location provided by the request or retrieved from a specific location server using an identity (HELD). This module implements the basic functionality to get or parse location information (civic and geodetic) and to query a mapping service (LOST) to get the next hop based on location and service urn either specified or provided with the request.
This module implements protocol functions that use the http_client API to fetch data from external LOST and HELD servers. The module is using the http_client concept of "connections" to define properties of HTTP sessions. A connection has one or multiple servers and a set of settings that apply to the specific connection.
The function lost_held_query allows Kamailio to assemble a HELD locationRequest as defined in RFC6155 (https://tools.ietf.org/html/rfc6155) to query location information represented as PIDF-LO for a given identity (in most cases a SIP URI). The identity may be a specific parameter or taken from the P-Asserted-Identity or From header. The locationRequest response is parsed and represented as PIDF-LO and location URI to dereference location via HTTP(S).
The function lost_held_dereference allows Kamailio to assemble a HELD dereference request as defined in RFC6155 (https://tools.ietf.org/html/rfc6753) to dereference location information represented as PIDF-LO for a given URL. Required parameters are an URL, responseTime, and responseType. The response is represented as PIDF-LO.
The function lost_query allows Kamailio to assemble a LOST findService request as defined in RFC5222 (https://tools.ietf.org/html/rfc5255) to query routing information for a given (geodetic or civic) location and a service URN. Both, PIDF-LO and service URN may be provided as function parameters, or are taken from the request message if applicable. The findServiceResponse is parsed and represented as display name and SIP URI typically used as the next hop in a Route header.
The http_client module uses the CURL library to set up connections. The CURL library by default uses the system-configured DNS resolver, not the Kamailio resolver.
The module is limited to using HTTP and HTTPS protocols.
The following modules must be loaded before this module:
HTTP_CLIENT - the http_client module should be loaded first to initialize connections properly.
TLS - if you use TLS connections (https) the TLS module should be loaded first in order to initialize OpenSSL properly.
The following libraries or applications must be installed before running Kamailio with this module loaded:
libxml2
Besides parameters listed, this module uses http_client therefore appropriate module parameters may apply.
Indicates to the location server that the contents of the "location_type" parameter must be strictly followed. Values are 0 (false) or 1 (true).
Default: 0 (false)
A time value informs the location server how long the client is prepared to wait for a response.
The value is expressed as an integer, either -1 'emergencyDispatch', 0 'emergencyRouting', a non-negative integer (>0) in units of milliseconds. Note: The time value is indicative only.
Default: 0 ('emergencyRouting')
The "locationType" element contains a list of types that are requested. Values are "any", "geodetic", "civic" or "locationURI" and combinations.
any - returns location information in all forms available
geodetic - returns a location by value in the form of a geodetic location
civic - returns a location by value in the form of a civic address
locationURI - returns a set of location URIs (location by reference)
Default: "geodetic locationURI".
Example 1.3. Set location_type parameter
...
modparam("lost", "location_type", "civic geodetic locationURI")
...
Dereferencing the location can be done using either the HTTP GET or POST method. This parameter globally defines whether only HTTP POST method should be used. Values are 0 (GET) or 1 (POST).
Default: 0 (GET)
A Presence Information Data Format Location Object (PIDF-LO) may contain geodetic or civic location profile or combinations. A LoST findService contains only one location, which is selected via this parameter as follows:
0 - takes the first location of any type
1 - takes the last location of any type
2 - takes the first geodetic location
3 - takes the first civic location
Default: 0 (first).
A Presence Information Data Format Location Object (PIDF-LO) may contain one of the shape types as listed in RFC5491 (https://tools.ietf.org/html/rfc5491). A LoST findService request currently contains only a profile for two-dimensional geodetic location information, which is the default setting for this parameter. The parameter can be set to 1 if a LoST server supports 3d, otherwise a 3d location is reduced to 2d by the module.
0 - two-dimensional (2d) shape representations only
1 - three-dimensional (3d) volume representations allowed
Default: 0 (2d representations).
A Geolocation header may include a list of locationValues pointing to either a Presence Information Data Format Location Object (PIDF-LO) in the SIP body using a content-indirection (cid:) URI per RFC4483 (https://tools.ietf.org/html/rfc4483), or an http(s) URI pointing to an external source. This parameter supports filtering of the following types:
0 (any) - any URI (first or last)
1 (cid) - cid URI (aka Location-by-Value)
2 (http) - http URI (aka Location-by-Reference)
3 (https) - https URI (aka Location-by-Reference)
Default: 0 (any)
A Geolocation header may include a list of locationValues. This parameter sets the order of the URI used to retrieve the location information, either the first element of a certain type or the last. Values are 0 (first) or 1 (last).
Default: 0 (first)
A Geolocation header may include a list of locationValues. This parameter sets the order of the URI used to retrieve the location information, either the first element of a certain type or the last. Values are 0 (first) or 1 (last).
Default: 1 (allowed)
Detailed output of LoST findService, redirect or error response as shown below. Values are 0 (disabled) or 1 (enabled).
### LOST expires: [2031-01-27T14:54:21+00:00]
### LOST lastUpdated: [2021-01-29T14:54:21+00:00]
### LOST source: [ecrf.demo.gridgears.xx]
### LOST sourceId: [06ac5b1c-d6c8-42bd-a667-5d1b90bb3d95]
### LOST displayName: [Polizeinotruf (de)]
### LOST serviceNumber: [112]
### LOST service: [urn:service:sos]
### LOST uri: [sip:112@demo.dec112.xx]
### LOST via: [ecrf.demo.gridgears.xx]
Default: 0
Sends a HELD locationRequest to a given connection. The device identity is either specified, or the P-A-I header value, or the From header value.
con - the name of an existing HTTP connection, defined by a httpcon modparam
id - the device id used in the HELD locationRequest
pidf-lo - the PIDF-LO returned in the HELD locationRequest response
url - the location reference returned in the HELD locationRequest response - this reference may be added as Geolocation header value and forwarded downstream. Note: to work properly, it is required to include "locationURI" in the location_type parameter.
error - any error code returned in the HELD response
The return value is 200 on success, 400 if an internal error occurred, or 500 if an error code is returned in the HELD locationRequest response.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
Example 1.11. lost_held_query() usage
...
modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
...
# HELD location request
$var(id) = "sip:alice@atlanta";
$var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "$var(err)");
xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$var(pidf)");
...
$var(res) = lost_held_query("heldsrv", "$var(pidf)", "$var(url)", "$var(err)");
xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$var(pidf)\n");
...
Sends a HELD POST locationRequest to a given URL. Attributes are responseTime and responseType. The locationType property "exact" is set to "false".
url - a URL received via Geolocation header to dereference location
rtime - the response time as defined
in Section 3.2, “response_time (int)”
rtype - the response type (location) as defined
in Section 3.3, “location_type (string)”
pidf-lo - the PIDF-LO returned in the HELD locationRequest response
error - any error code returned in the HELD response
The return value is 200..203 on success, 400 if an internal error occurred, or 500 if an error code is returned in the HELD response. Success codes in detail are as follows:
200 - received 200 OK, but neither location-info nor locationURI element found
201 - received 200 OK with locationURI (aka Location-by-Reference)
202 - received 200 OK with location-info element (aka Location-by-Value)
203 - received 200 OK with location-info and locationURI element
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
Example 1.12. lost_held_dereference() usage
...
# HELD location dereference
if ($hdr(Geolocation)=~"^<http.*$") {
$var(url) = $(hdr(Geolocation){s.select,0,;});
$var(res) = lost_held_dereference("$(var(url){s.unbracket})", "emergencyDispatch", "civic geodetic", "$var(pidf)", "$var(err)");
xlog("L_INFO", "HELD location dereference: Result code $var(res)\n$var(pidf)");
...
}
Sends a LOST findService request to a given connection. PIDF-LO and URN are either specified, or, if omitted, parsed from the message body (PIDF-LO) and request line (URN). Either "pidf-lo" or "urn" can be set to an empty string to be ignored.
con - the name of an existing HTTP connection defined by a httpcon modparam
pidf-lo - the PIDF-LO used to create the LOST findService request
urn - the URN used to create the LOST findService request
uri - the SIP uri returned in the LOST findServiceResponse
name - the display name returned in the LOST findServiceResponse
error - any error code returned in the LOST findServiceResponse
The return value is 200 on success, 400 if an internal error occurred, or 500 if an error code is returned in the LOST findServiceResponse.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
Example 1.13. lost() usage
...
modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");
...
# HELD location request
$var(id) = "sip:alice@atlanta";
$var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "$var(err)");
...
# LOST findService request - pidf-lo and urn as parameter
$var(id) = "urn:service:sos";
$var(res) = lost_query("lostsrv", "$var(pidf)", "$var(urn)", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name)\n");
...
# LOST findService request - pidf-lo as parameter, urn taken from request line
$var(res) = lost_query("lostsrv", "$var(pidf)", "", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name)\n");
...
# LOST findService request - urn as parameter, pidf-lo taken from message body
$var(res) = lost_query("lostsrv", "", "$var(urn)", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name\n");
...
# LOST findService request - pidf-lo and urn taken from message
$var(res) = lost_query("lostsrv", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name)\n");
...
This module has no specific counters but uses http_client therefore according counters may apply.
Note: libcurl leak in CentOS 6 - this module uses libcurl library (via http_client) and in case you are using CentOS 6, be aware that standard libcurl-7.19.7-52 has a memory leak. To fix this memory, install libcurl from city-fan repository. More details at: https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6.
Note: http_client_query exported by the http_client API returns by default the first line of the HTTP response, but the lost module requires the complete response message, otherwise dereferencing location via the HTTP URL provided with the Geolocation header causes an error. Therefore, to work properly, it is required to set the http_client module parameter query_result to 0. More details at: https://www.kamailio.org/docs/modules/devel/modules/http_client.html#http_client.p.query_result.
Note: to test the module with a mapping service (LOST), an API key may be requested under the following link (search for "GET ACCESS"): https://gridgears.at/.
Note: in case modparam "geoheader_type" is set to 2 (http), the module may use 3 (https) as a fallback and vice versa.