lost: initial checkin of README file
[sip-router] / src / modules / lost / README
1
2 LOST Module
3
4 Wolfgang Kampichler
5
6    Frequentis AG
7    DEC112 (funded by netidee)
8
9 Edited by
10
11 Wolfgang Kampichler
12
13    Copyright © 20018-2019 Wolfgang Kampichler
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Dependencies
22
23               2.1. Kamailio Modules
24               2.2. External Libraries or Applications
25
26         3. Parameters
27         4. Functions
28
29               4.1. lost_held_query(con, [id,] pidf-lo, url, error)
30               4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
31
32         5. Counters
33         6. Remarks
34
35    List of Examples
36
37    1.1. lost_held_query() usage
38    1.2. lost() usage
39
40 Chapter 1. Admin Guide
41
42    Table of Contents
43
44    1. Overview
45    2. Dependencies
46
47         2.1. Kamailio Modules
48         2.2. External Libraries or Applications
49
50    3. Parameters
51    4. Functions
52
53         4.1. lost_held_query(con, [id,] pidf-lo, url, error)
54         4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
55
56    5. Counters
57    6. Remarks
58
59 1. Overview
60
61    SIP requests may be forwarded based on a location provided with the
62    request or retrieved from a specific location server using an identity
63    (HELD). This module implements the basic functionality to get or parse
64    location information and to query a mapping service (LOST) in order to
65    get next hop based on location and service urn either specified or
66    provided with the request.
67
68    This module implements protocol functions that use the http_client api
69    to fetch data from external LOST and HELD servers. The module is using
70    the http_client concept of "connections" to define properties of HTTP
71    sessions. A connection has one or multiple servers and a set of
72    settings that apply to the specific connection.
73
74    The function lost_held_query allows Kamailio to assemble a HELD
75    locationRequest as defined in RFC6155
76    (https://tools.ietf.org/html/rfc6155) to query location information
77    represented as PIDF-LO for a given identity (in most cases a SIP URI).
78    The identity may be a specific parameter or taken from the
79    P-Asserted-Identity or From header. The locationRequest response is
80    parsed and represented as PIDF-LO and location URI to dereference
81    location via HTTP(S).
82
83    The function lost_query allows Kamailio to assemble a LOST findService
84    request as defined in RFC5222 (https://tools.ietf.org/html/rfc5255) to
85    query routing information for a given (geodetic) location and a service
86    URN. Both, PIDF-LO and service URN may be provided as function
87    parameter, or are taken from the request message if applicable. The
88    findServiceResponse is parsed and represented asdisplay name and SIP
89    URI typically used as next hop in a Route header.
90
91    The http_client module use the CURL library setting up connections. The
92    CURL library by default use the system configured DNS resolvers, not
93    the Kamailio resolver.
94
95    The module is limited to using HTTP and HTTPS protocols.
96
97 2. Dependencies
98
99    2.1. Kamailio Modules
100    2.2. External Libraries or Applications
101
102 2.1. Kamailio Modules
103
104    The following modules must be loaded before this module:
105      * HTTP_CLIENT - the http_client module should be loaded first in
106        order to initialize connections properly.
107      * TLS - if you use TLS connections (https) the tls module should be
108        loaded first in order to initialize OpenSSL properly.
109
110 2.2. External Libraries or Applications
111
112    The following libraries or applications must be installed before
113    running Kamailio with this module loaded:
114      * libcurl
115      * libxml2
116
117 3. Parameters
118
119    This module has no specific paramater but uses http_client therfore
120    according parameters may apply.
121
122 4. Functions
123
124    4.1. lost_held_query(con, [id,] pidf-lo, url, error)
125    4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
126
127 4.1.  lost_held_query(con, [id,] pidf-lo, url, error)
128
129    Sends a HELD locationRequest to a given connection. The device identity
130    is either specified, or the P-A-I header value, or the From header
131    value.
132      * con - the name of an existing HTTP connection, definied by a
133        httpcon modparam
134      * id - the device id used in the HELD locationRequest
135      * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
136      * url - the location reference returned in the HELD locationRequest
137        response - this reference may be added as Geolocation header value
138        and forwarded downstream
139      * error - any error code returned in the HELD locationRequest
140        response
141
142    The return value is 200 on success, 400 if an internal error occured,
143    or 500 if an error code is returned in the HELD locationRequest
144    response.
145
146    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
147    FAILURE_ROUTE, and BRANCH_ROUTE.
148
149    Example 1.1. lost_held_query() usage
150 ...
151 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
152 ...
153 # HELD location request
154 $var(id) = "sip:alice@atlanta";
155 $var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "
156 $var(err)");
157 xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$va
158 r(pidf)");
159 ...
160 $var(res) = lost_held_query("heldsrv", "$var(pidf)", "$var(url)"", "$var(err)");
161 xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$va
162 r(pidf)\n");
163 ...
164
165 4.2.  lost_query(con, [pidf-lo, urn,] uri, name, error)
166
167    Sends a LOST findService request to a given connection. PIDF-LO and URN
168    are either specified, or, if omitted, parsed from the message body
169    (PIDF-LO) and request line (URN). Either "pidf-lo" or "urn" can be set
170    to an empty string in order to be ignored.
171      * con - the name of an existing HTTP connection definied by a httpcon
172        modparam
173      * pidf-lo - the PIDF-LO used to create the LOST findService request
174      * urn - the URN used to create the LOST findService request
175      * uri - the SIP uri returned in the LOST findServiceResponse
176      * name - the display name returned in the LOST findServiceResponse
177      * error - any error code returned in the LOST findServiceResponse
178
179    The return value is 200 on success, 400 if an internal error occured,
180    or 500 if an error code is returned in the LOST findServiceResponse.
181
182    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
183    FAILURE_ROUTE, and BRANCH_ROUTE.
184
185    Example 1.2. lost() usage
186 ...
187 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
188 modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");
189 ...
190 # HELD location request
191 $var(id) = "sip:alice@atlanta";
192 $var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "
193 $var(err)");
194 ...
195 # LOST findService request - pidf-lo and urn as parameter
196 $var(id) = "urn:service:sos";
197 $var(res) = lost_query("lostsrv", "$var(pidf)", "$var(urn)", "$var(uri)", "$var(
198 name)", "$var(err)");
199 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
200 var(uri)\n");
201 ...
202 # LOST findService request - pidf-lo as parameter, urn taken from request line
203 $var(res) = lost_query("lostsrv", "$var(pidf)", "", "$var(uri)", "$var(name)", "
204 $var(err)");
205 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
206 var(uri)\n");
207 ...
208 # LOST findService request - urn as parameter, pidf-lo taken from message body
209 $var(res) = lost_query("lostsrv", "", "$var(urn)", "$var(uri)", "$var(name)", "$
210 var(err)");
211 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
212 var(uri)\n");
213 ...
214 # LOST findService request - pidf-lo and urn taken from message
215 $var(res) = lost_query("lostsrv", "$var(uri)", "$var(name)", "$var(err)");
216 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $
217 var(uri)\n");
218 ...
219
220 5. Counters
221
222    This module has no specific counters but uses http_client therfore
223    according counters may apply.
224
225 6. Remarks
226
227    Note: libcurl leak in CentOS 6 - this module uses libcurl library (via
228    http_client) and in case if you are using CentOS 6, be aware that
229    standard libcurl-7.19.7-52 has a memory leak. To fix this memory,
230    install libcurl from city-fan repository. More details at:
231    https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in
232    -centos6
233
234    Note: http_client_query exported by the http_client API returns the
235    first line of the HTTP response (query_params.oneline = 1), but the
236    lost module requires the complete response message, which requires
237    query_params.oneline set to 0. In the case lost_query is used with the
238    default http_client API, dereferencing location via HTTP provided with
239    the Geolocation header causes an error.