modules: readme files regenerated - ndb_redis ... [skip ci]
[sip-router] / src / modules / ndb_redis / README
1 NDB_REDIS Module
2
3 Daniel-Constantin Mierla
4
5    <miconda@gmail.com>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13 Vicente Hernando
14
15    <vhernando@systemonenoc.com>
16
17 Morten Isaksen
18
19    <misak@uni-tel.dk>
20
21 Carsten Bock
22
23    <carsten@ng-voice.com>
24
25    Copyright © 2011 asipto.com
26
27    Copyright © 2012 www.systemonenoc.com
28
29    Copyright © 2017 ng-voice GmbH
30      __________________________________________________________________
31
32    Table of Contents
33
34    1. Admin Guide
35
36         1. Overview
37         2. Dependencies
38
39               2.1. Kamailio Modules
40               2.2. External Libraries or Applications
41
42         3. Parameters
43
44               3.1. server (str)
45               3.2. init_without_redis (integer)
46               3.3. connect_timeout (int)
47               3.4. cmd_timeout (int)
48               3.5. cluster (integer)
49               3.6. allowed_timeouts (integer)
50               3.7. disable_time (integer)
51               3.8. flush_on_reconnect (integer)
52
53         4. Functions
54
55               4.1. redis_cmd(srvname, command, ..., replyid)
56               4.2. redis_pipe_cmd(srvname, command, ..., replyid)
57               4.3. redis_execute(srvname)
58               4.4. redis_free(replyid)
59
60    List of Examples
61
62    1.1. Set server parameter
63    1.2. Set init_without_redis parameter
64    1.3. Set connect_timeout parameter
65    1.4. Set cmd_timeout parameter
66    1.5. Set cluster parameter
67    1.6. Set allowed_timeots parameter
68    1.7. Set disable_time parameter
69    1.8. Set flush_on_reconnect parameter
70    1.9. redis_cmd usage
71    1.10. redis_execute usage
72    1.11. redis_free usage
73
74 Chapter 1. Admin Guide
75
76    Table of Contents
77
78    1. Overview
79    2. Dependencies
80
81         2.1. Kamailio Modules
82         2.2. External Libraries or Applications
83
84    3. Parameters
85
86         3.1. server (str)
87         3.2. init_without_redis (integer)
88         3.3. connect_timeout (int)
89         3.4. cmd_timeout (int)
90         3.5. cluster (integer)
91         3.6. allowed_timeouts (integer)
92         3.7. disable_time (integer)
93         3.8. flush_on_reconnect (integer)
94
95    4. Functions
96
97         4.1. redis_cmd(srvname, command, ..., replyid)
98         4.2. redis_pipe_cmd(srvname, command, ..., replyid)
99         4.3. redis_execute(srvname)
100         4.4. redis_free(replyid)
101
102 1. Overview
103
104    This module provides a connector to interact with REDIS NoSQL Database
105    from configuration file. You can read more about REDIS at
106    http://redis.io.
107
108    It can connect to many REDIS servers and store the results in different
109    containers.
110
111 2. Dependencies
112
113    2.1. Kamailio Modules
114    2.2. External Libraries or Applications
115
116 2.1. Kamailio Modules
117
118    The following modules must be loaded before this module:
119      * none.
120
121 2.2. External Libraries or Applications
122
123    The following libraries or applications must be installed before
124    running Kamailio with this module loaded:
125      * hiredis - available at https://github.com/antirez/hiredis .
126
127 3. Parameters
128
129    3.1. server (str)
130    3.2. init_without_redis (integer)
131    3.3. connect_timeout (int)
132    3.4. cmd_timeout (int)
133    3.5. cluster (integer)
134    3.6. allowed_timeouts (integer)
135    3.7. disable_time (integer)
136    3.8. flush_on_reconnect (integer)
137
138 3.1. server (str)
139
140    Specify the details to connect to REDIS server. It takes a list of
141    attribute=value separated by semicolon, the attributes can be name,
142    unix, addr, port, db and pass. Name is a generic identifier to be used
143    with module functions. unix is the path to the unix domain socket
144    provided by redis server. addr and port are the IP address and the port
145    to connect to REDIS server. pass is the server password. unix and
146    (addr, port) are mutually exclusive. If both appear in same server
147    settings unix domain socket is configured. db is the DB number to use
148    (defaults to 0 if not specified).
149
150    You can set this parameter many times, in case you want to connect to
151    many REDIS servers, just give different attributes and use the specific
152    server name when querying the REDIS instance.
153
154    Default value is NULL.
155
156    Example 1.1. Set server parameter
157 ...
158 modparam("ndb_redis", "server", "name=srvN;addr=127.0.0.1;port=6379;db=1")
159 modparam("ndb_redis", "server", "name=srvX;addr=127.0.0.2;port=6379;db=4;pass=my
160 password")
161
162 # Unix domain socket
163 modparam("ndb_redis", "server", "name=srvY;unix=/tmp/redis.sock;db=3")
164 ...
165
166 3.2. init_without_redis (integer)
167
168    If set to 1, the module will correctly initialize even if redis is not
169    available at start up.
170
171    Default value is “0”.
172
173    Example 1.2. Set init_without_redis parameter
174 ...
175 modparam("ndb_redis", "init_without_redis", 1)
176 ...
177
178 3.3. connect_timeout (int)
179
180    The timeout when connecting to the redis server
181
182    Default value is 1000 ms.
183
184    Example 1.3. Set connect_timeout parameter
185 ...
186 modparam("ndb_redis", "connect_timeout", 500)
187 ...
188
189 3.4. cmd_timeout (int)
190
191    The timeout for each query to the redis server. If the redis server
192    does not reply within the timeout value, the command will fail and
193    kamailio will continue executing the cfg file.
194
195    Default value is 1000 ms.
196
197    Example 1.4. Set cmd_timeout parameter
198 ...
199 modparam("ndb_redis", "cmd_timeout", 500)
200 ...
201
202 3.5. cluster (integer)
203
204    If set to 1, the module will connect to servers indicated in the
205    "MOVED" reply.
206
207    The module needs to know all existing REDIS-Nodes at startup. The nodes
208    are searched by the name "ip:port", e.g. if REDIS replies with "MOVED
209    127.0.0.1:4711", ndb_redis needs to know the databases
210    "127.0.0.1:4711".
211
212    Default value is “0” (disabled).
213
214    Example 1.5. Set cluster parameter
215 ...
216 modparam("ndb_redis", "server", "name=127.0.0.1:26001;addr=127.0.0.1;port=26001"
217 )
218 modparam("ndb_redis", "server", "name=127.0.0.1:26004;addr=127.0.0.1;port=26004"
219 )
220 modparam("ndb_redis", "server", "name=127.0.0.1:26008;addr=127.0.0.1;port=26008"
221 )
222 ...
223 modparam("ndb_redis", "cluster", 1)
224 ...
225
226 3.6. allowed_timeouts (integer)
227
228    If this is set to a non-negative value, it sets the number of
229    consecutive REDIS commands that can fail before temporarily disabling
230    the REDIS server. This is similar to rtpengine_disable_tout parameter
231    from the rtpengine module.
232
233    When communicating with a REDIS server, if redis_cmd or redis_execute
234    will fail for more than “allowed_timeouts” consecutive times, the
235    server will be temporary disabled for a number of seconds configured by
236    the “disable_time” parameter.
237
238    Disabling a server means that further redis_cmd and redis_execute
239    commands will not do anything and return a negative value “-2”.
240    Messages are also logged when disabling and re-enabling a server.
241
242    The number of consecutive fails are counted by each Kamailio process,
243    so when disabling a server this is done just for that process, not
244    globally.
245
246    Default value is “-1” (disabled).
247
248    Example 1.6. Set allowed_timeots parameter
249 ...
250 modparam("ndb_redis", "allowed_timeouts", 3)
251 ...
252
253 3.7. disable_time (integer)
254
255    If allowed_timeouts is set to a non negative value this determines the
256    number of seconds the REDIS server will be disabled
257
258    Default value is “0”.
259
260    Example 1.7. Set disable_time parameter
261 ...
262 modparam("ndb_redis", "allowed_timeouts", 0)
263 modparam("ndb_redis", "disable_time", 30)
264 ...
265
266 3.8. flush_on_reconnect (integer)
267
268    If this is set to a non zero value, a "FLUSHALL" command is issued
269    after reconnecting to a REDIS server, to clear the entire database.
270
271    When a command to a REDIS server fails, a reconnection to that server
272    is made, so with this parameter each failed command will result in a
273    flush of the database.
274
275    This is useful in scenarios when a REDIS server does not respond to
276    commands, but the commands might have been issued, and the responses
277    lost. If this leaves the data in the db in an uncertain state, a flush
278    might fix any issues that may occur.
279
280    Default value is “0” (disabled).
281
282    Example 1.8. Set flush_on_reconnect parameter
283 ...
284 modparam("ndb_redis", "flush_on_reconnect", 1)
285 ...
286
287 4. Functions
288
289    4.1. redis_cmd(srvname, command, ..., replyid)
290    4.2. redis_pipe_cmd(srvname, command, ..., replyid)
291    4.3. redis_execute(srvname)
292    4.4. redis_free(replyid)
293
294 4.1.  redis_cmd(srvname, command, ..., replyid)
295
296    Send a command to REDIS server identified by srvname. The reply will be
297    stored in a local container identified by replyid. All the parameters
298    can be strings with pseudo-variables that are evaluated at runtime.
299
300    Minimum required arguments are srvname, command and replyid. Command
301    argument can be separated into several ones using %s token. (See
302    examples) Total number of arguments cannot exceed six.
303
304    The reply can be accessed via pseudo-variable $redis(key). The key can
305    be: type - type of the reply (as in hiredis.h); value - the value
306    returned by REDIS server; info - in case of error from REDIS, it will
307    contain an info message.
308
309    If reply type is an array (as in hiredis.h), there are other keys
310    available:
311      * size - returns number of elements in the array.
312      * type[n] - returns the type of the nth element in the array. type -
313        returns array type.
314      * value[n] - returns value of the nth element. value - returns null
315        for an array. You need to get each element by index.
316
317    In case one of the members of the array is also an array (for example
318    calling SMEMBERS in a MULTI/EXEC transaction), the members of the array
319    can be accessed by adding any of the above keys, after a value[n] key.
320    The first value[n] references the element in the first array, while the
321    next key references an element of the referenced array.
322
323    Example 1.9. redis_cmd usage
324 ...
325 if(redis_cmd("srvN", "INCR cnt", "r")) {
326     # success - the incremented value is in $redis(r=>value)
327     xlog("===== $redis(r=>type) * $redis(r=>value)\n");
328 }
329
330 # set a value
331 redis_cmd("srvN", "SET foo bar", "r");
332
333 redis_cmd("srvN", "SET ruri $ru", "r");
334
335 # get a value
336 redis_cmd("srvN", "GET foo", "r");
337
338 # same command separated into two arguments:
339 redis_cmd("srvN", "GET %s", "foo", "r");
340
341 # if we have a key with spaces within it:
342 redis_cmd("srvN", "GET %s", "foo bar", "r");
343
344 # several values substitution:
345 redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
346
347
348 # array example
349 if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
350     xlog("array size: $redis(r=>size)\n");
351     xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
352 }
353
354
355 # array as element of an array example
356 redis_cmd("srvN", "MULTI", "r1");
357 redis_cmd("srvN", "SMEMBERS foo", "r2");
358 if (redis_cmd("srvN", "EXEC", "r")) {
359     xlog("array size: $redis(r=>value[0]=>size)\n");
360     xlog("first member of the set:$redis(r=>value[0]=>value[0])\n");
361     xlog("type of the second member of the set:$redis(r=>value[0]=>type[1])\n");
362 }
363 ...
364
365 4.2.  redis_pipe_cmd(srvname, command, ..., replyid)
366
367    Add a command to be sent to REDIS server identified by srvname. All the
368    commands will be stored in a buffer until a call to redis_execute is
369    made. When calling redis_execute the stored commands are sent using the
370    pipelining functionality of redis. The replies will be stored in local
371    containers identified by the replyid of each added command. All the
372    parameters can be strings with pseudo-variables that are evaluated at
373    runtime.
374
375    This command is similar in syntax with redis_cmd, the only difference
376    is that it does not send the command but instead appends it to a
377    buffer.
378
379    See examples from redis_execute.
380
381    Note: Pipelining feature is incompatible with the clustering feature.
382    If cluster parameter is set to 1, this function will log an error and
383    do nothing.
384
385 4.3.  redis_execute(srvname)
386
387    Sends commands to REDIS server identified by srvname. Commands are
388    added with redis_pipe_cmd function, and will be stored for an existing
389    REDIS server. When this function is called all the commands will be
390    sent in a single message to the REDIS server.
391
392    When using redis_cmd together with redis_pipe_cmd it is recommended
393    that a call to redis_execute is made before calling redis_cmd in case
394    there are pipelined commands, otherwise when calling redis_cmd, if
395    pipelined messages exist, a call to redis_execute is made automatically
396    and a warning message is logged.
397
398    Note: Pipelining feature is incompatible with the clustering feature.
399    If cluster parameter is set to 1, this function will log an error and
400    do nothing.
401
402    Example 1.10. redis_execute usage
403 ...
404 After several redis command calls:
405         redis_pipe_cmd("srvA", "SET foo bar", "r1");
406
407         redis_pipe_cmd("srvB", "SET ruri $ru", "r2");
408
409         redis_pipe_cmd("srvB", "GET foo", "r3");
410
411 Send the data and retrieve the results:
412         redis_execute("srvA"); //send command to srvA and wait for reply. Store
413 the reply in r1
414
415         redis_execute("srvB"); //send command to srvA and wait for reply. Store
416 the replies in r2 (for SET ruri $ru) and r3 (for GET foo)
417
418 Using both redis_cmd and redis_pipe_cmd:
419         redis_pipe_cmd("srvA", "SET foo bar", "r1");
420
421         redis_pipe_cmd("srvA", "SET ruri $ru", "r2");
422
423         redis_execute("srvA"); //send commands to srvA and wait for reply. Store
424  replies in r1 and r2
425
426         redis_cmd("srvA", "GET foo", "r3"); //send command, wait for reply and s
427 tore it in r3
428
429
430         redis_pipe_cmd("srvA", "SET foo bar", "r1");
431
432         redis_pipe_cmd("srvA", "SET ruri $ru", "r2");
433
434         redis_cmd("srvA", "GET foo", "r3"); //first call redis execute (replies
435 are stored in r1 and r2), log warning and execute redis_cmd
436
437         redis_execute("srvA"); //this does nothing as there are no more pipeline
438 d commands. The call is not necessary
439 ...
440
441 4.4.  redis_free(replyid)
442
443    Frees data in a previous reply from memory. After this function call,
444    accessing to a freed replyid returns null value.
445
446    It is not necessary to free a reply to use it again in a new redis_cmd
447    function. When ndb_redis module closes, all pending replies are freed
448    automatically.
449
450    Example 1.11. redis_free usage
451 ...
452 After a redis command call:
453         redis_cmd("srvN", "INCR cnt", "r");
454
455 free reply data:
456         redis_free("r");
457 ...