Merge pull request #2326 from NGSegovia/keepalive/first_check_on_start
[sip-router] / src / modules / keepalive / README
1 KeepAlive Module
2
3 Guillaume Bour
4
5    <guillaume@bour.cc>
6
7 Yasin CANER
8
9    <caner_yaso@hotmail.com>
10
11 Edited by
12
13 Guillaume Bour
14
15    <guillaume@bour.cc>
16
17 Yasin CANER
18
19    <caner_yaso@hotmail.com>
20
21    Copyright © 2017 Guillaume Bour
22      __________________________________________________________________
23
24    Table of Contents
25
26    1. Admin Guide
27
28         1. Overview
29         2. Dependencies
30
31               2.1. Kamailio Modules
32               2.2. External Libraries or Applications
33               2.3. Parameters
34
35                     2.3.1. ping_interval (integer)
36                     2.3.2. destination (string)
37                     2.3.3. delete_counter(int)
38                     2.3.4. ping_from(string)
39
40               2.4. Functions
41
42                     2.4.1. ka_is_alive(destination)
43                     2.4.2. ka_add_destination(sip_uri)
44                     2.4.3. ka_del_destination(sip_uri)
45
46               2.5. RPC Commands
47
48                     2.5.1. keepalive.list
49                     2.5.2. keepalive.add
50                     2.5.3. keepalive.del
51                     2.5.4. keepalive.get
52                     2.5.5. keepalive.flush
53
54    2. Developer Guide
55
56         1. Available Functions
57
58               1.1. add_destination(uri, owner, flags, ping_interval,
59                       [statechanged_clb, response_clb, [user_attr]])
60
61               1.2. Examples
62
63    List of Examples
64
65    1.1. Set ping_interval parameter
66    1.2. Set destination parameter
67    1.3. Set delete_counter parameter
68    1.4. Set ping_from parameter
69    1.5. ka_is_alive() usage
70    1.6. ka_add_destination(sip_uri) usage
71    1.7. ka_del_destination(sip_uri) usage
72    1.8. keepalive.list RPC example
73    1.9. keepalive.add RPC example
74    1.10. keepalive.del RPC example
75    1.11. keepalive.get RPC example
76    1.12. keepalive.flush RPC example
77    2.1. Loading KeepAlive module's API from another module, adding a
78           destination to monitor & registering a callback
79
80 Chapter 1. Admin Guide
81
82    Table of Contents
83
84    1. Overview
85    2. Dependencies
86
87         2.1. Kamailio Modules
88         2.2. External Libraries or Applications
89         2.3. Parameters
90
91               2.3.1. ping_interval (integer)
92               2.3.2. destination (string)
93               2.3.3. delete_counter(int)
94               2.3.4. ping_from(string)
95
96         2.4. Functions
97
98               2.4.1. ka_is_alive(destination)
99               2.4.2. ka_add_destination(sip_uri)
100               2.4.3. ka_del_destination(sip_uri)
101
102         2.5. RPC Commands
103
104               2.5.1. keepalive.list
105               2.5.2. keepalive.add
106               2.5.3. keepalive.del
107               2.5.4. keepalive.get
108               2.5.5. keepalive.flush
109
110 1. Overview
111
112    This module performs destinations monitoring either for itself, or on
113    the behalf of other modules. The monitoring is done by sending SIP
114    OPTIONS requests, more or less in the same fashion as the dispatcher
115    module (which was the initial source for this module).
116
117    As an example of usage by other modules, see drouting, which was
118    enhanced to use this module to monitor its gateways.
119
120 2. Dependencies
121
122    2.1. Kamailio Modules
123    2.2. External Libraries or Applications
124    2.3. Parameters
125
126         2.3.1. ping_interval (integer)
127         2.3.2. destination (string)
128         2.3.3. delete_counter(int)
129         2.3.4. ping_from(string)
130
131    2.4. Functions
132
133         2.4.1. ka_is_alive(destination)
134         2.4.2. ka_add_destination(sip_uri)
135         2.4.3. ka_del_destination(sip_uri)
136
137    2.5. RPC Commands
138
139         2.5.1. keepalive.list
140         2.5.2. keepalive.add
141         2.5.3. keepalive.del
142         2.5.4. keepalive.get
143         2.5.5. keepalive.flush
144
145 2.1. Kamailio Modules
146
147    The following modules must be loaded before this module:
148      * tm - Transaction module
149
150 2.2. External Libraries or Applications
151
152    The following libraries or applications must be installed before
153    running Kamailio with this module loaded:
154      * none
155
156 2.3. Parameters
157
158 2.3.1. ping_interval (integer)
159
160    Define the interval (in seconds) ping requests are sent to destinations
161
162    Default value is 30 seconds.
163
164    Example 1.1. Set ping_interval parameter
165 ...
166 modparam("keepalive", "ping_interval", 10)
167 ...
168
169 2.3.2. destination (string)
170
171    Allows to statically define destinations you want to monitor
172
173    Example 1.2. Set destination parameter
174 ...
175 modparam("keepalive", "destination", "192.168.10.20")
176 modparam("keepalive", "destination", "sip.provider.com")
177 ...
178
179 2.3.3. delete_counter(int)
180
181    Unsuccesful attemps increase delete_counter. After passing it,
182    keepalive module doesn't try to send options requests. Ignored if it's
183    set to 0.
184
185    Default value is 5 .
186
187    Example 1.3. Set delete_counter parameter
188 ...
189 modparam("keepalive", "delete_counter", "5")
190 ...
191
192 2.3.4. ping_from(string)
193
194    Sets from header's uri.
195
196    Default value is "sip:keepalive@kamailio.org" .
197
198    Example 1.4. Set ping_from parameter
199 ...
200 modparam("keepalive", "ping_from", "sip:keepalive@kamailio.org")
201 ...
202
203 2.4. Functions
204
205 2.4.1.  ka_is_alive(destination)
206
207    Get destination status.
208
209    The Parameter destination is destination you want to check status
210
211    Returned value:
212      * 1 if destination is up
213      * 2 if destination is down
214      * -1 on error
215
216    This function can be used from ANY_ROUTE.
217
218    Example 1.5. ka_is_alive() usage
219 ...
220 if(ka_is_alive("192.168.10.20") == 1) {
221   // do stuff
222 };
223 ...
224
225 2.4.2.  ka_add_destination(sip_uri)
226
227    Adds destination sip/sips uri in memory list to keep alive .
228
229    Returned value:
230      * 1 - successful
231      * -1 - on error
232
233    This function can be used from
234    REQUEST_ROUTE,BRANCH_ROUTE,ONREPLY_ROUTE.
235
236    Example 1.6. ka_add_destination(sip_uri) usage
237 ...
238 $avp(duri1)="sip:192.168.1.10:5060;transport=tcp";
239 $avp(duri2)="sip:192.168.1.11:5061";
240 $avp(duri3)="sip:192.168.1.12"
241 ka_add_destination("$avp(duri3)");
242 ka_add_destination("sip:192.168.1.10:5060;transport=tcp");
243 ...
244
245 2.4.3.  ka_del_destination(sip_uri)
246
247    Deletes destination sip/sips uri in memory list .
248
249    Returned value:
250      * 1 - successful
251      * -1 - on error
252
253    This function can be used from ANY_ROUTE.
254
255    Example 1.7. ka_del_destination(sip_uri) usage
256 ...
257 $avp(duri1)="sip:192.168.1.10:5060;transport=tcp";
258 $avp(duri2)="sip:192.168.1.11:5061";
259 $avp(duri3)="sip:192.168.1.12"
260 ka_del_destination("$avp(duri3)");
261 ka_del_destination("sip:192.168.1.10:5060;transport=tcp");
262 ...
263
264 2.5. RPC Commands
265
266 2.5.1. keepalive.list
267
268    Lists destinations in memory.
269
270    Name: keepalive.list
271
272    Parameters: none
273
274    Example 1.8. keepalive.list RPC example
275                          keepalive.list
276
277 2.5.2. keepalive.add
278
279    Adds destination in memory.
280
281    Name: keepalive.add
282
283    Parameters: sip_uri listname
284
285    Example 1.9. keepalive.add RPC example
286                          keepalive.add sip:username@domain listname
287
288 2.5.3. keepalive.del
289
290    Deletes destination in memory.
291
292    Name: keepalive.del
293
294    Parameters: sip_uri listname
295
296    Example 1.10. keepalive.del RPC example
297                          keepalive.del sip:username@domain listname
298
299 2.5.4. keepalive.get
300
301    Gets destination in memory.
302
303    Name: keepalive.get
304
305    Parameters: sip_uri listname
306
307    Example 1.11. keepalive.get RPC example
308                          keepalive.get sip:username@domain listname
309
310 2.5.5. keepalive.flush
311
312    Deletes all destinations in memory.
313
314    Name: keepalive.flush
315
316    Parameters:
317
318    Example 1.12. keepalive.flush RPC example
319                          keepalive.flush
320
321 Chapter 2. Developer Guide
322
323    Table of Contents
324
325    1. Available Functions
326
327         1.1. add_destination(uri, owner, flags, ping_interval,
328                 [statechanged_clb, response_clb, [user_attr]])
329
330         1.2. Examples
331
332    The KeepAlive module provides an internal API to be used by other
333    Kamailio modules. This API offers support for destinations monitoring.
334
335    For internal (non-script) usage, the KeepAlive module offers to other
336    module the possibility to register callback functions to be executed
337    for each destination's status change.
338
339 1. Available Functions
340
341    1.1. add_destination(uri, owner, flags, ping_interval,
342           [statechanged_clb, response_clb, [user_attr]])
343
344    1.2. Examples
345
346 1.1.  add_destination(uri, owner, flags, ping_interval, [statechanged_clb,
347 response_clb, [user_attr]])
348
349    This function registers a new destination to monitor. Monitoring of the
350    destination starts as soon as it returns with success (0 value).
351
352    Meaning of the parameters is as follows:
353      * uri (string) - address of destination to monitor. Valid format is
354        [proto:]ip[:port], with:
355           + proto being one of sip or sips (SIP over TLS). If omitted, sip
356             is used by default
357           + port being optional (using default standard port, 5060 for sip
358             and 5061 for sips)
359      * owner (string) - module name “owning” the destination (for
360        information purpose)
361      * flags (integer) - destination flags (unused for now, use 0 value)
362      * ping_interval (integer) - Pinging interval in seconds for this
363        destination
364      * statechanged_clb (ka_statechanged_f, optional) - callback function,
365        executed on destination's state change.
366        The callback function is of type void (*ka_statechanged_f)(str
367        *uri, int state, void *user_attr);. Use NULL to set no callback.
368        destination's state value is one of:
369           + 0 - unknown state (this is the destination state at first,
370             waiting first ping replies or timeout)
371           + 1 - destination is UP
372           + 2 - destination is DOWN
373      * response_clb (ka_response_f, optional) - callback function,
374        executed on destination's response provided.
375        The callback function is of type void (*ka_response_f)(str *uri,
376        struct tmcb_params *ps, void *user_attr);. Use NULL to set no
377        callback.
378        ps is a pack structure with all params passed to callback function.
379        Defined in t_hooks.h
380      * user_attr (void * pointer, optional) - If any callback function is
381        setup, this parameter will be forwarded to it (or both callbacks in
382        both are defined), as last parameter. Use NULL to set no user_attr
383        parameter.
384
385    Returned values:
386      * 0 if ok
387      * -1 if an error occurred
388
389 1.2. Examples
390
391    Example 2.1. Loading KeepAlive module's API from another module, adding
392    a destination to monitor & registering a callback
393 ...
394 #include "../keepalive/api.h"
395 ...
396 keepalive_api_t ka_api;
397 ...
398 ...
399 /* loading keepalive API */
400 if (bind_keepalive( &ka_api ) != 0) {
401     LM_ERR("can't load KeepAlive API\n");
402     goto error;
403 }
404 ...
405 ...
406 /* callback function (on state changed) */
407 void my_state_changed_clb(str uri, int state, void *user_attr) {
408         printf("%.*s new state is: %d\n", uri.len, uri.str, state)
409 }
410
411 /* callback function (on each response received) */
412 void my_response_clb(str *uri, struct tmcb_params *ps, void *user_attr) {
413         printf("response [%d] from %.*s\n", ps->code, uri.len, uri.str)
414 }
415
416 if (ka_api.add_destination(dest, owner, 0, 60, my_state_changed_clb,
417                                 my_response_clb, NULL) != 0) {
418     LM_ERR("can't add destination\n");
419     goto error;
420 }
421 ...