modules: readme files regenerated - keepalive ... [skip ci]
[sip-router] / src / modules / keepalive / README
1 KeepAlive Module
2
3 Guillaume Bour
4
5    <guillaume@bour.cc>
6
7 Edited by
8
9 Guillaume Bour
10
11    <guillaume@bour.cc>
12
13    Copyright © 2017 Guillaume Bour
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               2.3. Parameters
26
27                     2.3.1. ping_interval (integer)
28                     2.3.2. destination (string)
29
30               2.4. Functions
31
32                     2.4.1. is_alive(destination)
33
34    2. Developer Guide
35
36         1. Available Functions
37
38               1.1. add_destination(uri, owner, flags, [callback,
39                       [user_attr]])
40
41               1.2. Examples
42
43    List of Examples
44
45    1.1. Set ping_interval parameter
46    1.2. Set destination parameter
47    1.3. is_alive() usage
48    2.1. Loading KeepAlive module's API from another module, adding a
49           destination to monitor & registering a callback
50
51 Chapter 1. Admin Guide
52
53    Table of Contents
54
55    1. Overview
56    2. Dependencies
57
58         2.1. Kamailio Modules
59         2.2. External Libraries or Applications
60         2.3. Parameters
61
62               2.3.1. ping_interval (integer)
63               2.3.2. destination (string)
64
65         2.4. Functions
66
67               2.4.1. is_alive(destination)
68
69 1. Overview
70
71    This module performs destinations monitoring either for itself, or on
72    the behalf of other modules. The monitoring is done by sending SIP
73    OPTIONS requests, more or less in the same fashion as the dispatcher
74    module (which was the initial source for this module).
75
76    As an example of usage by other modules, see drouting, which was
77    enhanced to use this module to monitor its gateways.
78
79 2. Dependencies
80
81    2.1. Kamailio Modules
82    2.2. External Libraries or Applications
83    2.3. Parameters
84
85         2.3.1. ping_interval (integer)
86         2.3.2. destination (string)
87
88    2.4. Functions
89
90         2.4.1. is_alive(destination)
91
92 2.1. Kamailio Modules
93
94    The following modules must be loaded before this module:
95      * tm - Transaction module
96
97 2.2. External Libraries or Applications
98
99    The following libraries or applications must be installed before
100    running Kamailio with this module loaded:
101      * none
102
103 2.3. Parameters
104
105 2.3.1. ping_interval (integer)
106
107    Define the interval (in seconds) ping requests are sent to destinations
108
109    Default value is 30 seconds.
110
111    Example 1.1. Set ping_interval parameter
112 ...
113 modparam("keepalive", "ping_interval", 10)
114 ...
115
116 2.3.2. destination (string)
117
118    Allows to statically define destinations you want to monitor
119
120    Example 1.2. Set destination parameter
121 ...
122 modparam("keepalive", "destination", "192.168.10.20")
123 modparam("keepalive", "destination", "sip.provider.com")
124 ...
125
126 2.4. Functions
127
128 2.4.1.  is_alive(destination)
129
130    Get destination status.
131
132    The Parameter destination is destination you want to check status
133
134    Returned value:
135      * 1 if destination is up
136      * 2 if destination is down
137      * -1 on error
138
139    This function can be used from ANY_ROUTE.
140
141    Example 1.3. is_alive() usage
142 ...
143 if(is_alive("192.168.10.20") == 1) {
144   // do stuff
145 };
146 ...
147
148 Chapter 2. Developer Guide
149
150    Table of Contents
151
152    1. Available Functions
153
154         1.1. add_destination(uri, owner, flags, [callback, [user_attr]])
155         1.2. Examples
156
157    The KeepAlive module provides an internal API to be used by other
158    Kamailio modules. This API offers support for destinations monitoring.
159
160    For internal (non-script) usage, the KeepAlive module offers to other
161    module the possibility to register callback functions to be executed
162    for each destination's status change.
163
164 1. Available Functions
165
166    1.1. add_destination(uri, owner, flags, [callback, [user_attr]])
167    1.2. Examples
168
169 1.1.  add_destination(uri, owner, flags, [callback, [user_attr]])
170
171    This function registers a new destination to monitor. Monitoring of the
172    destination starts as soon as it returns with success (0 value).
173
174    Meaning of the parameters is as follows:
175      * uri (string) - address of destination to monitor. Valid format is
176        [proto:]ip[:port], with:
177           + proto being one of sip or sips (SIP over TLS). If omitted, sip
178             is used by default
179           + port being optional (using default standard port, 5060 for sip
180             and 5061 for sips)
181      * owner (string) - module name “owning” the destination (for
182        information purpose)
183      * flags (integer) - destination flags (unused for now, use 0 value)
184      * callback (ka_statechanged_f, optional) - callback function,
185        executed on destination's state change.
186        The callback function is of type void (*ka_statechanged_f)(str
187        *uri, int state, void *user_attr);. Use NULL to set no callback.
188        destination's state value is one of:
189           + 0 - unknown state (this is the destination state at first,
190             waiting first ping replies or timeout)
191           + 1 - destination is UP
192           + 2 - destination is DOWN
193      * user_attr (void * pointer, optional) - If callback function is
194        setup, this parameter will be forwarded to it, as last parameter.
195        Use NULL to set no user_attr parameter.
196
197    Returned values:
198      * 0 if ok
199      * -1 if an error occured
200
201 1.2. Examples
202
203    Example 2.1. Loading KeepAlive module's API from another module, adding
204    a destination to monitor & registering a callback
205 ...
206 #include "../keepalive/api.h"
207 ...
208 keepalive_api_t ka_api;
209 ...
210 ...
211 /* loading keepalive API */
212 if (bind_keepalive( &ka_api ) != 0) {
213     LM_ERR("can't load KeepAlive API\n");
214     goto error;
215 }
216 ...
217 ...
218 /* callback function */
219 void my_callback(str uri, int state, void *user_attr) {
220
221         printf("%.*s new state is: %d\n", uri.len, uri.str, state)
222 }
223
224 /* register a new destination */
225 str dest  = str_init("sip:192.168.10.21:5060");
226 str owner = str_init("mymodule");
227
228 if (ka_api.add_destination(dest, owner, 0, my_callback, NULL) != 0) {
229     LM_ERR("can't add destination\n");
230     goto error;
231 }
232 ...