Asterisk

What is Asterisk ?

Asterisk is an Open Source telephony server. Asterisk can handle traditional telephony hardware and be connected to your telephony provider, but Asterisk can also be used to connect VoIP phones locally and on the Internet. In case a SIP subscription is included with your Internet access, you will be able to use it to access the telephony network. And if you need simultaneous calls, then you will be able to use a multi-channel "SIP trunk", that you can get from one of the many SIP providers on the market. Among various applications, Asterisk affords leaving recorded messages and sending them by mail, or doing some conferencing.

From a practical viewpoint, Asterisk is easy to install but requires quite some efforts to understand and properly configure, as it is massive and the available documentation is not easy to understand, or some key points are sometimes missing. Also the configuration files are sensitive to syntax errors and the software will stop working, with no clue on what's wrong. However these syntax difficulties are during configuration only. When fixed, the software seems to be quite stable.

Installing Dahdi

Dahdi-linux is a set of Asterisk linux modules required only when using telephony hardware. It was once also required to provide timing functions to the rest of the sofware but this is no longer the case so you probably don't need to install it. If you do, download then untar and install.

# tar -C /usr/local -xvf dahdi-linux-x.y.z.tar.gz
# cd /usr/local/include
# ln -s ../dahdi-linux-x.y.z/linux/include/dahdi .
# cd /usr/local/dahdi-linux-x.y.z
# make
# make install
# make clean

That's it. Note : the other package Dahdi-tools is not required. Other note : Dahdi requires a kernel compiled with CONFIG_CRC_CCITT=y.

Installing Jansson

Jansson is a required Json development library. Download then untar and install.

# tar -C /usr/local -xvf jansson-x.y.z.tar.gz
# cd /usr/local/jansson-linux-x.y.z
# ./configure --prefix=/usr/local --libdir=/usr/local/lib64
# make
# make install
# make clean

Installing c-client

The asterisk imap option requires presence of library c-lient.a, which is part of Imap-uw, by the University of Washington. The University of Washington seems to be no longer distributing the software so we keep a copy for your convenience. Download then untar and install :

# gunzip c-client.tar.Z
# tar -C /usr/local -xvf c-client.tar
# cd /usr/local
# chown -R root:root imap-2007f
# chmod -R o-w imap-2007f
# cd imap2007f
# make slx EXTRACFLAGS="-I/usr/include/openssl -g -O2 -fPIC" SSLCERTS=/etc/ssl/certs SSLKEYS=/etc/ssl/private

Installing Speex

Speex is a required free codec. Download speex source code then untar and install.

# tar -C /usr/local -xvf speex-x.y.z.tar.gz
# cd /usr/local/speex-x.y.z
# ./configure --prefix=/usr/local --libdir=/usr/local/lib64
# make
# make install
# make clean

Installing Asterisk

Download Asterisk then untar and install. Make menuselect affords choosing which components to use. If using mysql, be sure to read the next paragraph before invoking make. Otherwise proceed. make samples affords creating the configuration files in /usr/local/etc/asterisk.

# groupadd asterisk
# useradd -g asterisk asterisk
# tar -C /usr/local --no-same-permissions --no-same-owner -xvf asterisk-x.y.z.t.tar.gz
# cd /usr/local/asterisk-x.y.z.t
# ./configure --prefix=/usr/local --libdir=/usr/local/lib64 --mandir=/usr/local/man \
--with-asound --with-crypto --with-iconv --with-imap=/usr/local/imap-2007f \
--with-jansson --with-ldap --with-speex --with-ssl
# make menuselect
# make
# make install
# make install-logrotate
# make samples
# make clean
# chown -R asterisk:asterisk /usr/local/lib64/asterisk
# chown -R asterisk:asterisk /usr/local/var/lib/asterisk
# chown -R asterisk:asterisk /usr/local/var/log/asterisk
# chown -R asterisk:asterisk /usr/local/var/run/asterisk
# chown -R asterisk:asterisk /usr/local/var/spool/asterisk
# chmod o+x /usr/local/etc/asterisk
# chmod o-x /usr/local/lib64/asterisk
# chmod o-x /usr/local/var/lib/asterisk
# chmod o-x /usr/local/var/log/asterisk
# chmod o-x /usr/local/var/run/asterisk
# chmod o-x /usr/local/var/spool/asterisk

If using mysql modules, there might be a glitch with the mysql include path. Replace in the files below the lines with "#include <mysql/mysql.h>" by lines with "#include <mysql.h>" (removing the directory) :

addons/app_mysql.c
addons/cdr_mysql.c
addons/res_config_mysql.c

It is then possible to launch asterisk in the foreground with various levels of verbosity (depending on the number of v's). However the default configuration files include a number of options that we don't want, so we'll rename them first and start with empty files. Asterisk includes a console and then proposes a shell :

# cd /usr/local/etc/asterisk
# mv extensions.conf extensions.conf.sample
# mv extensions.ael extensions.ael.sample
# mv sip.conf sip.conf.sample
# sudo -u asterisk asterisk -vvvc
. . .
*CLI>

Type help to view the available commands, however before doing anything useful we'll need to modify the configuration files so let's just core stop gracefully here.

Running asterisk

Asterisk runs as a daemon so must be launched at startup and stopped at shutdown. Update /etc/rc.d/rc.local and /etc/rc.d/rc.local_shutdown accordingly :

# vi /etc/rc.d/rc.local
. . .
# start asterisk
if [ -x /usr/local/sbin/safe_asterisk ]; then
        echo "Starting asterisk: /usr/local/sbin/safe_asterisk -G asterisk -U asterisk -p"
        /usr/local/sbin/safe_asterisk -G asterisk -U asterisk -p
fi
<esc>
:x
# vi /etc/rc.d/rc.local_shutdown
. . .
# stop asterisk
if [ -r /usr/local/var/run/asterisk/asterisk.pid ]; then
        echo "Stopping asterisk: kill -INT `cat /usr/local/var/run/asterisk/asterisk.pid`"
        kill -INT `cat /usr/local/var/run/asterisk/asterisk.pid`
fi
<esc>
:x

Configuring Asterisk

Asterisk running in the backgroung, it's possible to attach to the process using asterisk -r and to exit the asterisk shell by typing exit. Most of the configuration files can be modified externally then reloaded using commands such as dialplan reload, sip reload, or voicemail reload. A few files however cannot (example confbridge.conf), and require restarting using core restart now. Type help to get a complete list of commands.

The configuration files are created under EPREFIX/etc and there are many of them (112 in version 1.15.0.0 !). The bad news is that they must be all reviewed and modified to remove unneeded configuration options. When done though, modifying only a few will afford getting a working system with a reasonnable set of features. We decided to use LDAP to configure our users so this is what is detailed below.

Note : the asterisk configuration files are organized in contexts whose names are enclosed in square brackets on a line of its own. Definitions in these contexts - otherwise mentionned - are valid inside these contexts only.

Configuration file	Usage
sip.conf	to configure sip accounts
res_ldap.conf	to configure LDAP users
confbridge.conf	to configure conferences
voicemail.conf	to configure voicemail boxes
extensions.conf	to configure the dialplan