lost: doc edits
[kamailio] / src / modules / lost / doc / lost_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         <title>&adminguide;</title>
14         <section>
15         <title>Overview</title>
16         <para>
17         SIP requests may be forwarded based on a location provided with the
18         request or retrieved from a specific location server using an identity
19         (HELD). This module implements the basic functionality to get or parse
20         location information (civic and geodetic) and to query a mapping service
21         (LOST) in order to get next hop based on location and service urn either
22         specified or provided with the request. 
23         </para>
24         <para>
25         This module implements protocol functions that use the http_client api
26         to fetch data from external LOST and HELD servers. The module is using
27         the http_client concept of "connections" to define properties of HTTP
28         sessions. A connection has one or multiple servers and a set of settings
29         that apply to the specific connection.
30         </para>
31         <para>
32         The function lost_held_query allows &kamailio; to assemble a HELD
33         locationRequest as defined in RFC6155
34         (<ulink url="https://tools.ietf.org/html/rfc6155"/>) to query location
35         information represented as PIDF-LO for a given identity (in most cases
36         a SIP URI). The identity may be a specific parameter or taken from the
37         P-Asserted-Identity or From header. The locationRequest response is
38         parsed and represented as PIDF-LO and location URI to dereference
39         location via HTTP(S).
40         </para>
41         <para>
42         The function lost_query allows &kamailio; to assemble a LOST
43         findService request  as defined in RFC5222
44         (<ulink url="https://tools.ietf.org/html/rfc5255"/>) to query 
45         routing information for a given (geodetic or civic) location and a service
46         URN. Both, PIDF-LO and service URN may be provided as function parameter,
47         or are taken from the request message if applicable. The findServiceResponse
48         is parsed and represented as display name and SIP URI typically used as next
49         hop in a Route header.
50         </para>
51         <para>
52         The http_client module use the CURL library setting up connections.
53         The CURL library by default use the system configured DNS resolver,
54         not the Kamailio resolver.
55         </para>
56         <para>
57         The module is limited to using HTTP and HTTPS protocols.
58         </para>
59         </section>
60         <section>
61             <title>Dependencies</title>
62             <section>
63                     <title>&kamailio; Modules</title>
64                     <para>
65                         The following modules must be loaded before this module:
66                 <itemizedlist>
67                 <listitem><para>
68                 HTTP_CLIENT - the http_client module should be
69                 loaded first in order to initialize connections properly.
70                 </para></listitem>
71                 <listitem><para>
72                 TLS - if you use TLS connections (https) the tls module
73                 should be loaded first in order to initialize &openssl; properly.
74                 </para></listitem>
75                             </itemizedlist>
76             </para>
77         </section>
78         <section>
79             <title>External Libraries or Applications</title>
80             <para>
81             The following libraries or applications must be
82             installed before running &kamailio; with this module loaded:
83                 <itemizedlist>
84                 <listitem>
85                 <para>
86                     <emphasis>&libcurl;</emphasis>
87                 </para>
88                 </listitem>
89                 <listitem>
90                 <para>
91                     <emphasis>libxml2</emphasis>
92                 </para>
93                 </listitem>
94                 </itemizedlist>
95             </para>
96         </section>
97         </section>
98         <section id="lost.p.general">
99                 <title>Parameters</title>
100         <para>
101         Besides parameters listed, this module uses <emphasis>http_client</emphasis>
102         therefore according parameters may apply.
103         </para>
104         <section id="lost.p.exact_type">
105             <title><varname>exact_type</varname> (int)</title>
106             <para>
107             Indicates to the location server that the contents of the "location_type"
108             parameter must be strictly followed. Values are 0 (false) or 1 (true).
109             </para>
110             <para>
111             Default: 0 (false)
112             </para>
113             <example>
114             <title>Set <varname>exact_type</varname> parameter</title>
115                 <programlisting format="linespecific">
116     ...
117     modparam("lost", "exact_type", 1)
118     ...
119                 </programlisting>
120             </example>
121         </section>
122         <section id="lost.p.response_time">
123             <title><varname>response_time</varname> (int)</title>
124             <para>
125             A time value indicating to the location server how long the client is
126             prepared to wait for a response.
127             </para>
128             <para>
129             The value is expressed as a non-negative integer in units of
130             milliseconds. Note: The time value is indicative only. 
131             </para>
132             <para>
133             Default: 0 (response time not set)
134             </para>
135             <example>
136             <title>Set <varname>response_time</varname> parameter</title>
137                 <programlisting format="linespecific">
138     ...
139     modparam("lost", "response_time", 5000)
140     ...
141                 </programlisting>
142             </example>
143         </section>
144         <section id="lost.p.location_type">
145             <title><varname>location_type</varname> (string)</title>
146             <para>
147             The "locationType" element contains a list of types that are requested.
148             Values are "any", "geodetic", "civic" or "locationURI" and combinations.
149             </para>
150                         <itemizedlist>
151                 <listitem><para>
152                     <emphasis>any</emphasis> - returns location information in all forms available
153                 </para></listitem>
154                 <listitem><para>
155                     <emphasis>geodetic</emphasis> - returns a location by value in the form of a geodetic location
156                 </para></listitem>
157                 <listitem><para>
158                     <emphasis>civic</emphasis> - returns a location by value in the form of a civic address
159                 </para></listitem>
160                 <listitem><para>
161                     <emphasis>locationURI</emphasis> - returns a set of location URIs (location by reference)
162                 </para></listitem>
163             </itemizedlist>
164             <para>
165             Default: "geodetic locationURI".
166             </para>
167             <example>
168             <title>Set <varname>location_type</varname> parameter</title>
169                 <programlisting format="linespecific">
170     ...
171     modparam("http_client", "location_type, "civic geodetic locationURI")
172     ...
173                 </programlisting>
174             </example>
175         </section>
176         </section>
177         <section>
178             <title>Functions</title>
179                 <section id="lost.f.lost_held_query">
180                         <title>
181                                 <function moreinfo="none">lost_held_query(con, [id,] pidf-lo, url, error)</function>
182                         </title>
183                         <para>
184                         Sends a HELD locationRequest to a given connection. The device identity is either
185             specified, or the P-A-I header value, or the From header value.
186                 </para>
187                             <itemizedlist>
188                                     <listitem><para>
189                                                 <emphasis>con</emphasis> - the name of an existing
190                                                 HTTP connection, defined by a httpcon modparam
191                                     </para></listitem>
192                     <listitem><para>
193                                                 <emphasis>id</emphasis> - the device id used in the HELD
194                         locationRequest
195                     </para></listitem>
196                     <listitem><para>
197                                                 <emphasis>pidf-lo</emphasis> - the PIDF-LO returned in the
198                         HELD locationRequest response
199                     </para></listitem>
200                     <listitem><para>
201                                                 <emphasis>url</emphasis> - the location reference returned
202                         in the HELD locationRequest response - this reference may be
203                         added as Geolocation header value and forwarded downstream.
204                         Note: to work properly, it is required to include "locationURI"
205                         in the location_type parameter.
206                     </para></listitem>
207                     <listitem><para>
208                                                 <emphasis>error</emphasis> - any error code returned in the
209                         HELD locationRequest response
210                     </para></listitem>
211                             </itemizedlist>
212                         <para>
213                         The return value is 200 on success, 400 if an internal error occured, or 500 if an
214             error code is returned in the HELD locationRequest response.
215                 </para>
216                         <para>
217                         This function can be used from REQUEST_ROUTE,
218                         ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
219                         </para>
220                         <example>
221                                 <title><function>lost_held_query()</function> usage</title>
222                                 <programlisting format="linespecific">
223 ...
224 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
225 ...
226 # HELD location request
227 $var(id) = "sip:alice@atlanta";
228 $var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "$var(err)");
229 xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$var(pidf)");
230 ...
231 $var(res) = lost_held_query("heldsrv", "$var(pidf)", "$var(url)"", "$var(err)");
232 xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$var(pidf)\n");
233 ...
234                                 </programlisting>
235                         </example>
236                 </section>
237                 <section id="lost.f.lost_query">
238                         <title>
239                                 <function moreinfo="none">lost_query(con, [pidf-lo, urn,] uri, name, error)</function>
240                         </title>
241                         <para>
242                         Sends a LOST findService request to a given connection. PIDF-LO and URN are either specified,
243             or, if omitted, parsed from the message body (PIDF-LO) and request line (URN). Either "pidf-lo"
244             or "urn" can be set to an empty string in order to be ignored. 
245                 </para>
246                         <itemizedlist>
247                 <listitem><para>
248                     <emphasis>con</emphasis> - the name of an existing
249                     HTTP connection defined by a httpcon modparam
250                 </para></listitem>
251                 <listitem><para>
252                     <emphasis>pidf-lo</emphasis> - the PIDF-LO used to create the
253                     LOST findService request
254                 </para></listitem>
255                 <listitem><para>
256                     <emphasis>urn</emphasis> - the URN used to create the
257                     LOST findService request
258                 </para></listitem>
259                 <listitem><para>
260                     <emphasis>uri</emphasis> - the SIP uri returned in the
261                     LOST findServiceResponse
262                 </para></listitem>
263                 <listitem><para>
264                     <emphasis>name</emphasis> - the display name returned in the
265                     LOST findServiceResponse
266                 </para></listitem>
267                 <listitem><para>
268                     <emphasis>error</emphasis> - any error code returned in the
269                     LOST findServiceResponse
270                 </para></listitem>
271                         </itemizedlist>
272                         <para>
273                         The return value is 200 on success, 400 if an internal error occured, or 500 if an
274             error code is returned in the LOST findServiceResponse.
275                 </para>
276                         <para>
277                         This function can be used from REQUEST_ROUTE,
278                         ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
279                         </para>
280                         <example>
281                                 <title><function>lost()</function> usage</title>
282                                 <programlisting format="linespecific">
283 ...
284 modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
285 modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");
286 ...
287 # HELD location request
288 $var(id) = "sip:alice@atlanta";
289 $var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "$var(err)");
290 ...
291 # LOST findService request - pidf-lo and urn as parameter
292 $var(id) = "urn:service:sos";
293 $var(res) = lost_query("lostsrv", "$var(pidf)", "$var(urn)", "$var(uri)", "$var(name)", "$var(err)");
294 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name)\n");
295 ...
296 # LOST findService request - pidf-lo as parameter, urn taken from request line
297 $var(res) = lost_query("lostsrv", "$var(pidf)", "", "$var(uri)", "$var(name)", "$var(err)");
298 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name)\n");
299 ...
300 # LOST findService request - urn as parameter, pidf-lo taken from message body
301 $var(res) = lost_query("lostsrv", "", "$var(urn)", "$var(uri)", "$var(name)", "$var(err)");
302 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name\n");
303 ...
304 # LOST findService request - pidf-lo and urn taken from message
305 $var(res) = lost_query("lostsrv", "$var(uri)", "$var(name)", "$var(err)");
306 xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(name)\n");
307 ...
308                                 </programlisting>
309                         </example>
310                 </section>
311
312     </section>
313     <section id="lost.s.counters">
314             <title>Counters</title>
315         <para>
316             This module has no specific counters but uses http_client therefore
317             according counters may apply.
318         </para>
319         </section>
320
321     <section id="lost.s.remarks">
322         <title>Remarks</title>
323         <para>
324             Note: libcurl leak in CentOS 6 - this module uses libcurl library
325             (via http_client) and in case if you are using CentOS 6, be aware that
326             standard libcurl-7.19.7-52 has a memory leak. To fix this memory, install
327             libcurl from city-fan repository. More details at:
328             <ulink url="https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6"></ulink>.
329         </para>
330         <para>
331             Note: http_client_query exported by the http_client API returns by default the first line of
332             the HTTP response, but the lost module requires the complete response message, otherwise
333             dereferencing location via the HTTP URL provided with the Geolocation header causes an error.
334             Therefore, to work properly, it is required to set the http_client module parameter query_result
335             to 0. More details at:
336             <ulink url="https://www.kamailio.org/docs/modules/devel/modules/http_client.html#http_client.p.query_result"></ulink>.
337         </para>
338         <para>
339             Note: to test the module with a mapping service (LOST), an API key may be requested under the
340             following link (search for "GET ACCESS"):
341             <ulink url="https://gridgears.at/"></ulink>.
342         </para>
343     </section>
344 </chapter>