lost: initial checkin of README file
authorHenning Westerholt <hw@skalatan.de>
Fri, 16 Aug 2019 06:09:52 +0000 (08:09 +0200)
committerHenning Westerholt <hw@skalatan.de>
Fri, 16 Aug 2019 06:09:52 +0000 (08:09 +0200)
src/modules/lost/README [new file with mode: 0644]

diff --git a/src/modules/lost/README b/src/modules/lost/README
new file mode 100644 (file)
index 0000000..e3a2f18
--- /dev/null
@@ -0,0 +1,239 @@
+
+LOST Module
+
+Wolfgang Kampichler
+
+   Frequentis AG
+   DEC112 (funded by netidee)
+
+Edited by
+
+Wolfgang Kampichler
+
+   Copyright © 20018-2019 Wolfgang Kampichler
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+        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
+
+   1.1. lost_held_query() usage
+   1.2. 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
+   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
+   location information 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.
+
+   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
+   query routing information for a given (geodetic) 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 applicable. The
+   findServiceResponse is parsed and represented asdisplay name and SIP
+   URI typically used as next hop in a Route header.
+
+   The http_client module use the CURL library setting up connections. The
+   CURL library by default use the system configured DNS resolvers, 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 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
+
+   This module has no specific paramater but uses http_client therfore
+   according parameters may apply.
+
+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.
+     * con - the name of an existing HTTP connection, definied 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
+     * 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.
+
+   Example 1.1. 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_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.
+     * con - the name of an existing HTTP connection definied 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 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.
+
+   Example 1.2. 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(uri)\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(uri)\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(uri)\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(uri)\n");
+...
+
+5. Counters
+
+   This module has no specific counters but uses http_client therfore
+   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
+   -centos6
+
+   Note: http_client_query exported by the http_client API returns the
+   first line of the HTTP response (query_params.oneline = 1), but the
+   lost module requires the complete response message, which requires
+   query_params.oneline set to 0. In the case lost_query is used with the
+   default http_client API, dereferencing location via HTTP provided with
+   the Geolocation header causes an error.