RJ Systems
Linux System Administration
Home Tech Linux Links Consulting







Valid XHTML 1.0!

Valid CSS!

IPv6 test

Asterisk: minimal SIP configuration

Introduction

Asterisk is an open source PBX that runs on Linux and many other operating systems. It was created in 1999 by Mark Spencer, the founder of Digium, which is a privately-held company based in Huntsville, Alabama. Among other things, Digium is specialized in developing hardware for use with Asterisk. As a result, Asterisk may not be vendor-independent, but it is still the most popular open source PBX.

The development of Asterisk was significant, because it marked the first time that organizations and individuals could set up their own PBX without losing an arm and a leg. Instead, the cost of an Asterisk PBX need only consist of the hardware that it runs on and the phones that connect to it; all of which are standardized, readily available and thus affordable.

Like any PBX, Asterisk is basically a router for incoming and outgoing telephone calls. It can be configured to support a range of external connections using various media and protocols, as well as a large number of endpoints: usually telephones that connect to Asterisk via the network (or the Internet) using one protocol or another.

This page describes how to install a minimal, SIP-only Asterisk system on Debian 5.0 (lenny). The operating system comes with Asterisk 1.4.21 and Zaptel 1.4.11. Actually, Debian supplies two Zaptel packages: zaptel and zaptel-source, with a zaptel-modules package that must be compiled from the latter. The installation and configuration procedures below assume that a minimal Debian lenny system is already up and running, that a SIP-capable phone is available, possibly through the use of a SIP adapter, and that an external SIP account is available through a commercial VoIP provider.


1. Asterisk install

Start by installing the following three packages:

~# apt-get install asterisk zaptel zaptel-source

Assuming that nothing beyond a basic system exists at this point, a total of 75 packages will be installed as a result, including 72 dependencies:

asterisk                      1:1.4.21.2~dfsg-3+lenny1 Open Source Private Branch Exchange (PBX)
asterisk-config               1:1.4.21.2~dfsg-3+lenny1 Configuration files for Asterisk
asterisk-sounds-main          1:1.4.21.2~dfsg-3+lenny1 Core Sound files for Asterisk (English)
binutils                      2.18.1~cvs20080103-7     The GNU assembler, linker and binary utilities
build-essential               11.4                     Informational list of build-essential packages
bzip2                         1.0.5-1                  high-quality block-sorting file compressor - utilities
ca-certificates               20080809                 Common CA certificates
cpp                           4:4.3.2-2                The GNU C preprocessor (cpp)
cpp-4.3                       4.3.2-1.1                The GNU C preprocessor
debhelper                     7.0.15                   helper programs for debian/rules
dpkg-dev                      1.14.29                  Debian package development tools
fxload                        0.0.20020411-1.1         Firmware download to EZ-USB devices
g++                           4:4.3.2-2                The GNU C++ compiler
g++-4.3                       4.3.2-1.1                The GNU C++ compiler
gcc                           4:4.3.2-2                The GNU C compiler
gcc-4.2-base                  4.2.4-6                  The GNU Compiler Collection (base package)
gcc-4.3                       4.3.2-1.1                The GNU C compiler
gcc-4.3-base                  4.3.2-1.1                The GNU Compiler Collection (base package)
gettext                       0.17-4                   GNU Internationalization utilities
gettext-base                  0.17-4                   GNU Internationalization utilities for the base system
html2text                     1.3.2a-5                 advanced HTML to text converter
intltool-debian               0.35.0+20060710.1        Help i18n of RFC822 compliant config files
libasound2                    1.0.16-2                 ALSA library
libc-client2007b              7:2007b~dfsg-4+lenny3    c-client library for mail protocols - library files
libc6-dev                     2.7-18lenny2             GNU C Library: Development Libraries and Header Files
libcompress-raw-zlib-perl     2.012-1lenny1            low-level interface to zlib compression library
libcompress-zlib-perl         2.012-1                  Perl module for creation and manipulation of gzip files
libcurl3                      7.18.2-8lenny4           Multi-protocol file transfer library (OpenSSL)
libdigest-hmac-perl           1.01-7                   create standard message integrity checks
libdigest-sha1-perl           2.11-2+b1                NIST SHA-1 message digest algorithm
libfile-remove-perl           1.42-1                   remove files and directories, accepts wildcards
libgcc1                       1:4.3.2-1.1              GCC support library
libgmp3c2                     2:4.2.2+dfsg-3           Multiprecision arithmetic library
libgomp1                      4.3.2-1.1                GCC OpenMP (GOMP) support library
libgsm1                       1.0.12-1                 Shared libraries for GSM speech compressor
libiksemel3                   1.2-4                    C library for the Jabber IM platform
libio-compress-base-perl      2.012-1                  Base Class for IO::Compress modules
libio-compress-zlib-perl      2.012-1                  Perl interface to zlib
libio-stringy-perl            2.110-4                  Perl modules for IO from scalars and arrays
liblocale-gettext-perl        1.05-4                   Using libc functions for internationalization in Perl
libltdl3                      1.5.26-4+lenny1          A system independent dlopen wrapper for GNU libtool
libmail-box-perl              2.082-2                  Manage a message-folder
libmail-sendmail-perl         0.79-5                   Send email from a perl script
libmailtools-perl             2.03-1                   Manipulate email in perl programs
libmime-types-perl            1.24-1                   Perl extension for determining MIME types and Transfer Encodin
libmpfr1ldbl                  2.3.1.dfsg.1-2           multiple precision floating-point computation
libobject-realize-later-perl  0.18-1                   Delayed creation of objects
libogg0                       1.1.3-4                  Ogg Bitstream Library
libperl5.10                   5.10.0-19lenny2          Shared Perl library
libpq5                        8.3.9-0lenny1            PostgreSQL C client library
libpri1.0                     1.4.3-2                  Primary Rate ISDN specification library
libradiusclient-ng2           0.5.5-1                  Enhanced RADIUS client library
libsensors3                   1:2.10.7-1               library to read temperature/voltage/fan sensors
libsnmp-base                  5.4.1~dfsg-12            SNMP (Simple Network Management Protocol) MIBs and documentati
libsnmp15                     5.4.1~dfsg-12            SNMP (Simple Network Management Protocol) library
libspeex1                     1.2~rc1-1                The Speex codec runtime library
libspeexdsp1                  1.2~rc1-1                The Speex extended runtime library
libsqlite0                    2.8.17-4                 SQLite shared library
libssh2-1                     0.18-1                   SSH2 client-side library
libsys-hostname-long-perl     1.4-2                    Figure out the long (fully-qualified) hostname
libsysfs2                     2.1.0-5                  interface library to sysfs
libtimedate-perl              1.1600-9                 Time and date functions for Perl
libtonezone1                  1:1.4.11~dfsg-3          tonezone library (runtime)
liburi-perl                   1.35.dfsg.1-1            Manipulates and accesses URI strings
libuser-identity-perl         0.92-2                   manages different identities/roles used by a physical person
libvorbis0a                   1.2.0.dfsg-3.1+lenny1    The Vorbis General Audio Compression Codec
libvorbisenc2                 1.2.0.dfsg-3.1+lenny1    The Vorbis General Audio Compression Codec
libvpb0                       4.2.38.1-1               Voicetronix telephony hardware userspace interface library
linux-libc-dev                2.6.26-21lenny4          Linux support headers for userspace development
make                          3.81-5                   The GNU version of the "make" utility.
makedev                       2.3.1-88                 creates device files in /dev
mlock                         7:2007b~dfsg-4+lenny3    mailbox locking program
module-assistant              0.10.11.0                tool to make module package creation easier
odbcinst1debian1              2.2.11-16                Support library and helper program for accessing odbc ini file
openssl                       0.9.8g-15+lenny6         Secure Socket Layer (SSL) binary and related cryptographic too
po-debconf                    1.0.15                   manage translated Debconf templates files with gettext
unixodbc                      2.2.11-16                ODBC tools libraries
vpb-driver-source             4.2.38.1-1               Source for the Voicetronix telephony hardware drivers
zaptel                        1:1.4.11~dfsg-3          zapata telephony utilities
zaptel-source                 1:1.4.11~dfsg-3          Zapata telephony interface (source code for kernel driver)

This produces a basic Asterisk installation. However, there is one error message that appears almost at the end of the install process:

Zaptel telephony kernel driver: FATAL: Module ztdummy not found.

The issue of this missing module is addressed in the next step.


2. Zaptel modules

There is no real cause for concern regarding the previous error message. Rather, it should be seen as a reminder of what to do next, which is to compile and install the Zaptel modules. Luckily, this is easily done with the module-assistant:

~# m-a a-i zaptel

The m-a command is a symlink for module-assistant, while the a-i option is short for auto-install.

Before the actual build process starts, the above command will automatically install six new packages, including three that are kernel-specific:

cpp-4.1                       4.1.2-25                 The GNU C preprocessor
gcc-4.1                       4.1.2-25                 The GNU C compiler
gcc-4.1-base                  4.1.2-25                 The GNU Compiler Collection (base package)
linux-headers-2.6.26-2-686    2.6.26-21lenny4          Header files for Linux 2.6.26-2-686
linux-headers-2.6.26-2-common 2.6.26-21lenny4          Common header files for Linux 2.6.26-2
linux-kbuild-2.6.26           2.6.26-3                 Kbuild infrastructure for Linux 2.6.26

The end result is that the zaptel-modules package is produced and installed, including a number of modules for the running kernel. Among these is ztdummy.ko, which will take care of the aforementioned error. This module provides the clock source that Asterisk uses as a timing mechanism, e.g. to help it keep multiple audio streams synchronized while mixing them together.

Load the ztdummy module and restart Asterisk with the following commands:

~# modprobe ztdummy
~# /etc/init.d/asterisk restart
Stopping Asterisk PBX: asterisk.
Starting Asterisk PBX: asterisk.
~# _

A quick check with lsmod will show that, actually, a total of three new modules are loaded as a result:

ztdummy                 3056  0 
zaptel                185060  1 ztdummy
crc_ccitt               2080  1 zaptel

According to their modinfo output, the other two provide the "Zapata Telephony Interface" and "CRC-CCITT calculations." The latter, incidentally, is not part of the Zaptel package.


3. SIP channel config

In this example, the SIP protocol is used both for setting up a channel to the PSTN, using an account with a commercial VoIP provider, and for configurating a local phone for testing puposes. For both of these, changes must first be made to /etc/asterisk/sip.conf, which is the SIP configuration file. Initially, this file contains mostly comments, so rename it for now:

~# mv /etc/asterisk/sip.conf /etc/asterisk/sip.conf-org
~# _

After that, create a new, empty version of this file and modify its ownership and permissions:

~# touch /etc/asterisk/sip.conf
~# chown asterisk.asterisk /etc/asterisk/sip.conf
~# chmod 640 /etc/asterisk/sip.conf
~# _

Then edit the new and empty /etc/asterisk/sip.conf to add a number of things. Start with a [general] section, the options under which will apply to all other sections in this file unless they are overridden specifically:

[general]
disallow=all
allow=ulaw
allow=alaw
allow=gsm
qualify=yes
canreinvite=no

The explanations for these settings are as follows:

disallow=all Disables the use of all codecs. Used before specific codecs are enabled in order of preference.
allow=ulaw Enables a codec based on the μ-law algorithm that is used primarily in North America and Japan. Provides slightly more dynamic range than A-law. This is a 64 kbps PCM (Pulse Code Modulation) codec and a companding variant of the ITU-T G.711 standard. All such codecs impose a minimal load on the CPU.
allow=alaw Enables a codec based on the A-law algorithm that is used in Europe and the rest of the world. Requires even less CPU processing power than μ-law. In the USA, it is used by convention for international connections if at least one party uses it. Another ITU-T G.711 variant.
allow=gsm Enables the GSM 06.10 codec, which is the preferred codec for Asterisk. It operates at 13 kbps, employs lossy speech compression, has no licensing requirements and offers excellent CPU-related performance.
qualify=yes When enabled, SIP NOTIFY messages will periodically be sent to the remote peer to determine both its availability and the latency of its replies.
canreinvite=no Prevents the two end points from connecting to each other directly, which is normal behavior when using SIP. This forces Asterisk to remain in the transmission path, which is necessary to detect DTMF signals. Some commercial SIP providers also do this.

Besides the above, three more additions are necessary before it will be possible to make and receive calls. The first is an outbound SIP registration that will authenticate this system to the VoIP provider, let it know what this system's IP address is and that it is available. Such registration statements have the following format:

register => user[:secret[:authuser]]@host[:port][/extension]

In the example registration statement below, jsmith will be the name of the remote account, 1234 the secret (password), provider.example.com the name of the VoIP provider's server and 0715551234 the destination for the call. The extension, 0715551234, is descriptive, but arbitrary − it can even be alphanumeric. Based on this information, the registration statement should be:

register => jsmith:1234@provider.example.com/0715551234

Add this registration statement to the end of the file under the [general] context mentioned above.

The next section to add to the local sip.conf will handle incoming and outgoing calls between this host and the one maintained by the commercial VoIP provider. Add it to the end of the file, below the registration statement:

[provider]
type=peer
context=incoming
host=provider.example.com
username=jsmith
fromuser=jsmith
secret=1234

Explanation:

[provider] Section title. All lines between this section title and the next apply to this section only. This name will be referred to in the dial plan to establish outgoing calls.
type=peer Definition of the connection type. Type peer is for outgoing connections. Used in cases when the remote host is not expected to place calls (for routing) to this host − only vice versa.
context=incoming The name specified here, which is arbitrary, will determine where incoming calls will enter the dial plan when they arrive on the channel associated with this section.
host=provider.example.com Sets the name of the remote host to which this host must connect. In this case the value must be a fully qualified domain name.
username=jsmith Sets the username with which Asterisk authenticates to a peer, as well as the username for the peer to use when authenticating to Asterisk. This overrides the name in the section title (between the square brackets) that is normally used for this purpose. Also allows registration with a peer before that peer has registered with Asterisk. This option may also be required by other features, such as dialout from voicemail.
fromuser=jsmith Another method of specifying the username for authentication with a peer to override the name in the section title. With some SIP providers, this option may be required for the channel definition to work.
secret=1234 Sets the password. Used for authentication together with the name (title) of this section, which in this case is overridden by fromuser=jsmith.

The third new section is for the phone that is to be attached to the new server. Its name ([sip-phone]) and password (5678) are basically arbitrary, but they must match those used in the phone's SIP client software configuration. Again, add it to the end of the file:

[sip-phone]
type=friend
context=outgoing
host=dynamic
secret=5678

Explanation:

[sip-phone] Section title. All lines between this section title and the next apply to this section only. Together with the secret, this name will be used for authentication by the SIP client be referred to in the dial plan when incoming calls need to be routed to this phone.
type=friend Definition of the connection type. Type friend is a combination of both user and peer types, since the remote host can connect to this host, as well as vice versa.
context=outgoing The name specified here, which is arbitrary, will determine where outgoing calls will enter the dial plan when they are made with the phone associated with this section.
host=dynamic Configures the host to which this host is to connect, although dynamic is used to indicate that the connecting host uses a dynamic IP address.
secret=5678 Sets the password. Used for authentication together with the name (title) of this section.

After saving these edits, submit the changes to the already running Asterisk process with this command:

~# asterisk -rx "sip reload"
~# _

At this point, the idea is to configure the phone's SIP client software to authenticate to Asterisk. Set the method for sending DTMF signaling information to rfc2833, which is recommended for in-band signalling and is the default for Asterisk. The phone should also attempt to authenticate itself to the IP address or FQDN of the new Asterisk host using the SIP port (5060) and with a name and password combination of sip-phone and 5678. If successful, an entry similar to the following will appear in /var/log/asterisk/messages:

[Apr  6 00:53:59] NOTICE[2781] chan_sip.c: Peer 'sip-phone' is now Reachable. (16ms / 2000ms)

4. Dial plan

At the heart of every PBX is its dial plan: the logic that, based on the number and pattern of the digits dialled, determines which connections are made for any and all incoming and outgoing calls. The dial plan is saved in /etc/asterisk/extensions.conf. It contains many interesting things to begin with, but since these are not needed for this exercise, rename the file for now:

~# mv /etc/asterisk/extensions.conf /etc/asterisk/extensions.conf-org
~# _

After that, create a new, empty version fo this file and modify its ownership and permissions:

~# touch /etc/asterisk/extensions.conf
~# chown asterisk.asterisk /etc/asterisk/extensions.conf
~# chmod 640 /etc/asterisk/extensions.conf
~# _

Then edit the new and empty /etc/asterisk/extensions.conf and add the following contents:

[incoming]
exten => 0715551234,1,Dial(SIP/sip-phone,60)
exten => 0715551234,n,Hangup()

[outgoing]
exten => _X.,1,Dial(SIP/${EXTEN}@provider)
exten => _X.,n,Hangup()

Explanation:

[incoming]

Incoming calls from the SIP channel, provider, are inserted at this point, because the title of this section matches the context=incoming statement in the [provider] section of sip.conf. Otherwise, the name of this section is arbitrary.

exten => 0715551234,1,Dial(SIP/sip-phone,60)

When an incoming call reaches this point and matches extension number 0715551234, a sequence of two events is triggered, starting with the Dial() application, which connects together all of the various channel types in Asterisk. Here, it connects to a SIP channel, called sip-phone, which is represented by a section called [sip-phone] in sip.conf, with a ring-timeout of 60 seconds.

exten => 0715551234,n,Hangup()

After the incoming call has ended, or if the ring-timeout has been reached, the second event (n=n+1) that matches this extension will take place. This is the Hangup() application, which simply hangs up the current channel unconditionally.

[outgoing]

Outgoing calls from the SIP channel, sip-phone, are inserted at this point, because the title of this section matches the context=outgoing statement in the [sip-phone] section of sip.conf. Otherwise, the name of this section is arbitrary.

exten => _X.,1,Dial(SIP/${EXTEN}@provider)

This event will always be triggered by calls that reach this point, because "_X." is a catch-all that matches any number and combination of digits that can be dialled. The Dial() application will then connect to a SIP channel, called provider, with ${EXTEN} representing the dialled number.

exten => _X.,n,Hangup()

After the incoming call has ended, the second event (n=n+1) that matches this extension will take place and the Hangup() application will hang up the current channel.

Once the new dial plan has been saved, submit the changes to the already running Asterisk process with this command:

~# asterisk -rx "dialplan reload"
Dialplan reloaded.
~# _

5. Result

At this point it should be possible to make and receive calls via this new Asterisk system using the SIP test phone. With only one phone and a single PSTN channel, this is a very minimal configuration. It may not be capable of all that much yet, but it is a good foundation to start with and hopefully a reasonable demonstration of how incoming and outgoing calls are routed through the dial plan.


6. See also
7. Further reading
  • Degener J. 2009. GSM 06.10 lossy speech compression. HTML at the Questionable Utility Company.
  • Roach AB. 2002. RFC3265 − Session Initiation Protocol (SIP) − Specific Event Notification. The Internet Society. HTML at the Internet FAQ Archives.
  • Rosenberg J, Schulzrinne H, Camarillo G, Johnston A, Peterson J, Sparks R, Handley M, Schooler E. 2002. RFC3261 − SIP: Session Initiation Protocol. The Internet Society. HTML at the Internet FAQ Archives.
  • Schulzrinne H, Petrack S. 2000. RFC2833 − RTP Payload for DTMF Digits, Telephony Tones and Telephony Signals. The Internet Society. HTML at the Internet FAQ Archives.

8. Sources

Last modified: 2010-06-12, 14:01

©2003-2014 RJ Systems. Permission is granted to copy, distribute and/or modify the
content of this page under the terms of the OpenContent License, version 1.0.