3613f577d8e2c6c55ad126bbb1cb8608042d465e
[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
50         4. Functions
51
52               4.1. redis_cmd(srvname, command, ..., replyid)
53               4.2. redis_free(replyid)
54
55    List of Examples
56
57    1.1. Set server parameter
58    1.2. Set init_without_redis parameter
59    1.3. Set connect_timeout parameter
60    1.4. Set cmd_timeout parameter
61    1.5. Set cluster parameter
62    1.6. redis_cmd usage
63    1.7. redis_free usage
64
65 Chapter 1. Admin Guide
66
67    Table of Contents
68
69    1. Overview
70    2. Dependencies
71
72         2.1. Kamailio Modules
73         2.2. External Libraries or Applications
74
75    3. Parameters
76
77         3.1. server (str)
78         3.2. init_without_redis (integer)
79         3.3. connect_timeout (int)
80         3.4. cmd_timeout (int)
81         3.5. cluster (integer)
82
83    4. Functions
84
85         4.1. redis_cmd(srvname, command, ..., replyid)
86         4.2. redis_free(replyid)
87
88 1. Overview
89
90    This module provides a connector to interact with REDIS NoSQL Database
91    from configuration file. You can read more about REDIS at
92    http://redis.io.
93
94    It can connect to many REDIS servers and store the results in different
95    containers.
96
97 2. Dependencies
98
99    2.1. Kamailio Modules
100    2.2. External Libraries or Applications
101
102 2.1. Kamailio Modules
103
104    The following modules must be loaded before this module:
105      * none.
106
107 2.2. External Libraries or Applications
108
109    The following libraries or applications must be installed before
110    running Kamailio with this module loaded:
111      * hiredis - available at https://github.com/antirez/hiredis .
112
113 3. Parameters
114
115    3.1. server (str)
116    3.2. init_without_redis (integer)
117    3.3. connect_timeout (int)
118    3.4. cmd_timeout (int)
119    3.5. cluster (integer)
120
121 3.1. server (str)
122
123    Specify the details to connect to REDIS server. It takes a list of
124    attribute=value separated by semicolon, the attributes can be name,
125    unix, addr, port, db and pass. Name is a generic identifier to be used
126    with module functions. unix is the path to the unix domain socket
127    provided by redis server. addr and port are the IP address and the port
128    to connect to REDIS server. pass is the server password. unix and
129    (addr, port) are mutually exclusive. If both appear in same server
130    settings unix domain socket is configured. db is the DB number to use
131    (defaults to 0 if not specified).
132
133    You can set this parameter many times, in case you want to connect to
134    many REDIS servers, just give different attributes and use the specific
135    server name when querying the REDIS instance.
136
137    Default value is NULL.
138
139    Example 1.1. Set server parameter
140 ...
141 modparam("ndb_redis", "server", "name=srvN;addr=127.0.0.1;port=6379;db=1")
142 modparam("ndb_redis", "server", "name=srvX;addr=127.0.0.2;port=6379;db=4;pass=my
143 password")
144
145 # Unix domain socket
146 modparam("ndb_redis", "server", "name=srvY;unix=/tmp/redis.sock;db=3")
147 ...
148
149 3.2. init_without_redis (integer)
150
151    If set to 1, the module will correctly initialize even if redis is not
152    available at start up.
153
154    Default value is “0”.
155
156    Example 1.2. Set init_without_redis parameter
157 ...
158 modparam("ndb_redis", "init_without_redis", 1)
159 ...
160
161 3.3. connect_timeout (int)
162
163    The timeout when connecting to the redis server
164
165    Default value is 1000 ms.
166
167    Example 1.3. Set connect_timeout parameter
168 ...
169 modparam("ndb_redis", "connect_timeout", 500)
170 ...
171
172 3.4. cmd_timeout (int)
173
174    The timeout for each query to the redis server. If the redis server
175    does not reply within the timeout value, the command will fail and
176    kamailio will continue executing the cfg file.
177
178    Default value is 1000 ms.
179
180    Example 1.4. Set cmd_timeout parameter
181 ...
182 modparam("ndb_redis", "cmd_timeout", 500)
183 ...
184
185 3.5. cluster (integer)
186
187    If set to 1, the module will connect to servers indicated in the
188    "MOVED" reply.
189
190    Default value is “0” (disabled).
191
192    Example 1.5. Set cluster parameter
193 ...
194 modparam("ndb_redis", "cluster", 1)
195 ...
196
197 4. Functions
198
199    4.1. redis_cmd(srvname, command, ..., replyid)
200    4.2. redis_free(replyid)
201
202 4.1.  redis_cmd(srvname, command, ..., replyid)
203
204    Send a command to REDIS server identified by srvname. The reply will be
205    stored in a local container identified by replyid. All the parameters
206    can be strings with pseudo-variables that are evaluated at runtime.
207
208    Minimum required arguments are srvname, command and replyid. Command
209    argument can be separated into several ones using %s token. (See
210    examples) Total number of arguments cannot exceed six.
211
212    The reply can be accessed via pseudo-variable $redis(key). The key can
213    be: type - type of the reply (as in hiredis.h); value - the value
214    returned by REDIS server; info - in case of error from REDIS, it will
215    contain an info message.
216
217    If reply type is an array (as in hiredis.h), there are other keys
218    available:
219      * size - returns number of elements in the array.
220      * type[n] - returns the type of the nth element in the array. type -
221        returns array type.
222      * value[n] - returns value of the nth element. value - returns null
223        for an array. You need to get each element by index.
224
225    Example 1.6. redis_cmd usage
226 ...
227 if(redis_cmd("srvN", "INCR cnt", "r")) {
228     # success - the incremented value is in $redis(r=>value)
229     xlog("===== $redis(r=>type) * $redis(r=>value)\n");
230 }
231
232 # set a value
233 redis_cmd("srvN", "SET foo bar", "r");
234
235 redis_cmd("srvN", "SET ruri $ru", "r");
236
237 # get a value
238 redis_cmd("srvN", "GET foo", "r");
239
240 # same command separated into two arguments:
241 redis_cmd("srvN", "GET %s", "foo", "r");
242
243 # if we have a key with spaces within it:
244 redis_cmd("srvN", "GET %s", "foo bar", "r");
245
246 # several values substitution:
247 redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
248
249
250 # array example
251 if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
252     xlog("array size: $redis(r=>size)\n");
253     xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
254 }
255 ...
256
257 4.2.  redis_free(replyid)
258
259    Frees data in a previous reply from memory. After this function call,
260    accessing to a freed replyid returns null value.
261
262    It is not necessary to free a reply to use it again in a new redis_cmd
263    function. When ndb_redis module closes, all pending replies are freed
264    automatically.
265
266    Example 1.7. redis_free usage
267 ...
268 After a redis command call:
269         redis_cmd("srvN", "INCR cnt", "r");
270
271 free reply data:
272         redis_free("r");
273 ...