/
README
309 lines (237 loc) · 10.6 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
LOST Module
Wolfgang Kampichler
Frequentis AG
DEC112 (funded by netidee)
Edited by
Wolfgang Kampichler
Copyright © 2018-2020 Wolfgang Kampichler
__________________________________________________________________
Table of Contents
1. Admin Guide
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. exact_type (int)
3.2. response_time (int)
3.3. location_type (string)
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. 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
Chapter 1. Admin Guide
Table of Contents
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. exact_type (int)
3.2. response_time (int)
3.3. location_type (string)
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 (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.
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 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
applicable. The findServiceResponse is parsed and represented as
display 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 resolver, 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
3.1. exact_type (int)
3.2. response_time (int)
3.3. location_type (string)
Besides parameters listed, this module uses http_client therefore
according parameters may apply.
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")
...
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, defined 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. Note: to work properly, it is required to
include "locationURI" in the location_type parameter.
* 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.4. 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 defined 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.5. 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(name)\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(name)\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(name\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(name)\n");
...
5. Counters
This module has no specific counters but uses http_client therefore
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 by
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.
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/.