src/modules/lost/README
2ab96d98
 LOST Module
 
 Wolfgang Kampichler
 
    Frequentis AG
    DEC112 (funded by netidee)
 
 Edited by
 
 Wolfgang Kampichler
 
7dea3178
    Copyright © 2018-2020 Wolfgang Kampichler
2ab96d98
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
         3. Parameters
7c879b17
 
               3.1. exact_type (int)
               3.2. response_time (int)
               3.3. location_type (string)
 
2ab96d98
         4. Functions
 
               4.1. lost_held_query(con, [id,] pidf-lo, url, error)
               4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
 
         5. Counters
         6. Remarks
 
    List of Examples
 
7c879b17
    1.1. Set exact_type parameter
    1.2. Set response_time parameter
    1.3. Set location_type parameter
    1.4. lost_held_query() usage
    1.5. lost() usage
2ab96d98
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Parameters
7c879b17
 
         3.1. exact_type (int)
         3.2. response_time (int)
         3.3. location_type (string)
 
2ab96d98
    4. Functions
 
         4.1. lost_held_query(con, [id,] pidf-lo, url, error)
         4.2. 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 with the
    request or retrieved from a specific location server using an identity
    (HELD). This module implements the basic functionality to get or parse
b514d330
    location information (civic and geodetic) and to query a mapping
    service (LOST) in order to get next hop based on location and service
    urn either specified or provided with the request.
2ab96d98
 
    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_query allows Kamailio to assemble a LOST findService
    request as defined in RFC5222 (https://tools.ietf.org/html/rfc5255) to
b514d330
    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 parameter, or are taken from the request message if
7c879b17
    applicable. The findServiceResponse is parsed and represented as
    display name and SIP URI typically used as next hop in a Route header.
2ab96d98
 
    The http_client module use the CURL library setting up connections. The
7c879b17
    CURL library by default use the system configured DNS resolver, not the
    Kamailio resolver.
2ab96d98
 
    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 in
        order 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
 
7c879b17
    3.1. exact_type (int)
    3.2. response_time (int)
    3.3. location_type (string)
 
    Besides parameters listed, this module uses http_client therefore
2ab96d98
    according parameters may apply.
 
7c879b17
 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 indicating to the location server how long the client is
    prepared to wait for a response.
 
    The value is expressed as a non-negative integer in units of
    milliseconds. Note: The time value is indicative only.
 
    Default: 0 (response time not set)
 
    Example 1.2. Set response_time parameter
     ...
     modparam("lost", "response_time", 5000)
     ...
 
 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("http_client", "location_type, "civic geodetic locationURI")
     ...
 
2ab96d98
 4. Functions
 
    4.1. lost_held_query(con, [id,] pidf-lo, url, error)
    4.2. 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.
7c879b17
      * con - the name of an existing HTTP connection, defined by a httpcon
        modparam
2ab96d98
      * 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
7dea3178
        and forwarded downstream. Note: to work properly, it is required to
de849323
        include "locationURI" in the location_type parameter.
2ab96d98
      * error - any error code returned in the HELD locationRequest
        response
 
    The return value is 200 on success, 400 if an internal error occured,
    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.
 
7c879b17
    Example 1.4. lost_held_query() usage
2ab96d98
 ...
 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_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 in order to be ignored.
7c879b17
      * con - the name of an existing HTTP connection defined by a httpcon
2ab96d98
        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 occured,
    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.
 
7c879b17
    Example 1.5. lost() usage
2ab96d98
 ...
 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: $
b514d330
 var(name)\n");
2ab96d98
 ...
 # 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: $
b514d330
 var(name)\n");
2ab96d98
 ...
 # 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: $
b514d330
 var(name\n");
2ab96d98
 ...
 # 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: $
b514d330
 var(name)\n");
2ab96d98
 ...
 
 5. Counters
 
0e4e0a16
    This module has no specific counters but uses http_client therefore
2ab96d98
    according counters may apply.
 
 6. Remarks
 
    Note: libcurl leak in CentOS 6 - this module uses libcurl library (via
    http_client) and in case if 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
7dea3178
    -centos6.
2ab96d98
 
4acc8aa7
    Note: http_client_query exported by the http_client API returns by
7c879b17
    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.
7dea3178
 
    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/.