Skip to content

Installation Guide for CentOS 7#

This is a reference guide for installing all of the necessary components for Kazoo. Once you have completed this guide, you should have an all-in-one installation of Kazoo complete and ready to configure for use.

The CentOS packages for the various dependencies are installed along with a wrapper that sets up the various configs and scripts that Kazoo needs. So when you install `kazoo-kamailio` you get the vanilla Kamailio packages along with the `kazoo-kamailio` overlay. Be aware that you'll need to use `kazoo-kamailio` when interacting with systemd.

A living guide#

This guide is an attempt to make installing all the various components straightforward to get a working All-in-One Kazoo installation for testing purposes. However, packages are updated in the CentOS repos, new versions of Kazoo get released, and other things that can cause this guide to bitrot.

We need your help to keep this up to date by:

  1. Reporting on the forum about where in the guide things broke down, or that you didn't understand.
  2. Using the edit link to edit this document and issue a pull request.

Setup the server#

This guide builds a server using the CentOS 7 Minimal ISO. Once you have that installed on a server (or virtual machine), it is time to setup the host. Some of the commands below are optional (and noted as such) - check whether you need to run them first.


Please remember to replace '' with your server's actual IP address (not localhost either). A simple sed -i 's/ on this file should do it (or whatever string-replace functionality you have available)

# Install updates
yum update

# Install required packages
yum install -y yum-utils psmisc

# Hostname setup
hostnamectl set-hostname

echo " aio" >> /etc/hosts
echo " aio" >> /etc/hosts

# System time to UTC
ln -fs /usr/share/zoneinfo/UTC /etc/localtime

# Setup networking to auto-start (if necessary)
sed -i 's/ONBOOT=no/ONBOOT=yes/' /etc/sysconfig/network-scripts/ifcfg-eth0
systemctl restart network

# Add 2600Hz RPM server
# You can find the latest Release RPM here:
# Currently, 4.2 is considered 'stable' so:

yum install -y

# Clear yum cache
yum clean all

# Setup NTPd
yum install -y ntp
systemctl stop ntpd

# Feel free to use other NTP servers
echo "server" > /etc/ntp.conf
systemctl start ntpd

Setting up RabbitMQ#

# Install the Kazoo-wrapped RabbitMQ
yum install -y kazoo-rabbitmq

## This installs an older (perfectly fine) version 3.3.5
## If you want to run newer versions
## 1. import the signing key: rpm --import
## 2. choose the RPM you want from
##    yum install

# Enable and start
systemctl enable kazoo-rabbitmq
systemctl start kazoo-rabbitmq

# Check that RabbitMQ is listening
ss -lpn | grep "5672"
tcp    LISTEN     0      128       *:25672                 *:*                   users:(("beam.smp",pid=10826,fd=8))

# For testing purposes, it can be useful to disable iptables (optional)
systemctl stop iptables

# Check the RabbitMQ UI (optional)
# Use 'guest' as username and password

# Check out the API (optional, build monitoring tools around this)
curl -i -u guest:guest http://localhost:15672/api/aliveness-test/%2F
> HTTP/1.1 200 OK
server: Cowboy
date: Fri, 11 May 2018 22:55:25 GMT
content-length: 15
content-type: application/json
vary: accept, accept-encoding, origin
cache-control: no-cache


# Check the status of the broker
kazoo-rabbitmq status

Setting up Kamailio#

# Install Kazoo-wrapped Kamailio
yum install -y kazoo-kamailio

# Update the hostname in the config
sed -i 's/kamailio\.2600hz\.com/' /etc/kazoo/kamailio/local.cfg

# Update the IP addresses
sed -i 's/127\.0\.0\.1/' /etc/kazoo/kamailio/local.cfg

# Start Kamailio
systemctl enable kazoo-kamailio
systemctl restart kazoo-kamailio

# Check that Kamailio is listening (optional)
ss -ln | egrep "5060|7000"
udp    UNCONN     0      0         *:7000                  *:*
udp    UNCONN     0      0         *:5060                  *:*
tcp    LISTEN     0      128       *:5060                  *:*
tcp    LISTEN     0      128       *:7000                  *:*

# check the dispatcher status
kazoo-kamailio status
error: 500 - No Destination Sets

## This error is expected! You haven't added any FreeSWITCH servers for Kamailio to use.

Setting up FreeSWITCH#

# Install Kazoo-wrapped FreeSWITCH
yum install -y kazoo-freeswitch

# Enable and start FreeSWITCH
systemctl enable kazoo-freeswitch
systemctl start kazoo-freeswitch

# Check FreeSWITCH status (you will not see any connected erlang modules)
kazoo-freeswitch status
UP 0 years, 0 days, 0 hours, 0 minutes, 0 seconds, 192 milliseconds, 384 microseconds
FreeSWITCH (Version 1.6.20  64bit) is ready
0 session(s) since startup
0 session(s) - peak 0, last 5min 0
0 session(s) per Sec out of max 200, peak 0, last 5min 0
5000 session(s) max
min idle cpu 0.00/100.00
Current Stack Size/Max 240K/8192K

Running mod_kazoo v1.4.0-1
Listening for new Erlang connections on with cookie change_me
Registered as Erlang node, visible as freeswitch
No erlang nodes connected

# Get the sipify script for FreeSWITCH log parsing (optional)
curl -o /usr/bin/ \
chmod 755 /usr/bin/


mod_sofia isn't loaded on boot. FreeSWITCH is shipped with no dialplan as Kazoo itself controls all of the routing decisions, thus FreeSWITCH isn't of much use until Kazoo is connected.


Kamailio will still not know about FreeSWITCH in the destination sets. FreeSWITCH will be auto-discovered later in the process and added.

Setting up BigCouch#

At this time, BigCouch is still "recommended" solely because we don't have the history in production of running CouchDB. Kazoo works just fine with CouchDB 1.6 and 2.0 so feel free to install and configure those packages instead.

# Install Kazoo-wrapped BigCouch
yum install -y kazoo-bigcouch

# Enable and start BigCouch
systemctl enable kazoo-bigcouch
systemctl start kazoo-bigcouch

# Check that BigCouch is listening (optional)
ss -ln | egrep "5984|5986"
tcp    LISTEN     0      128       *:5984                  *:*
tcp    LISTEN     0      128       *:5986                  *:*

# Check the BigCouch UI (optional): http://localhost:5984/_utils

# Check the status of bigcouch
kazoo-bigcouch status
BigCouch (pid 21325) is running...

Setting up HAProxy#

# Install the Kazoo-wrapped HAProxy
yum -y install kazoo-haproxy

# Edit /etc/kazoo/haproxy/haproxy.cfg to setup the backend server to point to BigCouch
# For AiO installs, it should look something like:
cat /etc/kazoo/haproxy/haproxy.cfg
        log /dev/log local0 info
        maxconn 4096
        user haproxy
        group daemon
        stats socket    /var/run/haproxy/haproxy.sock mode 777

        log global
        mode http
        option httplog
        option dontlognull
    option log-health-checks
        option redispatch
        option httpchk GET /
        option allbackups
        option http-server-close
        maxconn 2000
        retries 3
        timeout connect 6000ms
        timeout client 12000ms
        timeout server 12000ms

listen bigcouch-data
  balance roundrobin
    server check

listen bigcouch-mgr
  balance roundrobin
    server check

listen haproxy-stats
  mode http
  stats uri /

# Enable and start HAProxy
systemctl enable kazoo-haproxy
systemctl start kazoo-haproxy

# Check the status of haproxy
kazoo-haproxy status
|Host                      |Backend         |Status |Active |Rate   |1xx    |2xx    |3xx    |4xx    |5xx    |Ping   |
|             |bigcouch-data   |UP     |0      |0      |0      |0      |0      |0      |0      |1ms    |
|             |bigcouch-mgr    |UP     |0      |0      |0      |0      |0      |0      |0      |1ms    |

curl localhost:15984

curl localhost:15986

curl localhost:15984/_all_dbs

Setting up Kazoo Applications#

At this point, we're ready to install Kazoo as all the infrastructure that Kazoo relies on is in place and ready to be taken control of. The first thing to do is install the Kazoo applications.

# Install all the Kazoo applications (at this time, 4.2.28 for most of the kazoo-application-* packages)
yum install -y kazoo-applications

# Start Kazoo Applications
systemctl enable kazoo-applications
systemctl start kazoo-applications

# Check that the databases are created (may take some time while things initialize)
# Results may vary a bit - should be at least 5 system databases for sure)
curl localhost:15984/_all_dbs

# You should have > 20 DBs
curl localhost:15984/_all_dbs | python -mjson.tool | wc -l

# Import System Media prompts (takes a while)
sup kazoo_media_maintenance import_prompts /opt/kazoo/sounds/en/us/

# If you need to import other languages (optional)
# sup kazoo_media_maintenance import_prompts /opt/kazoo/sounds/fr/ca fr-ca

# It can be a good idea to run a refresh over the installed databases - there are sporadic reports of partial installations hanging at this point
sup kapps_maintenance refresh
<10016.9661.0> (22/22) refreshing database 'system_config'

# Create the admin account, remember to replace the braced fields
# Example: To create an account with the username root, replace {ADMIN_USER} with root
sup crossbar_maintenance create_account \
View updated for account%2Fed%2F1f%2F03d6cf3b8135fe3b008847d92c65!
created new account 'ed1f03d6cf3b8135fe3b008847d92c65' in db 'account%2Fed%2F1f%2F03d6cf3b8135fe3b008847d92c65'
created new account admin user '002bc4e8687292f9e4085a590fa61eab'
promoting account ed1f03d6cf3b8135fe3b008847d92c65 to reseller status, updating sub accounts
updated master account id in system_config.accounts

# Use SUP to communicate with the running VM

# Check the status of the Kazoo cluster
kazoo-applications status
Node          :
md5           : o4fNOLAQ3LJSAzliaNiT1A
Version       : 4.2.28 - 19
Memory Usage  : 76.42MB
Processes     : 1716
Ports         : 23
Zone          : local
Broker        : amqp://
Globals       : local (4)
Node Info     : kz_amqp_pool: 150/0/0 (ready)
WhApps        : blackhole(1d2h16m23s)    callflow(1d2h16m22s)     conference(1d2h16m21s)   crossbar(1d2h16m21s)
                fax(1d2h16m18s)          hangups(1d2h15m58s)      media_mgr(1d2h15m58s)    milliwatt(1d2h15m57s)
                omnipresence(1d2h15m57s) pivot(1d2h15m57s)        registrar(1d2h15m57s)    reorder(1d2h15m57s)
                stepswitch(1d2h15m56s)   sysconf(1d2h16m24s)      tasks(1d2h15m56s)        teletype(1d2h14m54s)
                trunkstore(1d2h14m31s)   webhooks(1d2h14m31s)

Node          :
Version       : 5.0.4
Memory Usage  : 15.26MB
Zone          : local
Broker        : amqp://
WhApps        : kamailio(4d18h50m7s)
Roles         : Dispatcher Presence Proxy Registrar
Subscribers   :
Subscriptions :
Presentities  : presence (0)  dialog (0)  message-summary (0)
Registrations : 0

Setting up ecallmgr#

# Install Kazoo eCallMgr, it should install with kazoo-applications above but to be sure
yum install -y kazoo-application-ecallmgr

# Start Kazoo eCallMgr
systemctl enable kazoo-ecallmgr
systemctl start kazoo-ecallmgr

# eCallMgr will attempt to auto-connect to the local FreeSWITCH if possible
kazoo-applications status
Node          :
md5           : H5AnAyj8ESMlFPfqhmSAqw
Version       : 4.2.28 - 19
Memory Usage  : 46.11MB
Processes     : 1168
Ports         : 35
Zone          : local
Broker        : amqp://
Globals       : total (0)
Node Info     : kz_amqp_pool: 150/0/0 (ready)
WhApps        : ecallmgr(1m41s)
Channels      : 0
Conferences   : 0
Registrations : 0
Media Servers : (1m34s)

# If you don't see the "Media Servers" line:
# you can explicitly add FreeSWITCH servers to ecallmgr
sup -n ecallmgr ecallmgr_maintenance add_fs_node

# Add Kamailio to the SBC ACLs
sup -n ecallmgr ecallmgr_maintenance allow_sbc kam1
updating authoritative ACLs kam1( to allow traffic
issued reload ACLs to

# List SBC ACLs
sup -n ecallmgr ecallmgr_maintenance sbc_acls
| Name                           | CIDR               | List          | Type  | Authorizing Type | ID                               |
| kam1                           |    | authoritative | allow | system_config    |                                  |

# Check FreeSWITCH for ecallmgr connection info
kazoo-freeswitch status
Running mod_kazoo v1.4.0-1
Listening for new Erlang connections on with cookie change_me
Registered as Erlang node, visible as freeswitch
Connected to: ( up 0 years, 0 days, 0 hours, 7 minutes, 38 seconds

# Check that Kamailio sees FreeSWITCH
kazoo-kamailio status
    NRSETS: 1
    RECORDS: {
        SET: {
            ID: 1
            TARGETS: {
                DEST: {
                    FLAGS: AP
                    PRIORITY: 0

Setting up MonsterUI#

# Install Monster UI, UI Apps, and Apache
yum -y install monster-ui* httpd

# Update Monster's config for Crossbar's URL
sed -i 's/localhost/' /var/www/html/monster-ui/js/config.js

# Initialize Monster Apps
sup crossbar_maintenance init_apps \
/var/www/html/monster-ui/apps \
trying to init app from /var/www/html/monster-ui/apps/numbers
 saved app numbers as doc 94d5eadd9a0531fff63dd886882fe5a1
   saved NumberManager_app.png to 94d5eadd9a0531fff63dd886882fe5a1
   saved numbermanager1.png to 94d5eadd9a0531fff63dd886882fe5a1
   saved numbermanager2.png to 94d5eadd9a0531fff63dd886882fe5a1
trying to init app from /var/www/html/monster-ui/apps/callflows
 saved app callflows as doc 10c442ad16813b8339b36c5c5da373eb
   saved Callflows_app.png to 10c442ad16813b8339b36c5c5da373eb
   saved callflows_1.png to 10c442ad16813b8339b36c5c5da373eb
   saved callflows_2.png to 10c442ad16813b8339b36c5c5da373eb
   saved callflows_3.png to 10c442ad16813b8339b36c5c5da373eb
trying to init app from /var/www/html/monster-ui/apps/fax
 saved app fax as doc 7b15d543fd1cb6cba7988ff15fbf81f4
   saved Fax_app.png to 7b15d543fd1cb6cba7988ff15fbf81f4
   saved OutboundFaxes.png to 7b15d543fd1cb6cba7988ff15fbf81f4
trying to init app from /var/www/html/monster-ui/apps/voicemails
 saved app voicemails as doc 7685e788208c53aa88adea31419db2c0
   saved Voicemail_app.png to 7685e788208c53aa88adea31419db2c0
   saved PlayVoicemail.png to 7685e788208c53aa88adea31419db2c0
   saved SelectedVoicemails.png to 7685e788208c53aa88adea31419db2c0
trying to init app from /var/www/html/monster-ui/apps/webhooks
 saved app webhooks as doc b74bcdd908472f793529a2252f512808
   saved WebHooks_app.png to b74bcdd908472f793529a2252f512808
   saved webhooks1.png to b74bcdd908472f793529a2252f512808
   saved webhooks2.png to b74bcdd908472f793529a2252f512808
trying to init app from /var/www/html/monster-ui/apps/voip
 saved app voip as doc 8258579e9af38d7ac21c61d4f35ec85f
   saved SmartPBX_app.png to 8258579e9af38d7ac21c61d4f35ec85f
   saved smartpbx1.png to 8258579e9af38d7ac21c61d4f35ec85f
   saved smartpbx2.png to 8258579e9af38d7ac21c61d4f35ec85f
   saved smartpbx3.png to 8258579e9af38d7ac21c61d4f35ec85f
   saved smartpbx4.png to 8258579e9af38d7ac21c61d4f35ec85f
   saved smartpbx5.png to 8258579e9af38d7ac21c61d4f35ec85f
trying to init app from /var/www/html/monster-ui/apps/accounts
 saved app accounts as doc eae7a2a348976fb4a56671792dafd0a0
   saved Accounts_app.png to eae7a2a348976fb4a56671792dafd0a0
   saved Account-AvailableApps.png to eae7a2a348976fb4a56671792dafd0a0
   saved Account-Limits.png to eae7a2a348976fb4a56671792dafd0a0
   saved AccountOverview.png to eae7a2a348976fb4a56671792dafd0a0
trying to init app from /var/www/html/monster-ui/apps/pbxs
 saved app pbxs as doc 507f424503a1beb47b383c180b81ca17
   saved PBXconnector_app.png to 507f424503a1beb47b383c180b81ca17
   saved pbxconnector1.png to 507f424503a1beb47b383c180b81ca17
   saved pbxconnector2.png to 507f424503a1beb47b383c180b81ca17

# Start Apache to serve Monster
systemctl enable httpd
systemctl start httpd

# Create the virtual host
echo "<VirtualHost *:80>
  DocumentRoot \"/var/www/html/monster-ui\"
" > /etc/httpd/conf.d/

# Reload Apache
systemctl reload httpd

# Check that Crossbar (the API server) is accessible (responding to requests)
{"data":{"message":"invalid credentials"},"error":"401","message":"invalid_credentials","status":"error","timestamp":"2018-05-16T19:08:00","version":"4.2.28","node":"o4fNOLAQ3LJSAzliaNiT1A","request_id":"aeceb6ad9c4f754f92ff8f34e2e8b605","auth_token":"undefined"}


# You can now load MonsterUI in your browser at
# Use the credentials from the create_account step to log in



There was an issue with librabbitmq versions when installing/updating kazoo-kamailio. If you see something like:

Error: Package: kamailio-kazoo-5.0.4j-3.1.x86_64 (2600hz-stable)

You can workaround this by disabling the base repo (hat-tip btel):

yum remove librabbitmq
yum --disablerepo="*" --enablerepo=epel install librabbitmq
yum install kazoo-kamailio

CouchDB / Bigcouch#

If creating the first account fails, or you see the following in /var/log/bigcouch/bigcouch.log:

[Tue, 15 May 2018 04:03:03 GMT] [info] [<0.124.0>] [--------] couch_proc_manager <0.3773.0> died normal
[Tue, 15 May 2018 04:03:03 GMT] [error] [<0.254.0>] [941cd296] OS Process Error <0.3792.0> :: {<<"unnamed_error">>,
                                                               <<"(new TypeError(\"cmd is undefined\", \"/opt/bigcouch/share/couchjs/main.js\", 1474))">>}
[Tue, 15 May 2018 04:03:03 GMT] [info] [<0.124.0>] [--------] couch_proc_manager <0.3781.0> died normal

This was caused by a CentOS update to the js package from 1.8.5-19 to -20.

2600Hz is hosting the -19 version now; if you've installed -20 you'll need to downgrade:

yum downgrade js-1:1.8.5-19.el7.x86_64

See the CouchDB issue if you want more info.