Intro to Redis
The Redis website describes Redis as "an open source (BSD licensed), in-memory data structure store, used as database, cache and message broker." While Redis and FreeSWITCH may be installed on the same server, they can also be on separate servers, with the Redis connection information managed using profiles in the FreeSWITCH mod_hiredis configuration file.
mod_hiredis in FreeSWITCH
Mod_hiredis was built using the officially supported C library libhiredis, and is a useful tool for interfacing with the Redis instance.
Installing pre-requisites
On the Debian Jessie server(s), install the following tools for repository and file management:
apt-get install git emacs-nox
Installing Redis
On a dedicated server, or on the same server as FreeSWITCH, install redis-server.
apt-get install redis-server
This will create the redis configuration directory in /etc/redis. To start the redis server, run:
/etc/init.d/redis-server start
Check the running process, and note that the redis server is now running on port 6379
ps aux | grep redis
# Output:
redis 6843 0.0 0.5 38528 3000 ? Ssl 11:44 0:00 /usr/bin/redis-server 127.0.0.1:6379
root 6977 0.0 0.1 11056 512 pts/5 D+ 11:47 0:00 grep redis
Here are some commands you can do with Redis: exists, get, set, incr (increment), decr (decrement), del (delete). Read more about these and others here: http://redis.io/commands
Let's try a few commands on our Redis server. Open the Redis Command Line Interface on your Redis server.
redis-cli
See the example below for testing a few commands. Notice the outputs for the different commands. Exist returns 1 (does exist) or 0 (does not exist). Delete returns 1 (did exist, now deleted) or 0 (did not exist, was not deleted). Get returns the value, regardless of whether the key exists or not. Set returns OK on success. Incr and Decr return the new value of the key after incrementing and decrementing, respectively.
127.0.0.1:6379> exists testing
(integer) 0
127.0.0.1:6379> get testing
(nil)
127.0.0.1:6379> set testing 1
OK
127.0.0.1:6379> exists testing
(integer) 1
127.0.0.1:6379> get testing
"1"
127.0.0.1:6379> incr testing
(integer) 2
127.0.0.1:6379> get testing
"2"
127.0.0.1:6379> decr testing
(integer) 1
127.0.0.1:6379> get testing
"1"
127.0.0.1:6379> del testing
(integer) 1
127.0.0.1:6379> exists testing
(integer) 0
127.0.0.1:6379> get testing
(nil)
127.0.0.1:6379> del testing
(integer) 0
Installing hiredis
On a Debian Jessie server, install the Hiredis development library. If not using the same server for Redis and FreeSWITCH, use the dedicated FreeSWITCH server for the following sections.
apt-get install libhiredis-dev
Cloning FreeSWITCH
Install the latest 1.6 branch of FreeSWITCH from source.
Enable the Debian Jessie repository and install FreeSWITCH's dependencies
echo "deb http://files.freeswitch.org/repo/deb/debian/ jessie main" > /etc/apt/sources.list.d/99FreeSWITCH.test.list
wget -O - http://files.freeswitch.org/repo/deb/debian/key.gpg |apt-key add -
apt-get update
DEBIAN_FRONTEND=none APT_LISTCHANGES_FRONTEND=none apt-get install -y --force-yes freeswitch-video-deps-most
Clone the FreeSWITCH repository
cd /usr/src/
git clone https://freeswitch.org/stash/scm/fs/freeswitch.git freeswitch.git
cd freeswitch.git
Installing FreeSWITCH with mod_hiredis
Run bootstrap as usual, then add or uncomment the applications/mod_hiredis line in modules.conf
./bootstrap.sh -j
emacs modules.conf
Modules.conf should now include the following uncommented line
applications/mod_hiredis
Proceed to configure and install FreeSWITCH, now that it knows to grab the hiredis library
./configure
make
make install
make cd-sounds-install && make cd-moh-install && make samples
Create the FreeSWITCH user and set permissions for the FreeSWITCH install. Note: the user is added before granting ownership of the directories. A Warning message may occur between adding the user and changing the ownership.
cd /usr/local
adduser --disabled-password --quiet --system --home /usr/local/freeswitch --gecos "FreeSWITCH open source softswitch" --ingroup daemon freeswitch
chown -R freeswitch:daemon /usr/local/freeswitch/
chmod -R ug=rwX,o= /usr/local/freeswitch/
chmod -R u=rwx,g=rx /usr/local/freeswitch/bin/*
Configuring mod_hiredis
Update the mod_hiredis default profile, or add your own profile based on your redis server details.
cd ./freeswitch
emacs ./conf/autoload_configs/hiredis.conf.xml
Sample working configs:
<configuration name="hiredis.conf" description="mod_hiredis">
<profiles>
<profile name="default">
<connections>
<connection name="primary">
<param name="hostname" value="localhost"/>
<param name="password" value="redis"/>
<param name="port" value="6379"/>
<param name="timeout_ms" value="500"/>
</connection>
<connection name="secondary">
<param name="hostname" value="172.18.101.101"/>
<param name="password" value="redis"/>
<param name="port" value="6379"/>
<param name="timeout_ms" value="500"/>
</connection>
</connections>
<params>
<param name="debug" value="1"/>
</params>
</profile>
</profiles>
</configuration>
Update autload_configs to load mod_hiredis on startup by adding or uncommenting the load line
emacs ./conf/autoload_configs/modules.conf.xml
<load module="mod_hiredis"/>
While updating settings, change the default password to anything other than 1234 by updating the line in vars.xml.
emacs ./conf/vars.xml
<X-PRE-PROCESS cmd="set" data="default_password=1111"/>
Start FreeSWITCH and note the following lines on startup:
/usr/local/freeswitch/bin/freeswitch -nonat -ncwait
2015-08-28 10:19:29.343106 [CRIT] hiredis_utils.c:78 hiredis: adding conn[6379 == 6379]
2015-08-28 10:19:29.343109 [CRIT] hiredis_profile.c:81 hiredis: adding conn[6379]
2015-08-28 10:19:29.343114 [CRIT] hiredis_utils.c:78 hiredis: adding conn[6380 == 6380]
2015-08-28 10:19:29.343116 [CRIT] hiredis_profile.c:81 hiredis: adding conn[6380]
2015-08-28 10:19:29.343123 [CONSOLE] switch_loadable_module.c:1538 Successfully Loaded [mod_hiredis]
2015-08-28 10:19:29.343132 [NOTICE] switch_loadable_module.c:292 Adding Application 'hiredis_raw'
2015-08-28 10:19:29.343154 [NOTICE] switch_loadable_module.c:338 Adding API Function 'hiredis_raw'
2015-08-28 10:19:29.343167 [NOTICE] switch_loadable_module.c:556 Adding Limit interface 'hiredis'
FreeSWITCH has established connection to the hiredis library on the ports specified in the hiredis configuration file and prints the notice that hiredis_raw application and API function are now available, as is the hiredis limit interface. So let's test it out!
Testing mod_hiredis
Interfacing with the redis server over mod_hiredis is most visible using fs_cli, the FreeSWITCH Command Line Interface. Open fs_cli from the terminal:
/usr/local/freeswitch/bin/fs_cli
set, get
In fs_cli, use the following syntax to perform a "set" command, which will set the value. This example uses the standard hiredis_raw API, the default profile, the "set" command, and the new key "test". Note the Output indicating connection to the redis server and successful response.
freeswitch@Quentus8852> hiredis_raw default set test 01
2015-09-04 10:08:34.499851 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [set test 01]
OK
In fs_cli, use the following syntax to perform a "get" command, which will retrieve the value. Note the Output of 01, the value of the key "test".
freeswitch@Quentus8852> hiredis_raw default get test
2015-09-04 10:08:45.159853 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [get test]
01
increment, decrement
In fs_cli, use the following syntax to perform a "incr" command, which will increment the value. Note the Output indicating the new value.
freeswitch@Quentus8852> hiredis_raw default incr test
2015-09-04 10:08:57.879817 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [incr test]
2
In fs_cli, use the following syntax to perform a "decr" command, which will decrement the value. Note the Output indicating the new value.
freeswitch@Quentus8852> hiredis_raw default decr test
2015-09-04 10:09:02.359886 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [decr test]
1
exists, delete
In fs_cli, use the following syntax to perform a "exists" command, which will check if the key exists. Note the Output indicating that it does exist.
freeswitch@Quentus8852> hiredis_raw default exists test
2015-09-04 10:09:07.719849 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [exists test]
1
In fs_cli, use the following syntax to perform a "del" command, which will delete the key if it exists. Note the Output indicating that it was deleted.
freeswitch@Quentus8852> hiredis_raw default del test
2015-09-04 10:09:13.679892 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [del test]
1
In fs_cli, use the following syntax to perform a "exists" command, which will check if the key exists. Note the Output indicating that it does NOT exist.
freeswitch@Quentus8852> hiredis_raw default exists test
2015-09-04 10:09:16.639881 [DEBUG] mod_hiredis.c:96 hiredis: debug: profile[default] for command [exists test]
0
Wrap-up
Congratulations! You have installed and configured mod_hiredis. For more fun with Redis, perform a "set" on a key from fs_cli followed by a "get" on the same key from redis-cli and vice versa.
Watch for upcoming posts exploring more mod_hiredis functionality!