| Linux System Administration |
| Home | Tech | Linux | Links | Consulting |
|
Asterisk: minimal SIP configuration
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:
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:
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:
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:
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
8. Sources
Last modified: 2017-08-02, 17:50
©2003-2020 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. |
