8ef7d7dd9c3f26553ce4df89a6b57dfdaca1c042
[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    Example 1.9. redis_cmd usage
318 ...
319 if(redis_cmd("srvN", "INCR cnt", "r")) {
320     # success - the incremented value is in $redis(r=>value)
321     xlog("===== $redis(r=>type) * $redis(r=>value)\n");
322 }
323
324 # set a value
325 redis_cmd("srvN", "SET foo bar", "r");
326
327 redis_cmd("srvN", "SET ruri $ru", "r");
328
329 # get a value
330 redis_cmd("srvN", "GET foo", "r");
331
332 # same command separated into two arguments:
333 redis_cmd("srvN", "GET %s", "foo", "r");
334
335 # if we have a key with spaces within it:
336 redis_cmd("srvN", "GET %s", "foo bar", "r");
337
338 # several values substitution:
339 redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
340
341
342 # array example
343 if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
344     xlog("array size: $redis(r=>size)\n");
345     xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
346 }
347 ...
348
349 4.2.  redis_pipe_cmd(srvname, command, ..., replyid)
350
351    Add a command to be sent to REDIS server identified by srvname. All the
352    commands will be stored in a buffer until a call to redis_execute is
353    made. When calling redis_execute the stored commands are sent using the
354    pipelining functionality of redis. The replies will be stored in local
355    containers identified by the replyid of each added command. All the
356    parameters can be strings with pseudo-variables that are evaluated at
357    runtime.
358
359    This command is similar in syntax with redis_cmd, the only difference
360    is that it does not send the command but instead appends it to a
361    buffer.
362
363    See examples from redis_execute.
364
365    Note: Pipelining feature is incompatible with the clustering feature.
366    If cluster parameter is set to 1, this function will log an error and
367    do nothing.
368
369 4.3.  redis_execute(srvname)
370
371    Sends commands to REDIS server identified by srvname. Commands are
372    added with redis_pipe_cmd function, and will be stored for an existing
373    REDIS server. When this function is called all the commands will be
374    sent in a single message to the REDIS server.
375
376    When using redis_cmd together with redis_pipe_cmd it is recommended
377    that a call to redis_execute is made before calling redis_cmd in case
378    there are pipelined commands, otherwise when calling redis_cmd, if
379    pipelined messages exist, a call to redis_execute is made automatically
380    and a warning message is logged.
381
382    Note: Pipelining feature is incompatible with the clustering feature.
383    If cluster parameter is set to 1, this function will log an error and
384    do nothing.
385
386    Example 1.10. redis_execute usage
387 ...
388 After several redis command calls:
389         redis_pipe_cmd("srvA", "SET foo bar", "r1");
390
391         redis_pipe_cmd("srvB", "SET ruri $ru", "r2");
392
393         redis_pipe_cmd("srvB", "GET foo", "r3");
394
395 Send the data and retrieve the results:
396         redis_execute("srvA"); //send command to srvA and wait for reply. Store
397 the reply in r1
398
399         redis_execute("srvB"); //send command to srvA and wait for reply. Store
400 the replies in r2 (for SET ruri $ru) and r3 (for GET foo)
401
402 Using both redis_cmd and redis_pipe_cmd:
403         redis_pipe_cmd("srvA", "SET foo bar", "r1");
404
405         redis_pipe_cmd("srvA", "SET ruri $ru", "r2");
406
407         redis_execute("srvA"); //send commands to srvA and wait for reply. Store
408  replies in r1 and r2
409
410         redis_cmd("srvA", "GET foo", "r3"); //send command, wait for reply and s
411 tore it in r3
412
413
414         redis_pipe_cmd("srvA", "SET foo bar", "r1");
415
416         redis_pipe_cmd("srvA", "SET ruri $ru", "r2");
417
418         redis_cmd("srvA", "GET foo", "r3"); //first call redis execute (replies
419 are stored in r1 and r2), log warning and execute redis_cmd
420
421         redis_execute("srvA"); //this does nothing as there are no more pipeline
422 d commands. The call is not necessary
423 ...
424
425 4.4.  redis_free(replyid)
426
427    Frees data in a previous reply from memory. After this function call,
428    accessing to a freed replyid returns null value.
429
430    It is not necessary to free a reply to use it again in a new redis_cmd
431    function. When ndb_redis module closes, all pending replies are freed
432    automatically.
433
434    Example 1.11. redis_free usage
435 ...
436 After a redis command call:
437         redis_cmd("srvN", "INCR cnt", "r");
438
439 free reply data:
440         redis_free("r");
441 ...