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