LOST Module

Wolfgang Kampichler

   Frequentis AG
   DEC112 (funded by netidee)

Edited by

Wolfgang Kampichler

   Copyright © 2018-2021 Wolfgang Kampichler
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. exact_type (int)
              3.2. response_time (int)
              3.3. location_type (string)
              3.4. post_request (int)
              3.5. location_profile (int)
              3.6. location_3d (int)
              3.7. geoheader_type (int)
              3.8. geoheader_order (int)
              3.9. recursion (int)
              3.10. verbose (int)

        4. Functions

              4.1. lost_held_query(con, [id,] pidf-lo, url, error)
              4.2. lost_held_dereference(url, rtime, rtype, pidf-lo,
                      error)

              4.3. lost_query(con, [pidf-lo, urn,] uri, name, error)

        5. Counters
        6. Remarks

   List of Examples

   1.1. Set exact_type parameter
   1.2. Set response_time parameter
   1.3. Set location_type parameter
   1.4. Set post_request parameter
   1.5. Set location_profile parameter
   1.6. Set location_3d parameter
   1.7. Set geoheader_type parameter
   1.8. Set geoheader_order parameter
   1.9. Set recursion parameter
   1.10. Set verbose parameter
   1.11. lost_held_query() usage
   1.12. lost_held_dereference() usage
   1.13. lost() usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. exact_type (int)
        3.2. response_time (int)
        3.3. location_type (string)
        3.4. post_request (int)
        3.5. location_profile (int)
        3.6. location_3d (int)
        3.7. geoheader_type (int)
        3.8. geoheader_order (int)
        3.9. recursion (int)
        3.10. verbose (int)

   4. Functions

        4.1. lost_held_query(con, [id,] pidf-lo, url, error)
        4.2. lost_held_dereference(url, rtime, rtype, pidf-lo, error)
        4.3. lost_query(con, [pidf-lo, urn,] uri, name, error)

   5. Counters
   6. Remarks

1. Overview

   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.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   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.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libcurl
     * libxml2

3. Parameters

   3.1. exact_type (int)
   3.2. response_time (int)
   3.3. location_type (string)
   3.4. post_request (int)
   3.5. location_profile (int)
   3.6. location_3d (int)
   3.7. geoheader_type (int)
   3.8. geoheader_order (int)
   3.9. recursion (int)
   3.10. verbose (int)

   Besides parameters listed, this module uses http_client therefore
   appropriate module parameters may apply.

3.1. exact_type (int)

   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)

   Example 1.1. Set exact_type parameter
    ...
    modparam("lost", "exact_type", 1)
    ...

3.2. response_time (int)

   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')

   Example 1.2. Set response_time parameter
    ...
    modparam("lost", "response_time", 0)
    ...

3.3. location_type (string)

   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")
    ...

3.4. post_request (int)

   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)

   Example 1.4. Set post_request parameter
    ...
    modparam("lost", "post_request", 1)
    ...

3.5. location_profile (int)

   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).

   Example 1.5. Set location_profile parameter
    ...
    modparam("lost", "location_profile, 2)
    ...

3.6. location_3d (int)

   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).

   Example 1.6. Set location_3d parameter
    ...
    modparam("lost", "location_3d, 1)
    ...

3.7. geoheader_type (int)

   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)

   Example 1.7. Set geoheader_type parameter
    ...
    modparam("lost", "geoheader_type", 1)
    ...

3.8. geoheader_order (int)

   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)

   Example 1.8. Set geoheader_order parameter
    ...
    modparam("lost", "geoheader_order", 0)
    ...

3.9. recursion (int)

   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)

   Example 1.9. Set recursion parameter
    ...
    modparam("lost", "recursion", 0)
    ...

3.10. verbose (int)

   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

   Example 1.10. Set verbose parameter
    ...
    modparam("lost", "verbose", 1)
    ...

4. Functions

   4.1. lost_held_query(con, [id,] pidf-lo, url, error)
   4.2. lost_held_dereference(url, rtime, rtype, pidf-lo, error)
   4.3. lost_query(con, [pidf-lo, urn,] uri, name, error)

4.1.  lost_held_query(con, [id,] pidf-lo, url, error)

   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$va
r(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$va
r(pidf)\n");
...

4.2.  lost_held_dereference(url, rtime, rtype, pidf-lo, error)

   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})", "emergencyDisp
atch", "civic geodetic", "$var(pidf)", "$var(err)");
    xlog("L_INFO", "HELD location dereference: Result code $var(res)\n$var(pidf)
");
...
}

4.3.  lost_query(con, [pidf-lo, urn,] uri, name, error)

   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");
...

5. Counters

   This module has no specific counters but uses http_client therefore
   according counters may apply.

6. Remarks

   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#ht
   tp_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.
