Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?

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.

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).

# 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 4.0 RPM here:
export RPMFILE=2600hz-release-4.0-1.el7.centos.noarch.rpm
RPMPATH=artifacts/2600hz-release/4.0/centos/7/; \
yum install $RPMFILE
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

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

# Check that RabbitMQ is listening
ss -lpn | grep "5672"

# If you need to forward a port in an active SSH session
# In this case, forward the management port of RabbitMQ
ssh> -L 15672:localhost:15672
Forwarding port.

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

# Check out the API (build monitoring tools around this)
curl -i -u guest:guest \

curl -i -u guest:guest \

# 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
ss -ln | egrep "5060|7000"

# Add FreeSWITCH to the dispatcher list (FreeSWITCH doesn't exist yet)
echo ":1:sip\\:11000:0:0::aio-fs" \
>> /etc/kazoo/kamailio/dbtext/dispatcher

# Reload the dispatcher
kamctl fifo ds_reload

# check the dispatcher status
kazoo-kamailio status

# Check stats for the kamailio
kamctl stats

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
fs_cli -x status

# Check mod_kazoo status
fs_cli -x 'erlang status'

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

Do note that 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.

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
ss -ln | egrep "5984|5986"

# If you need to forward a port to access the API (optional)
ssh> -L 5984:localhost:5984

# Check the API
curl localhost:5984

# Check the admin API
curl localhost:5986

# Check nodes involved in the cluster
curl localhost:5984/_membership | python -mjson.tool

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

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

# Test the API via HAProxy
curl localhost:15984

Setting up Kazoo Applications

# Install all the Kazoo applications
yum install -y kazoo-applications kazoo-application-*

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

# Check all the databases created (may take some time while things initialize)
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

# Create the admin account
sup crossbar_maintenance create_account \

# Use SUP to communicate with the running VM
sup -h

Setting up ecallmgr

Traditionally ecallmgr ran in its own VM. This is no longer required and ecallmgr can run in the same VM as the rest of the Kazoo applications if you choose.

# Start ecallmgr if needed
sup kapps_controller start_app ecallmgr

# Add FreeSWITCH to ecallmgr
sup ecallmgr_maintenance add_fs_node

# Add Kamailio to the SBC ACLs
sup ecallmgr_maintenance allow_sbc kamailio1

# List SBC ACLs
sup ecallmgr_maintenance sbc_acls

# Check FreeSWITCH for ecallmgr connection info
fs_cli -x "erlang status"

# Check the status of the VM
kazoo-applications status

# Check that Sofia is loaded
fs_cli -x 'sofia status'

# Check that Kamailio sees FreeSWITCH
kazoo-kamailio status

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 \

# 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 is accessible

# You can now load MonsterUI in your browser at

Hi James,
Great installation guide!
I was following this, and had some questions/remarks..

  1. In my install of Centos7 (Minimal) I missed gdb, so maybe good to add that in also, else I could not get "kamctl fifo ds_reload" to work
  2. In the setup of HAProxy you write the following "# Edit /etc/kazoo/haproxy/haproxy.cfg to setup the backend server to point to BigCouch" is this also relevant when installing an single server setup ??

Not sure if this was due to I did not configure the haproxy, but I could not get the SUP command to create the admin account:

[root@kazoo ~]# sup crossbar_maintenance create_account {myaccount_name} {myaccount_realm} {username} {password}
failed to validate account properties(error): '{}'


Nevermind my last comment about the admin account, as I found my error (typo) just needed to remove the {brackets}, and it worked :-)


jamesaimonetti commented Nov 18, 2016

@mdruedal HAProxy is useful in a clustered environment to hide where all the couch servers are - the kazoo apps can just talk to the local haproxy and get connected to whichever couch servers are available at that time. For single-server, it is less important but included for completeness.

I'll look into the gdb issue but it shouldn't be required to get the ds_reload working.

Thanks @jamesaimonetti,
What do I need to make ecallmgr start on boot ??

onnet commented Nov 20, 2016

@mdruedal Try systemctl enable kazoo-ecallmgr.service
@jamesaimonetti Is there any drawbacks running ecallmgr within kazoo_app vm?


jamesaimonetti commented Nov 21, 2016

@onnet only that ecallmgr competes with other apps in the VM for resources like memory or CPU time on the schedulers.

alocaurd commented Dec 5, 2016

Hey James, this is great! Any plans on a CentOS Kazoo v3 to v4 upgrade guide?

Hello, Just tried to do this install and I keep getting this error:

Am I missing a step or has that file not been updated yet?


bingy92 commented Dec 11, 2016

When I try to create admin account using command:

sup crossbar_maintenance create_account

I get error:

failed to validate account properties(error): '"schema accounts not found."'

Any ideas how to fix?


Hello James,

I tried to install kazoo v4.0 but, I am getting the same error which @monkeyskull was getting. Please check the screenshot


Can anyone please suggest me what the issue is?

Anurag Mishra

@jamesaimonetti Any updates on @monkeyskull error ? I am facing similar error while building with these instructions.

bsingh commented Jan 17, 2017

@anuragmishra1 , you can disable experimental repos in and enable staging one in /etc/yum.repos.d/2600Hz-testing.repo

Any chance of getting a multi-server setup guide? The older multi-server setup guides seem to be outdated.

anchorman55555 commented Jan 25, 2017

The author thanks!

but after entering the credentials get a message here:

Oops! Something went wrong!
An unknown error happened, please try again in a few seconds!
More Information
"abort": undefined,
"always": undefined,
"complete": undefined,
"done": undefined,
"error": undefined,
"fail": undefined,
"getAllResponseHeaders": undefined,
"getResponseHeader": undefined,
"monsterData": ⊖{
"url": "",
"verb": "PUT"
"overrideMimeType": undefined,
"pipe": undefined,
"progress": undefined,
"promise": undefined,
"readyState": 0,
"responseText": "",
"setRequestHeader": undefined,
"state": undefined,
"status": 0,
"statusCode": undefined,
"statusText": "error",
"success": undefined,
"then": undefined,

Where my problem? Help me pls

@anchorman55555 - it looks like you fogot to edit this section and put your own IP in it:

Initialize Monster Apps

sup crossbar_maintenance init_apps

When trying to start RabbitMQ I get the following error:

Failed to start RabbitMQ Broker Configured for Kazoo.

agplacid commented Jun 5, 2017

Can I install the package on google cloud?

@jamesaimonetti @monkeyskull & @gauravsaini03
You may want to run the stable release anyway... Looks like the instructions default you to the testing repo.
Enable the 2600Hz repo and disable the 2600Hz-testing repo.


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment