mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
228 lines
6.4 KiB
228 lines
6.4 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
This module provides a connector to interact with REDIS NoSQL Database
|
|
from configuration file. You can read more about REDIS at
|
|
http://redis.io.
|
|
</para>
|
|
<para>
|
|
It can connect to many REDIS servers and store the results in different
|
|
containers.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>none</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before running
|
|
&kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>hiredis</emphasis> - available at
|
|
https://github.com/antirez/hiredis .
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="ndb_redis.p.server">
|
|
<title><varname>server</varname> (str)</title>
|
|
<para>
|
|
Specify the details to connect to REDIS server. It takes a list of attribute=value
|
|
separated by semicolon, the attributes can be name, unix, addr, port, db and pass. Name
|
|
is a generic identifier to be used with module functions. unix is the path to the unix
|
|
domain socket provided by redis server. addr and port are the IP address and the port to
|
|
connect to REDIS server. pass is the server password. unix and (addr, port) are mutually
|
|
exclusive. If both appear in same server settings unix domain socket is configured. db
|
|
is the DB number to use (defaults to 0 if not specified).
|
|
</para>
|
|
<para>
|
|
You can set this parameter many times, in case you want to connect to
|
|
many REDIS servers, just give different attributes and use the specific
|
|
server name when querying the REDIS instance.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is NULL.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>server</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("ndb_redis", "server", "name=srvN;addr=127.0.0.1;port=6379;db=1")
|
|
modparam("ndb_redis", "server", "name=srvX;addr=127.0.0.2;port=6379;db=4;pass=mypassword")
|
|
|
|
# Unix domain socket
|
|
modparam("ndb_redis", "server", "name=srvY;unix=/tmp/redis.sock;db=3")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="ndb_redis.p.init_without_redis">
|
|
<title><varname>init_without_redis</varname> (integer)</title>
|
|
<para>
|
|
If set to 1, the module will correctly initialize even if redis is not available at start up.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>init_without_redis</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("ndb_redis", "init_without_redis", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="ndb_redis.f.redis_cmd">
|
|
<title>
|
|
<function moreinfo="none">redis_cmd(srvname, command, ..., replyid)</function>
|
|
</title>
|
|
<para>
|
|
Send a command to REDIS server identified by srvname. The reply will
|
|
be stored in a local container identified by replyid. All the
|
|
parameters can be strings with pseudo-variables that are evaluated
|
|
at runtime.
|
|
</para>
|
|
<para>
|
|
Minimum required arguments are srvname, command and replyid. Command argument
|
|
can be separated into several ones using %s token. (See examples)
|
|
Total number of arguments cannot exceed six.
|
|
</para>
|
|
<para>
|
|
The reply can be accessed via pseudo-variable $redis(key). The key
|
|
can be: type - type of the reply (as in hiredis.h); value - the value
|
|
returned by REDIS server; info - in case of error from REDIS, it will
|
|
contain an info message.
|
|
</para>
|
|
<para>
|
|
If reply type is an array (as in hiredis.h), there are other keys
|
|
available:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
size - returns number of elements in the array.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
type[n] - returns the type of the nth element in the array. type
|
|
- returns array type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
value[n] - returns value of the nth element. value - returns null
|
|
for an array. You need to get each element by index.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<example>
|
|
<title><function>redis_cmd</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(redis_cmd("srvN", "INCR cnt", "r")) {
|
|
# success - the incremented value is in $redis(r=>value)
|
|
xlog("===== $redis(r=>type) * $redis(r=>value)\n");
|
|
}
|
|
|
|
# set a value
|
|
redis_cmd("srvN", "SET foo bar", "r");
|
|
|
|
redis_cmd("srvN", "SET ruri $ru", "r");
|
|
|
|
# get a value
|
|
redis_cmd("srvN", "GET foo", "r");
|
|
|
|
# same command separated into two arguments:
|
|
redis_cmd("srvN", "GET %s", "foo", "r");
|
|
|
|
# if we have a key with spaces within it:
|
|
redis_cmd("srvN", "GET %s", "foo bar", "r");
|
|
|
|
# several values substitution:
|
|
redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
|
|
|
|
|
|
# array example
|
|
if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
|
|
xlog("array size: $redis(r=>size)\n");
|
|
xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="ndb_redis.f.redis_free">
|
|
<title>
|
|
<function moreinfo="none">redis_free(replyid)</function>
|
|
</title>
|
|
<para>
|
|
Frees data in a previous reply from memory.
|
|
After this function call, accessing to a freed replyid returns null value.
|
|
</para>
|
|
<para>
|
|
It is not necessary to free a reply to use it again in a new redis_cmd
|
|
function. When ndb_redis module closes, all pending replies are freed
|
|
automatically.
|
|
</para>
|
|
<example>
|
|
<title><function>redis_free</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
After a redis command call:
|
|
redis_cmd("srvN", "INCR cnt", "r");
|
|
|
|
free reply data:
|
|
redis_free("r");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|