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
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    The module needs to know all existing REDIS-Nodes at startup. The nodes
191    are searched by the name "ip:port", e.g. if REDIS replies with "MOVED
192    127.0.0.1:4711", ndb_redis needs to know the databases
193    "127.0.0.1:4711".
194
195    Default value is “0” (disabled).
196
197    Example 1.5. Set cluster parameter
198 ...
199 modparam("ndb_redis", "server", "name=127.0.0.1:26001;addr=127.0.0.1;port=26001"
200 )
201 modparam("ndb_redis", "server", "name=127.0.0.1:26004;addr=127.0.0.1;port=26004"
202 )
203 modparam("ndb_redis", "server", "name=127.0.0.1:26008;addr=127.0.0.1;port=26008"
204 )
205 ...
206 modparam("ndb_redis", "cluster", 1)
207 ...
208
209 4. Functions
210
211    4.1. redis_cmd(srvname, command, ..., replyid)
212    4.2. redis_free(replyid)
213
214 4.1.  redis_cmd(srvname, command, ..., replyid)
215
216    Send a command to REDIS server identified by srvname. The reply will be
217    stored in a local container identified by replyid. All the parameters
218    can be strings with pseudo-variables that are evaluated at runtime.
219
220    Minimum required arguments are srvname, command and replyid. Command
221    argument can be separated into several ones using %s token. (See
222    examples) Total number of arguments cannot exceed six.
223
224    The reply can be accessed via pseudo-variable $redis(key). The key can
225    be: type - type of the reply (as in hiredis.h); value - the value
226    returned by REDIS server; info - in case of error from REDIS, it will
227    contain an info message.
228
229    If reply type is an array (as in hiredis.h), there are other keys
230    available:
231      * size - returns number of elements in the array.
232      * type[n] - returns the type of the nth element in the array. type -
233        returns array type.
234      * value[n] - returns value of the nth element. value - returns null
235        for an array. You need to get each element by index.
236
237    Example 1.6. redis_cmd usage
238 ...
239 if(redis_cmd("srvN", "INCR cnt", "r")) {
240     # success - the incremented value is in $redis(r=>value)
241     xlog("===== $redis(r=>type) * $redis(r=>value)\n");
242 }
243
244 # set a value
245 redis_cmd("srvN", "SET foo bar", "r");
246
247 redis_cmd("srvN", "SET ruri $ru", "r");
248
249 # get a value
250 redis_cmd("srvN", "GET foo", "r");
251
252 # same command separated into two arguments:
253 redis_cmd("srvN", "GET %s", "foo", "r");
254
255 # if we have a key with spaces within it:
256 redis_cmd("srvN", "GET %s", "foo bar", "r");
257
258 # several values substitution:
259 redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
260
261
262 # array example
263 if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
264     xlog("array size: $redis(r=>size)\n");
265     xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
266 }
267 ...
268
269 4.2.  redis_free(replyid)
270
271    Frees data in a previous reply from memory. After this function call,
272    accessing to a freed replyid returns null value.
273
274    It is not necessary to free a reply to use it again in a new redis_cmd
275    function. When ndb_redis module closes, all pending replies are freed
276    automatically.
277
278    Example 1.7. redis_free usage
279 ...
280 After a redis command call:
281         redis_cmd("srvN", "INCR cnt", "r");
282
283 free reply data:
284         redis_free("r");
285 ...