Asterisk The Definitive Guide Pdf
- Asterisk The Definitive Guide Pdf Download
- Asterisk The Definitive Guide Pdf Free
- Spark The Definitive Guide Pdf
Submit your own errata for this product.
The errata list is a list of errors and their corrections that were found after the product was released. If the error was corrected in a later version or reprint the date of the correction will be displayed in the column titled 'Date Corrected'.
Asterisk The Definitive Guide 5th Edition.pdf - Free download Ebook, Handbook, Textbook, User Guide PDF files on the internet quickly and easily. Download Asterisk: The Definitive Guide, 5th Edition or any other file from Books category. HTTP download also available at fast speeds. Asterisk: The Definitive Guide: The Future of Telephony Is Now 5th Edition by Jim Van Meggelen English 2019 ISBN: 181 Pages PDF (conv/HQ) 6.21 MB Learn how design a complete Voice over IP (VoIP) or traditional PBX system with Asterisk, even if you have only basic telecommunications knowledge.
The following errata were submitted by our customers and approved as valid errors by the author or editor.
Color Key:Serious Technical MistakeMinor Technical MistakeLanguage or formatting errorTypoQuestionNoteUpdate
| Version | Location | Description | Submitted By | Date Submitted | Date Corrected |
|---|---|---|---|---|---|
| Printed, PDF, Safari Books Online, Other Digital Version | In the AGI section, under the heading: 'Async AGI--AMI Controlled AGI', the syntax used to force Asterisk to execute AGI scripts asynchronously is written as: AGI(async:agi) When in reality, it is actually the other way around: AGI(agi:async) Thanks! -Randall Note from the Author or Editor: | Randall Degges | Sep 24, 2011 | ||
| Other Digital Version | The book contains 'sudo cat > snmpd.conf' and other 'sudo cat > somefile' examples. This cannot work, as the user running the shell will be opening the file for output, sudo won't help you there. One could fix it by doing this: sudo sh -c 'cat > snmpd.conf' Or one could tell the user to edit these config files as root (or the owner of the files). It makes it easier to stay consistent too, because you have a fully developed idea of the character’s personality right from the start. Some writers think this is cheating, but I do it all the time. When you first introduce them, you should include a few details, but the rest of their personalities, motivations, and back stories should be revealed gradually through their actions.Another tip is to base characters on real people. It’s a way to flesh out a character very quickly. Note from the Author or Editor: | Walter Doekes | Oct 04, 2011 | ||
| Other Digital Version | Kindle version. Ubuntu community recommend use of admin group - rather than wheel. sudo adduser asteriskpbx sudo adduser asteriskpbx admin Note from the Author or Editor: | Paul McGrath | Apr 10, 2012 | ||
| Other Digital Version | Kindle version. In section describing how to change the asteriskpbx environment to include specific paths - the file to be changed is NOT called .bash_profile. It is called '.bashrc' Note from the Author or Editor: | Paul McGrath | Apr 10, 2012 | ||
| Other Digital Version | XIIII Under sla.conf under Key system example with Analog trunk | Should the template for the 4 station read type=station instead of type=trunk? For the example box just above section extensions.conf Note from the Author or Editor: | Anonymous | Apr 26, 2012 | |
| Other Digital Version | Chapter 16 - 'Using Realtime' section In the section 'Using Realtime' of the Chapter 16. 'Relational Database Integration' | When the section talks how we can tell asterisk wich configuration files we want to load from the database (or wich dyinamic realtime objects we want to load from the database) it never says we have to write [settings] at the top of the /etc/asterisk/extconfig.conf file The section doesn't say Note from the Author or Editor: | Javier Zanon | Nov 22, 2012 | |
| Other Digital Version | Chapter 16 - 'Installing and configuring ODBC' section In the section 'Installing and configuring ODBC' from the chapter 16 'Relational Database Integration' | The section shows how to install the ODBC module and how to configure it. But it never says that you have to add to the file /etc/asterisk/modules.conf the following lines: preload => res_odbc.so preload => res_config_odbc.so under the lines: [modules] autoload=yes at the top of the file Note from the Author or Editor: | Javier Zanon | Nov 22, 2012 | |
| Other Digital Version | 1 Chapter 7. VoIP Connecting two Asterisk systems together with SIP | Examples show username=xxx but Asterisk 1.8 reports: The 'username' field for sip peers has been deprecated in favor of the term 'defaultuser' Examples just need updated. Thanks Note from the Author or Editor: | Anonymous | May 08, 2012 | |
| Other Digital Version | Table 2.5 (Channel Drives) row 2 - has a pipe character before chan_alsa in column 1. Note from the Author or Editor: | Anonymous | May 11, 2012 | ||
| Other Digital Version | 1 [2. Asterisk Architecture][File Structure][The Spool] | 'The spool is where Linux stores files..' - Linux (or any other kernel) does not store anything there, user-space programs are the ones that do so. From the FHS (Filesystem hierarchy Standard): /var/spool : Application spool data Note from the Author or Editor: | Fedja Beader | Aug 29, 2012 | |
| Safari Books Online | Public Switched Telephone Interface(PSTN) -> Public Switched Telephone Network(PSTN) Note from the Author or Editor: | Kunimitsu Arai | May 16, 2011 | Sep 23, 2011 | |
| Printed | When attempting to follow the instructions regarding menuselect. It appears that it was already setup for curses. Also, you specify (for CentOS) sudo yum install libnewt-devel. It's actually sudo yum install newt-devel. (http://www.hikaro.com/linux/newt-library-libnewt-not-found.html) And, once you have installed newt you have to go through the process to clear out menuselect and create it again. Note from the Author or Editor: | Anonymous | Apr 13, 2011 | Sep 23, 2011 | |
The text says to copy the indications.conf.sample from /usr/src/asterisk-complete/1.8/configs/. However, if you're following the setup til this page you would actually copy from ~/src/asterisk-complete/asterisk/1.8/configs. Also, you might want to add sudo cp for those of us who are still learning Linux. Note from the Author or Editor: | PhilMDev | Apr 13, 2011 | Sep 23, 2011 | ||
| Printed | The first exten => line under [general] has a minor error. It reads: exten => _NXXNXXXXXX,1,Dial({LOCAL}/$EXTEN}) and should of course read: exten => _NXXNXXXXXX,1,Dial({LOCAL}/${EXTEN}) (i.e. there is a missing { before EXTEN) Note from the Author or Editor: | Bob Eager | May 19, 2011 | Sep 23, 2011 | |
| PDF, Other Digital Version | All of the examples using Goto() are incorrect. They all omit the priority field, e.g.: exten => 911,Goto(dialsap,1) should be: exten => 911,1,Goto(dialpsap,1) This is a consistent error in this section. Note from the Author or Editor: | Bob Eager | May 16, 2011 | Sep 23, 2011 | |
| Printed, Other Digital Version | We're using the [internal] context, but it would make more sense to use [LocalSets]. | Leif Madsen | Nov 28, 2011 | ||
| Printed | There is an error in the description of the 'maxsilence' option. The relationship to the value of 'minsecs' is inverted; in other words, it should say that if 'maxsilence' is set greater than or equal to 'minsecs', a warning will be generated. Note from the Author or Editor: | Bob Eager | May 19, 2011 | Sep 23, 2011 | |
| Printed | The text says 'To allow users to dial 8500..'. But the following dialplan example says: exten => *98,.. which is not the same thing at all! Note from the Author or Editor: | Bob Eager | May 17, 2011 | Sep 23, 2011 | |
| Safari Books Online | when using example: exten => 123,1,Set(TEST=example) same => n,SayNumber(${LEN(${TEST})}) I hear no audio, but watching the console out I see the audio played, same with the example shortly following playing a count down from the number 10. http://forums.digium.com/viewtopic.php?f=1&t=80824 This forum posting points out to add same => n,answer() so correction would be exten => 123,1,Set(TEST=example) same => n,Answer() same => n,SayNumber(${LEN(${TEST})}) After doing this all works well, same goes with SayDigits() Note from the Author or Editor: | Bryan Anderson | Jan 30, 2013 | ||
| Printed | The syntax for the GotoIfTime() application is incomplete. It omits to show the 'false' path label, after a colon. This is inconsistent with what is show for GotoIf() on page 199. The syntax definition should read: GotoIfTime(times,days_of_week,days_of_month,months?destination1:destination2) and then the following explanation should be modified that destination1 is used if the date and time match the criteria, and destination2 is used otherwise. (what is actually described is, I believe, the Asterisk 1.6 behaviour). Note from the Author or Editor: | Bob Eager | Jul 03, 2011 | Sep 23, 2011 | |
| Printed, ePub | the line same => n,VoiceMail(${MACRO_EXTEN},${IF($[${DIALSTATUS} = BUSY]?b:u)}) is missing the voicemail context. Used with the examples shipped with the book it should read same => n,VoiceMail(${MACRO_EXTEN}@default,${IF($[${DIALSTATUS} = BUSY]?b:u)}) Note from the Author or Editor: | Marco Meklenburg | Mar 11, 2013 | ||
| Printed | Figure 10-1 shows a slight different time delay for channel 3 as e.g. Table 10-1 does. Table 10-1 -as well as the text itself - states, that channel 3 shall ring from timecode '15' till '30'. But Figure 10-1 states Channel 3 to ring from timecode 15 till something at 38 seconds. Nothing serious, not more than a typo. Note from the Author or Editor: | Marco Meklenburg | Mar 11, 2013 | ||
| Printed | the example shows how to use the AstDB for counting. The SayNumber function included in this example should read the current count value to the caller - but it cannot without Answering the call in the first place. In short: The first lines of the full example should look like this: exten => 678,1,Answer() same => n,Set(COUNT=${DB(test/count)}) same => n,GotoIf($[${ISNULL(${COUNT})}]?:continue) Note from the Author or Editor: | Marco Meklenburg | Mar 11, 2013 | ||
| Printed, PDF, Safari Books Online, Other Digital Version | There is a broken cross reference in the findslot row of the table on page 223. It says: 'Configures the parking slot selection behavior. See ??? for more details.' '???' should be replaced with some text Note from the Author or Editor: | Anonymous | Apr 11, 2011 | ||
| Safari Books Online | 'So far as we can tell, Polycom sets do not support multicast. We certainly were not able to find a way to use it.' The Polycom's implement a multicast paging system in firmware version 4.0.0 and above. Works quite well. I implemented an install of ~80 phones using. Not sure if that is already in edition 4 or not but thought I would throw it out there. Note from the Author or Editor: | Bryan Anderson | Jan 31, 2013 | ||
| Printed, PDF | Page 249 2nd sentence of 2nd paragraph in box at bottom of page | Redundant phrase at beginning and end of sentence: For those countries fortunate enough to have ENUM in produc- tion, you can perform ENUM lookups directly to their e164.arpa zones of those coun- tries fortunate enough to have ENUM in production. Note from the Author or Editor: | C.J. Adams-Collier | Nov 17, 2011 | |
| Printed | The [subFreenum] context at the top of the page starts with a call to Verbose(). However, the paragraph commencing 'The magic..' (about two thirds of the page down) says, in the second sentence: 'After the NoOp() on the first line..'. Clearly this should say something like 'After the initial call to Verbose()..'. Note from the Author or Editor: | Bob Eager | Jun 12, 2011 | Sep 23, 2011 | |
The paragraph: 'We’ve included the Queues context in the LocalSets context so that our telephones can call the queues we’ve set up. In Chapter 15, we’ll define menu items that go to these queues. Save the changes to your extensidons.conf file, and reload the dialplan with the dialplan reload CLI command.' Said 'extensidons.conf' and should be: extensions.conf: 'We’ve included the Queues context in the LocalSets context so that our telephones can call the queues we’ve set up. In Chapter 15, we’ll define menu items that go to these queues. Save the changes to your extensions.conf file, and reload the dialplan with the dialplan reload CLI command.' Note from the Author or Editor: | Juan Muriel | Jul 07, 2011 | Sep 23, 2011 | ||
| Printed, PDF, Safari Books Online, Other Digital Version | ; Used for unpausing agents in all available queues exten => *87,1,Verbose(2,UnPausing member in all queues) same => n,GoSub(subSetupAvailableQueues,start,1()) ; if we don't define a queue, then the member is unpaused from all queues same => n,UnPauseQueueMember(,${MemberChanType}/${MemberChannel}) same => n,GotoIf($[${PQMSTATUS} = PAUSED]?agent_unpaused,1:agent_not_found,1) In Unpause section of dialplan there is a variable error it should be like following same => n,GotoIf($[${UPQMSTATUS} = UNPAUSED]?agent_unpaused,1:agent_not_found,1) Note from the Author or Editor: | Satish Patel | May 27, 2011 | Sep 23, 2011 | |
| Printed | Page 311 Halfway down -- could please as a note or new paragraph | Since we are running Asterisk as the 'asterisk' user in this book, the instructions as described here for the OpenAIS stuff won't quite work. You'll run into the following error on the Asterisk console when loading res_ais.so: *CLI> module load res_ais.so ERROR[19593]: ais/clm.c:140 ast_ais_clm_load_module: Could not initialize cluster membership service: Unknown To fix this, you need to add some permissions stuff to corosync. I ran into the same issue when trying to load res_ais stuff, and found the solution on this page (we should attribute him): http://felimwhiteley.wordpress.com/2011/07/11/asterisk-invalid-ipc-credentials-or-how-no-interwebs-saved-the-day/#wpl-likebox Solution: cat > /etc/corosync/uidgid.d/asterisk uidgid { uid: asterisk gid: asterisk } CTRL+D | Leif Madsen | Oct 22, 2011 | |
| Printed | I believe that 'jabber show connected' should read as 'jabber show connections' in (2) places on this page. I tested using Asterisk 1.8 and the command as documented in the book produces the error: No such command 'jabber show connected' Note from the Author or Editor: | Tom Mazzotta | Sep 03, 2012 | ||
| Other Digital Version | SOURCE: http://www.asteriskdocs.org/en/3rd_Edition/asterisk-book-html/asterisk-book.html#DeviceStates_id36061103 - Chapter 14. Device States -- Shared Line Appearances --- sla.conf [station](!) type = trunk trunk = line1 trunk = line2 -------------------------- the line 'type = trunk' should read 'type = station' - Mark Norman Note from the Author or Editor: | Anonymous | Jan 30, 2012 | ||
Page 338,339 Subtitle 'The Dialplan' - Example code | In the code for the department's extensions, fax extension, directory extension, operator extension and, invalid and timeout extension (1, 2, 3, #, 0, i, t), the line with the Verbose() application is incomplete: exten => 1,1,Verbose(1, ; Sales Queue - see Chapter 13 for details same => n,Goto(Queues,7002,1) exten => 2,1,Verbose(1, ; Service Queue - see Chapter 13 for details same => n,Goto(Queues,7001,1) exten => 3,1,Verbose(1, same => n,Background() ; Address and fax info same => n,Goto(s,menuprompt) ; Take caller back to main menu prompt exten => #,1,Verbose(1, same => n,Directory() ; exten => 0,1,Verbose(1, ; Operator extension/queue same => n,Dial(SIP/operator) exten => i,1,Verbose(1, same => n,Playback(invalid) same => n,Goto(s,menuprompt) exten => t,1,Verbose(1, same => n,Goto(0,1) Could be something like: exten => 1,1,Verbose(1,Call to the Sales Extension) ; Sales Queue same => n,Goto(Queues,7002,1) exten => 2,1,Verbose(1,Call to the Sales Service) ; Service Queue same => n,Goto(Queues,7001,1) exten => 3,1,Verbose(1,Call to the address and fax info Extension) same => n,Background() ; Address and fax info same => n,Goto(s,menuprompt) ; Take caller back to main menu prompt exten => #,1,Verbose(1,Call to the Directory Service Extension) same => n,Directory() ; exten => 0,1,Verbose(1, Call to the Operator Extension) ; Operator extension/queue same => n,Dial(SIP/operator) exten => i,1,Verbose(1,Incoming call to invalid number) same => n,Playback(invalid) same => n,Goto(s,menuprompt) exten => t,1,Verbose(1,the caller doesn’t give input in time) same => n,Goto(0,1) Note from the Author or Editor: | Juan Muriel | Jul 06, 2011 | Sep 23, 2011 | |
| Safari Books Online | In chapter 16 on Relational Database Integration many of the readsql variables shown are vulnerable to sql injection. To avoid SQLi an attempt to sanitize user inputs should be made. In this case we are expecting numeric input so that is the only input we should accept. I've listed this as serious technical mistake because depending on implementation it could lead to a loss of confidentiality, integrity, and availability. Please re-classify as you see fit. | Paul Scott | Dec 20, 2011 | ||
| PDF, Safari Books Online | On ubuntu 10.04, the line UserName = asterisk must be changed to User = asterisk otherwise the connectivity test $ echo 'select 1' isql asterisk-connector -v gives back: [MYODBCUtilReadDataSource.c][243][ERROR] Unknown attribute (UserName). [08S01][unixODBC][MySQL][ODBC 3.51 Driver]Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (2) [ISQL]ERROR: Could not SQLConnect Hope this will be useful for improving the experience of future readers. (What I am looking at is the latest HTML/online content; it has been also confirmed to be the same in the PDF, 3rd edition.) Note from the Author or Editor: | Yassen Damyanov | Nov 05, 2011 | ||
If you enable the option 'limit =>0' using the PostgreSQL database, Asterisk will can not connect to the database: [asterisk] enabled => yes dsn => asterisk-connector username => asterisk password => welcome pooling => no limit => 0 pre-connect => yes When you execute 'odbc show' into the Asterisk CLI the output will look like: ODBC DSN Settings ----------------- You need to disable this option: [asterisk] enabled => yes dsn => asterisk-connector username => asterisk password => welcome pooling => no ; limit => 0 ---Disable this option using PostgreSQL database--- pre-connect => yes After you disabled this option the output of the Asterisk CLI will look like: ODBC DSN Settings ----------------- Name: asterisk DSN: asterisk-connector Last connection attempt: 1969-12-31 19:00:00 Pooled: No Connected: Yes Note from the Author or Editor: | Juan Muriel | Aug 03, 2011 | |||
| Printed | In the res_odbc.conf file the following line limit => 0 stops asterisk connecting to the MySQL database. When using CLI the command 'odbc show' does not show the DSN asterisk-connector. The solution was to remove the line. Note from the Author or Editor: | David Hanna | Aug 09, 2011 | Sep 23, 2011 | |
| Printed, Safari Books Online | Page 361 'start' extension of 'multirow_example_2' context in sample code. | The line: same => n,GotoIf($['${ODBC_FETCH_RESULT}' = 'FAILURE']?cleanup,1) Should read: same => n,GotoIf($['${ODBC_FETCH_STATUS}' = 'FAILURE']?cleanup,1) In the example given, if '1104' didn't exist in the database, the dialplan would go into an infinite loop. I believe that it would be better to check for the absence of a success rather than the presence of a failure - that way even with the broken example given, an infinite loop could not happen. I propose that the line should therefore be: same => n,GotoIf($['${ODBC_FETCH_STATUS}' != 'SUCCESS']?cleanup,1) It may be worth while pointing out that infinite loops could occur without sufficient error checking and that it is never a good idea to run Asterisk in realtime mode when testing things like this!! Note from the Author or Editor: | Nicholas Barnes | Feb 11, 2012 | |
| Printed | Page 440 First line under 'Using Festival with Asterisk' | 'we need to module' should read 'we need to modify'. Note from the Author or Editor: | Bob Eager | May 22, 2011 | Sep 23, 2011 |
| Printed | Page 569-570 Configuration section - under [Definitions] | Four of the lines for 'failregex =' are in error. They are functionally all the same in the example - the text after '<HOST>' in each case has been wrapped (no problem there) but has acquired a '#' symbol at the start of the continued line, thus making it into a comment. There are four occurrences of this - one at the bottom of page 569, and three more at the top of page 570. Note from the Author or Editor: | Bob Eager | May 23, 2011 | Sep 23, 2011 |
THIRD EDITION
Asterisk™: The Definitive Guide
Leif Madsen, Jim Van Meggelen, and Russell Bryant
Beijing • Cambridge • Farnham • Köln • Sebastopol • Tokyo
Asterisk™: The Definitive Guide, Third Edition by Leif Madsen, Jim Van Meggelen, and Russell Bryant Copyright © 2011 Leif Madsen, Jim Van Meggelen, and Russell Bryant. All rights reserved. Printed in the United States of America. Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or [email protected]
Editor: Mike Loukides Production Editor: Teresa Elsey Copyeditor: Rachel Head Proofreader: Andrea Fox Production Services: Molly Sharp
Indexer: Fred Brown Cover Designer: Karen Montgomery Interior Designer: David Futato Illustrator: Robert Romano
Printing History: June 2005: August 2007: April 2011:
First Edition. Second Edition. Third Edition.
Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. Asterisk: The Definitive Guide, the images of starfish, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.
ISBN: 978-0-596-51734-2 [LSI] 1302181785
Table of Contents
Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii 1. A Telephony Revolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Asterisk and VoIP: Bridging the Gap Between Traditional and Network Telephony The Zapata Telephony Project Massive Change Requires Flexible Technology Asterisk: The Hacker’s PBX Asterisk: The Professional’s PBX The Asterisk Community The Asterisk Mailing Lists Asterisk Wiki Sites The IRC Channels Asterisk User Groups The Asterisk Documentation Project The Business Case Conclusion
2 2 3 4 5 5 6 7 7 7 8 8 8
2. Asterisk Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Modules Applications Bridging Modules Call Detail Recording Modules Channel Event Logging Modules Channel Drivers Codec Translators Format Interpreters Dialplan Functions PBX Modules
10 12 15 15 16 17 18 18 19 21
v
Resource Modules Addon Modules Test Modules File Structure Configuration Files Modules The Resource Library The Spool Logging The Dialplan Hardware Asterisk Versioning Previous Release Methodologies The New Release Methodology Conclusion
21 23 24 24 24 24 25 25 25 25 26 26 26 27 28
3. Installing Asterisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Installation Cheat Sheet Distribution Installation CentOS Server Ubuntu Server Software Dependencies Downloading What You Need Getting the Source via Subversion Getting the Source via wget How to Install It LibPRI DAHDI Asterisk Setting File Permissions Base Configuration Disable SELinux Initial Configuration make menuselect Updating Asterisk Common Issues Upgrading Asterisk Conclusion
31 35 35 40 44 46 47 47 48 48 49 50 50 51 51 52 59 64 66 68 69
4. Initial Configuration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 asterisk.conf The [directories] Section The [options] Section vi Table of Contents
71 71 72
The [files] Section The [compat] Section modules.conf The [modules] Section indications.conf musiconhold.conf Converting Music to a Format That Works Best with Asterisk Conclusion
75 75 75 76 77 79 79 81
5. User Device Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Telephone Naming Concepts Hardphones, Softphones, and ATAs Configuring Asterisk How Channel Configuration Files Work with the Dialplan sip.conf iax.conf Modifying Your Channel Configuration Files for Your Environment Loading Your New Channel Configurations The Asterisk CLI Testing to Ensure Your Devices Have Registered Analog Phones A Basic Dialplan to Test Your Devices Under the Hood: Your First Call Conclusion
84 86 87 88 89 95 98 98 99 99 100 103 104 105
6. Dialplan Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Dialplan Syntax Contexts Extensions Priorities Applications The Answer(), Playback(), and Hangup() Applications A Simple Dialplan Hello World Building an Interactive Dialplan The Goto(), Background(), and WaitExten() Applications Handling Invalid Entries and Timeouts Using the Dial() Application Using Variables Pattern Matching Includes Conclusion
107 108 110 111 113 113 115 115 116 116 119 119 122 125 129 130
Table of Contents vii
7. Outside Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 The Basics of Trunking Fundamental Dialplan for Outside Connectivity PSTN Circuits Traditional PSTN Trunks Installing PSTN Trunks VoIP PSTN Termination PSTN Origination VoIP to VoIP Configuring VoIP Trunks Emergency Dialing Conclusion
131 132 133 134 136 144 144 145 147 147 154 156
8. Voicemail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Comedian Mail The [general] Section The [zonemessages] Section The Contexts Section An Initial voicemail.conf File Dialplan Integration The VoiceMail() Dialplan Application The VoiceMailMain() Dialplan Application Creating a Dial-by-Name Directory Using a Jitterbuffer Storage Backends Linux Filesystem ODBC IMAP Using Asterisk As a Standalone Voicemail Server Integrating Asterisk into a SIP Environment As a Standalone Voicemail Server SMDI (Simplified Message Desk Interface) Conclusion
157 158 166 167 168 169 169 171 171 172 172 172 173 173 174 174 177 179
9. Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Devices External to the Asterisk Server PSTN Connectivity, DAHDI, Digium Cards, and Analog Phones DAHDI Drivers Asterisk Caller ID Language and/or Accent of Prompts Time/Date Stamps and Pronunciation viii Table of Contents
182 185 187 189 189 190 191
Conclusion—Easy Reference Cheat Sheet
194
10. Deeper into the Dialplan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Expressions and Variable Manipulation Basic Expressions Operators Dialplan Functions Syntax Examples of Dialplan Functions Conditional Branching The GotoIf() Application Time-Based Conditional Branching with GotoIfTime() Macros Defining Macros Calling Macros from the Dialplan Using Arguments in Macros GoSub() Defining Subroutines Calling Subroutines from the Dialplan Using Arguments in Subroutines Returning from a Subroutine Local Channels Using the Asterisk Database (AstDB) Storing Data in the AstDB Retrieving Data from the AstDB Deleting Data from the AstDB Using the AstDB in the Dialplan Handy Asterisk Features Zapateller() Call Parking Conferencing with MeetMe() Conclusion
195 195 196 198 198 198 199 199 202 204 204 205 206 207 207 208 209 210 211 214 214 214 215 215 217 217 217 218 219
11. Parking and Paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 features.conf The [general] section The [featuremap] Section The [applicationmap] Section Application Map Grouping Parking Lots Overhead and “Underchin” Paging (a.k.a. Public Address) Places to Send Your Pages Zone Paging
221 222 225 225 227 228 229 230 235 Table of Contents ix
Conclusion
236
12. Internet Call Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 DNS and SIP URIs The SIP URI SRV Records Accepting Calls to Your System Dialing SIP URIs from Asterisk ENUM and E.164 E.164 and the ITU ENUM Asterisk and ENUM ISN, ITAD, and freenum.org Got ISN? ITAD Subscriber Numbers (ISNs) Management of Internet Numbering IP Telephony Administrative Domains (ITADs) Create a DNS Entry for Your ITAD Testing Your ITAD Using ISNs in Your Asterisk System Security and Identity Toll Fraud Spam over Internet Telephony (SPIT) Distributed Denial of Service Attacks Phishing Security Is an Ongoing Process Conclusion
237 238 238 240 246 247 247 248 249 250 251 251 251 252 253 254 254 256 257 258 258 258 259 259
13. Automatic Call Distribution (ACD) Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Creating a Simple ACD Queue Queue Members Controlling Queue Members via the CLI Controlling Queue Members with Dialplan Logic Automatically Logging Into and Out of Multiple Queues An Introduction to Device State The queues.conf File The agents.conf File Advanced Queues Priority Queue (Queue Weighting) Queue Member Priority Changing Penalties Dynamically (queuerules.conf) Announcement Control Overflow x Table of Contents
262 266 266 268 270 273 275 281 283 283 284 285 287 291
Using Local Channels Queue Statistics: The queue_log File Conclusion
293 296 299
14. Device States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 Device States Checking Device States Extension States Hints Checking Extension States SIP Presence Asterisk Configuration Using Custom Device States An Example Distributed Device States Using OpenAIS Using XMPP Shared Line Appearances Installing the SLA Applications Configuration Overview Key System Example with Analog Trunks Key System Example with SIP Trunks Shared Extension Example Additional Configuration Limitations Conclusion
301 302 303 303 304 306 306 307 308 309 310 314 318 318 319 319 323 325 327 328 329
15. The Automated Attendant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 An Auto Attendant Is Not an IVR Designing Your Auto Attendant The Greeting The Main Menu Timeout Invalid Dial by Extension Building Your Auto Attendant Recording Prompts The Dialplan Delivering Incoming Calls to the Auto Attendant IVR Conclusion
331 332 333 334 335 335 336 336 336 338 339 340 340
Table of Contents xi
16. Relational Database Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Installing and Configuring PostgreSQL and MySQL Installing PostgreSQL for CentOS Installing PostgreSQL for Ubuntu Installing MySQL for CentOS Installing MySQL for Ubuntu Configuring PostgreSQL Configuring MySQL Installing and Configuring ODBC Configuring ODBC for PostgreSQL Configuring ODBC for MySQL Configuring ODBC for Microsoft SQL Validating the ODBC Connector Configuring res_odbc to Allow Asterisk to Connect Through ODBC Managing Databases Troubleshooting Database Issues A Gentle Introduction to func_odbc Getting Funky with func_odbc: Hot-Desking Using Realtime Static Realtime Dynamic Realtime Storing Call Detail Records (CDRs) ODBC Voicemail Creating the Large Object Type for PostgreSQL ODBC Voicemail Storage Table Layout Configuring voicemail.conf for ODBC Storage Testing ODBC Voicemail Conclusion
342 342 342 343 343 343 345 346 347 349 350 351 352 353 353 354 354 368 368 371 375 378 379 381 382 383 387
17. Interactive Voice Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 What Is IVR? Components of an IVR IVR Design Considerations Do Don’t Asterisk Modules for Building IVRs CURL func_odbc AGI AMI A Simple IVR Using CURL Installing the cURL Module The Dialplan xii Table of Contents
389 390 392 392 392 392 392 392 393 393 393 393 394
A Prompt-Recording Application Speech Recognition and Text-to-Speech Text-to-Speech Speech Recognition Conclusion
394 395 395 396 396
18. External Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Calendar Integration Compiling Calendaring Support into Asterisk Configuring Calendar Support for Asterisk Triggering Calendar Reminders to Your Phone Controlling Calls Based on Calendar Information Writing Call Information to a Calendar Conclusion VoiceMail IMAP Integration Compiling IMAP VoiceMail Support into Asterisk Using XMPP (Jabber) with Asterisk Compiling Jabber Support into Asterisk Jabber Dialplan Commands chan_gtalk Skype Integration Installation of Skype for Asterisk Using Skype for Asterisk LDAP Integration Configuring OpenLDAP Compiling LDAP Support into Asterisk Configuring Asterisk for LDAP Support Text-to-Speech Utilities Festival Cepstral Conclusion
398 398 399 402 407 408 411 411 412 418 419 419 425 429 429 429 434 435 437 437 440 440 442 442
19. Fax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 What Is a Fax? Ways to Handle Faxes in Asterisk spandsp Obtaining spandsp Compiling and Installing spandsp Adding the spandsp Library to Your libpath Recompiling Asterisk with spandsp Support Disabling spandsp (Should You Want to Test Digium Fax) Digium Fax For Asterisk Obtaining Digium FFA
443 443 444 444 444 445 445 446 446 446
Table of Contents xiii
Disabling Digium FFA (Should You Want to Test spandsp) Incoming Fax Handling Fax to TIFF Fax to Email Fax Detection Outgoing Fax Handling Transmitting a Fax from Asterisk File Format for Faxing An Experiment in Email to Fax Fax Pass-Through Using Fax Buffers in chan_dahdi.conf Conclusion
446 447 447 447 448 449 450 450 451 454 454 455
20. Asterisk Manager Interface (AMI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 Quick Start AMI over TCP AMI over HTTP Configuration manager.conf http.conf Protocol Overview Message Encoding AMI over HTTP Development Frameworks CSTA Interesting Applications AsteriskGUI Flash Operator Panel Conclusion
457 458 459 460 460 464 465 466 467 471 471 472 472 473 473
21. Asterisk Gateway Interface (AGI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 Quick Start AGI Variants Process-Based AGI DeadAGI Is Dead FastAGI—AGI over TCP Async AGI—AMI-Controlled AGI AGI Communication Overview Setting Up an AGI Session Commands and Responses Ending an AGI Session Development Frameworks Conclusion xiv Table of Contents
475 477 477 478 478 479 480 480 482 486 487 488
22. Clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 Traditional Call Centers Hybrid Systems Pure Asterisk, Nondistributed Asterisk and Database Integration Single Database Replicated Databases Asterisk and Distributed Device States Distributing Device States over a LAN Distributing Device States over a WAN Multiple Queues, Multiple Sites Conclusion
489 490 492 493 493 495 496 496 497 499 501
23. Distributed Universal Number Discovery (DUNDi) . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 How Does DUNDi Work? The dundi.conf File Configuring Asterisk for Use with DUNDi General Configuration Initial DUNDi Peer Definition Creating Mapping Contexts Using Mapping Contexts with Peers Allowing Remote Connections Controlling Responses Performing Lookups from the Dialplan Conclusion
503 505 507 507 509 510 512 514 516 519 522
24. System Monitoring and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523 logger.conf Reviewing Asterisk Logs Logging to the Linux syslog Daemon Verifying Logging Call Detail Records CDR Contents Dialplan Applications cdr.conf Backends Example Call Detail Records Caveats CEL (Channel Event Logging) Channel Event Types Channel Event Contents Dialplan Applications cel.conf
523 525 526 527 527 527 529 529 530 536 537 537 537 539 540 540 Table of Contents xv
Backends Example Channel Events SNMP Installing the SNMP Module for Asterisk Configuring SNMP for Asterisk Using OpenNMS Monitoring Asterisk with OpenNMS Conclusion
540 546 551 551 552 558 559
25. Web Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 Flash Operator Panel Queue Status and Reporting Queue Status Display Queue Reporting Call Detail Records A2Billing Conclusion
562 562 563 563 563 564 564
26. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 Scanning for Valid Accounts Authentication Weaknesses Fail2ban Installation Configuration Encrypted Media Dialplan Vulnerabilities Securing Asterisk Network APIs IAX2 Denial of Service Other Risk Mitigation Resources Conclusion—A Better Idiot
565 567 567 568 569 571 571 572 573 574 575 576
27. Asterisk: A Future for Telephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 The Problems with Traditional Telephony Closed Thinking Limited Standards Compliancy Slow Release Cycles Refusing to Let Go of the Past and Embrace the Future Paradigm Shift The Promise of Open Source Telephony The Itch That Asterisk Scratches Open Architecture Standards Compliance Lightning-Fast Response to New Technologies xvi Table of Contents
577 578 578 579 579 580 580 580 581 582 582
Passionate Community Some Things That Are Now Possible The Future of Asterisk Speech Processing High-Fidelity Voice Video Wireless Unified Messaging Peering Challenges Opportunities
582 582 586 587 588 588 589 590 590 591 594
A. Understanding Telephony . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 B. Protocols for VoIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 C. Preparing a System for Asterisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
Table of Contents xvii
Foreword
“There’s more than one way to do it.” I’ve been working with Asterisk for nine years, and this motto becomes more true with each release, each added feature, and each clever person who attacks a telecommunications problem with this incredibly flexible toolkit. I had the fantastic opportunity to work as the community manager for the Asterisk project at Digium for two years, which gave me one of the best vantage points for seeing the scope and imagination of the worldwide development effort pushing Asterisk forward. The depth and breadth of Asterisk is staggering—installations with hundreds of thousands of users are now commonplace. I see Asterisk making deep inroads into the financial, military, hospital, Fortune 100 enterprise, service provider, calling card, and mobile environments. In fact, there really aren’t any areas that I can think of where Asterisk isn’t now entrenched as the default choice when there is a need for a generalized voice tool to do “stuff.” Asterisk has been emblematic of the way that open source software has changed business—and changed the world. My favorite part of any Asterisk project overview or conference talk is answering questions from someone new to Asterisk. As I continue to answer “Yes, it can do that,” I watch as the person’s eyes grow wide. The person starts to smile when he really starts to think about new things to do that his old phone or communication system couldn’t possibly have done. Radio integration? Sure. Streaming MP3s into or out of phone calls? OK. Emailing recorded conference calls to the participants? No problem. Integration of voice services into existing Java apps? Easy. Fax? Instant messages? IVRs? Video? Yes, yes, yes, yes. The affirmative answers just keep flowing, and at that point, the best thing to do is to sit the person down and start showing him quick demonstrations of how Asterisk can be quickly deployed and developed. Then, I typically point the person toward the first edition of this book, Asterisk: The Future of Telephony, and set him loose. In just a few hours of development (or longer, of course), companies can change the way they deliver products to customers, nonprofits can overhaul how their users interact with the services they offer, and individuals can learn to build a perfectly customized call-handling system for their mobile and home phones. Asterisk scales up and down from individual lines to vast multiserver installations across multiple continents, but the way to start is
xix
to install the package, open up some of the configuration files, and start looking at examples. From the basic beginnings of a PBX that Mark Spencer coded in 1999, the Asterisk project, with the help of thousands of developers, has moved from simply connecting phone calls and has matured into a platform that can handle voice, video, and text across dozens of virtual and physical interface types. The creation and growth of Asterisk were the inescapable results of the convergence of the four horsemen of the proprietary hardware apocalypse: open source development ideas, the Internet, Moore’s Law, and the plummeting costs of telecommunications. Even hardware vendors who may be frightened of Asterisk from a competitive standpoint are using it in their labs and core networks: almost all devices in the Voice-over-IP world are tested with Asterisk, making it the most compatible system across vendors. At a recent communications conference I attended, the question “Who uses Asterisk?” was posed to the 1000-plus crowd. Nearly 75 percent raised their hands. Asterisk is a mature, robust software platform that permeates nearly every area of the telecommunications industry and has firmly cemented itself as one of the basic elements in any open source service delivery system. I tell people that it’s reasonable for anyone delivering services both via phone and web to want to add an “A” for Asterisk to the LAMP (Linux, Apache, MySQL, [Perl/Python/PHP]) acronym, making it LAAMP. (LAMA-P was another option, but for some reason nobody seems to like that version…I don’t know why.) The expansion of this book to include more examples is something I’ve been looking forward to for some time. Asterisk is accessible because of the ease with which a novice can understand basic concepts. Then it continues to succeed as the novice becomes a pro and starts tapping the “other ways to do it” with more sophisticated implementations, using AGI with Java, Perl, or Python (or one of the other dozen or so supported languages), or even writing her own custom apps that work as compile-time options in Asterisk. But the first step for anyone, no matter what his or her skill level, is to look at examples of basic apps others have written. Leif, Jim, and Russell have not only put together a fantastic compendium of Asterisk methods, but they have also provided an excellent list of examples that will let the novice or expert quickly learn new techniques and “more than one way to do it.” Asterisk 1.x is fantastically powerful and can solve nearly any voice problem you might have. For those of you building the most complex installations, there is even more interesting work—which will be realized quite soon—in development. The currentlyin-development Asterisk SCF (Scalable Communications Framework) is being built as an adjunct open source project to allow Asterisk 1.x systems to scale in even more powerful ways—stay tuned, or better yet, get involved with the project as a developer.
xx Foreword
If you’re an experienced Asterisk developer or integrator, I’m sure this book will have a few “Hey, that’s a neat way to do it!” moments for you, which is one of the joys of Asterisk. If this is your first project with Asterisk, I’d like to welcome you to the huge community of users and developers dedicated to making Asterisk better. This book will take you from a vague idea of doing something with computers and voice communication to the point where you’re able to stun everyone you know with your phone system’s sophisticated tricks. You’re encouraged to participate in the online mailing lists, IRC chatrooms, and yearly AstriCon conference that provide up-to-the-second news and discussion surrounding the project. Without your interest, input, and code, Asterisk wouldn’t exist. Open source projects are hungry for new ideas and excellent contributions: I encourage you to be a participant in the Asterisk community, and I look forward to seeing your questions and examples in the next edition of this book. —John Todd
Foreword xxi
Preface
This is a book for anyone who uses Asterisk. Asterisk is an open source, converged telephony platform, which is designed primarily to run on Linux. Asterisk combines more than 100 years of telephony knowledge into a robust suite of tightly integrated telecommunications applications. The power of Asterisk lies in its customizable nature, complemented by unmatched standards compliance. No other PBX can be deployed in so many creative ways. Applications such as voicemail, hosted conferencing, call queuing and agents, music on hold, and call parking are all standard features built right into the software. Moreover, Asterisk can integrate with other business technologies in ways that closed, proprietary PBXs can scarcely dream of. Asterisk can appear quite daunting and complex to a new user, which is why documentation is so important to its growth. Documentation lowers the barrier to entry and helps people contemplate the possibilities. Produced with the generous support of O’Reilly Media, Asterisk: The Definitive Guide is the third edition of what was formerly called Asterisk: The Future of Telephony. We decided to change the name because Asterisk has been so wildly successful that it is no longer an up-and-coming technology. Asterisk has arrived. This book was written for, and by, members of the Asterisk community.
Audience This book is intended to be gentle toward those new to Asterisk, but we assume that you’re familiar with basic Linux administration, networking, and other IT disciplines. If not, we encourage you to explore the vast and wonderful library of books that O’Reilly publishes on these subjects. We also assume you’re fairly new to telecommunications (both traditional switched telephony and the new world of Voice over IP). However, this book will also be useful for the more experienced Asterisk administrator. We ourselves use the book as a reference for features that we haven’t used for a while.
xxiii
Organization The book is organized into these chapters: Chapter 1, A Telephony Revolution This is where we chop up the kindling and light the fire. Welcome to Asterisk! Chapter 2, Asterisk Architecture Discusses the file structure of an Asterisk system. Chapter 3, Installing Asterisk Covers obtaining, compiling, and installing Asterisk. Chapter 4, Initial Configuration Tasks Describes some initial configuration tasks for your new Asterisk system. This chapter goes over some of the configuration files required for all Asterisk installations. Chapter 5, User Device Configuration Provides guidance on configuring Asterisk to allow devices such as telephones to connect and make calls. Chapter 6, Dialplan Basics Introduces the heart of Asterisk, the dialplan. Chapter 7, Outside Connectivity Discusses how to configure Asterisk to connect to other systems, such as other Asterisk servers, Internet telephony service providers, or the plain old telephone network. Chapter 8, Voicemail Covers the usage of one of the most popular applications included with Asterisk, the voicemail system. Chapter 9, Internationalization Focuses on issues that an Asterisk administrator should be aware of when deploying a system outside of North America. Chapter 10, Deeper into the Dialplan Goes over some more advanced dialplan concepts. Chapter 11, Parking and Paging Describes the usage of two popular telephony features included with Asterisk, call parking and paging. Chapter 12, Internet Call Routing Covers techniques for routing calls between different administrative domains on the Internet. Chapter 13, Automatic Call Distribution (ACD) Queues Discusses how to build call queues in Asterisk.
xxiv Preface
Chapter 14, Device States Introduces the concept of device states and how they can be used as presence indicators. Chapter 15, The Automated Attendant Covers how to build a menuing system using the Asterisk dialplan. Chapter 16, Relational Database Integration Discusses various ways that Asterisk can be integrated with a database. Chapter 17, Interactive Voice Response Goes over how Asterisk can be used to build applications that act on input provided by a caller. Chapter 18, External Services Provides instructions on how to connect to external services including LDAP, calendars, IMAP for voicemail, XMPP, Skype, and text-to-speech. Chapter 19, Fax Discusses the various options for integrating sending and receiving faxes with an Asterisk system. Chapter 20, Asterisk Manager Interface (AMI) Introduces a network API for monitoring and controlling an Asterisk system. Chapter 21, Asterisk Gateway Interface (AGI) Introduces the Asterisk API that allows call control to be implemented in any programming language. Chapter 22, Clustering Discusses a number of approaches for clustering multiple Asterisk servers together once the demands of a deployment exceed the capabilities of a single server. Chapter 23, Distributed Universal Number Discovery (DUNDi) Covers a peer-to-peer protocol native to Asterisk that can be used for call routing. Chapter 24, System Monitoring and Logging Introduces some of the interfaces available for logging and monitoring an Asterisk system. Chapter 25, Web Interfaces A survey of some of the web interfaces that complement an Asterisk installation. Chapter 26, Security Discusses some common security issues that Asterisk administrators should be aware of. Chapter 27, Asterisk: A Future for Telephony In conclusion, we discuss some of the things we expect to see from open source telephony in the near future. Appendix A, Understanding Telephony Explores the technologies in use in traditional telecom networks. This used to be a chapter in old versions of this book. Although not directly relevant to Asterisk Preface xxv
we felt that it might still be useful to some readers, so we’ve left it in the book as an appendix. Appendix B, Protocols for VoIP Delves into all the particularities of Voice over IP. This was also a chapter in old versions of this book. Appendix C, Preparing a System for Asterisk Contains information you should be aware of and take into consideration when planning an Asterisk deployment.
Software This book is focused on documenting Asterisk version 1.8; however, many of the conventions and much of the information in this book is version-agnostic. Linux is the operating system we have run and tested Asterisk on, and we have documented installation instructions for both CentOS (Red Hat Enterprise Linux–based) and Ubuntu (Debian-based) where they differ from each other.
Conventions Used in This Book The following typographical conventions are used in this book: Italic Indicates new terms, URLs, email addresses, filenames, file extensions, pathnames, directories, and package names, as well as Unix utilities, commands, options, parameters, and arguments. Constant width
Used to display code samples, file contents, command-line interactions, library names, and database commands. Constant width bold
Indicates commands or other text that should be typed literally by the user. Also used for emphasis in code. Constant width italic
Shows text that should be replaced with user-supplied values. [ Keywords and other stuff ]
Indicates optional keywords and arguments. { choice-1 choice-2 } Signifies either choice-1 or choice-2. This icon signifies a tip, suggestion, or general note.
xxvi Preface
This icon indicates a warning or caution.
Using Code Examples This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission. We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Asterisk: The Definitive Guide, Third Edition, by Leif Madsen, Jim Van Meggelen, and Russell Bryant (O’Reilly). Copyright 2011 Leif Madsen, Jim Van Meggelen, and Russell Bryant, 978-0-596-51734-2.” If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [email protected]
Safari Books Online When you see a Safari Books Online icon on the cover of your favorite technology book, that means the book is available online through the O’Reilly Network Safari Bookshelf. Safari offers a solution that’s better than ebooks. It’s a virtual library that lets you easily search thousands of top tech books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current information. Try it for free at http://safari.oreilly.com.
How to Contact Us Please address comments and questions concerning this book to the publisher: O’Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472 (800) 998-9938 (in the United States or Canada) (707) 829-0515 (international or local) (707) 829-0104 (fax)
Preface xxvii
We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at: http://oreilly.com/catalog/9780596517342 To comment or ask technical questions about this book, send email to: [email protected] For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our website at: http://www.oreilly.com Find us on Facebook: http://facebook.com/oreilly Follow us on Twitter: http://twitter.com/oreillymedia Watch us on YouTube: http://www.youtube.com/oreillymedia
Acknowledgments To David Duffett, thanks for the excellent chapter on internationalization, which would not have been served well by being written by us North Americans. Next, we want to thank our fantastic editor, Michael Loukides, for your patience with this third edition, which took too long to get off the ground, and many long months to finally get written. Mike offered invaluable feedback and found incredibly tactful ways to tell us to rewrite a section (or chapter) when it was needed, and make us think it was our idea. Mike built us up when we were down, and brought us back to earth when we got uppity. You are a master, Mike, and seeing how many books have received your editorial oversight contributes to an understanding of why O’Reilly Media is the success that it is. Thanks also to Rachel Head (nee Rachel Wheeler), our copyeditor, who fixes all our silly grammar, spelling, and style mistakes (and the many Canadianisms that Leif and Jim feel compelled to include), and somehow leaves the result reading as if it was what we wrote in the first place. Copyeditors are the unsung heroes of publishing, and Rachel is one of the very best. Also thanks to Teresa Elsey, our production editor, and the rest of the unsung heroes in O’Reilly’s production department. These are the folks that take our book and make it an O’Reilly book. During the course of writing this book, we had the pleasure of being able to consult with many people with specific experience in various areas. Their generous contributions of time and expertise were instrumental in our research. Thanks to Randy Resnick, organizer of the VoIP User Group; Kevin Fleming of Digium; Lee Howard, author of iaxmodem and hylafax; Joshua Colp of Digium; Phillip Mullis of the Toronto Asterisk Users Group; Allison Smith, the Voice of Asterisk; Flavio E. Goncalves, author of books xxviii Preface
on Asterisk, OpenSER, and OpenSIPS; J. Oquendo, Security Guru; Tzafrir Cohen, font of knowledge about security and lots of other stuff; Jeff Gehlbach, for SNMP; Ovidiu Sas, for your encyclopedic knowlege of SIP; Tomo Takebe, for some SMDI help; Steve Underwood, for help with fax and spandsp; and Richard Genthner and John Covert, for helping with LDAP. A special thanks should also go to John Todd for being one of the first to write comprehensive Asterisk how-tos, all those years ago, and for all the many other things you do (and have done) for the Asterisk community.
Open Feedback Publishing System (OFPS) While we were writing this book, O’Reilly introduced its Open Feedback Publishing System (OFPS), which allowed our book to appear on the Web as we were writing it. Community members were able to submit feedback and comments, which was of enormous help to us. The following is a list of their names or handles*: Matthew McAughan, Matt Pusateri, David Van Ginneken, Asterisk Mania, Giovanni Vallesi, Mark Petersen, thp4, David Row, tvc123, Frederic Jean, John Todd, Steven Sokol, Laurent Steffan, Robert Dailey, Howard Harper, Joseph Rensin, Howard White, Jay Eames, Vincent Thomasset, Dave Barnow, Sebastien Dionne, Igor Nikolaev, Arend van der Kolk, Anwar Hossain, craigesmith, nkabir, anest, Nicholas Barnes, Alex Neuman, Justin Korkiner, Stefan Schmidt, pabelanger, jfinstrom, roderickmontgomery, Shae Erisson, Gaston Draque, Richard Genthner, Michael S Collins, and Jeff Peeler
Thanks to all of you for your valuable contribution to this book.
Thanks to Sean Bright, Ed Guy, Simon Ditner, and Paul Belanger for assisting us with clarifying best practices for user and group policies for Asterisk installation. In the past it was common to just install Asterisk with root permissions, but we have elected to describe an installation process that is more in keeping with Linux best practices,† and these fine gents contributed to our discussions on that. Kudos to all the folks working on the FreeSWITCH, YATE, SER, Kamailio, OpenSIPS, SER, sipXecs, Woomera, and any other open source telecom projects, for stimulating new thoughts, and for pushing the envelope. Everyone in the Asterisk community also needs to thank Jim Dixon for creating the first open source telephony hardware interfaces, starting the revolution, and giving his creations to the community at large. * We tried wherever possible to include the contributors’ names, but in some cases could not, and therefore included their handles instead. † Without starting a holy war!
Preface xxix
Finally, and most importantly, thanks go to Mark Spencer, the original author of Asterisk and founder of Digium, for Asterisk, for Pidgin (http://www.pidgin.im), and for contributing his creations to the open source community. Asterisk is your legacy!
Leif Madsen It sort of amazes me where I started with Asterisk, and where I’ve gone with Asterisk. In 2002, while attending school, a bunch of my friends and myself were experimenting with voice over the Internet using Microsoft’s MSN product. It worked quite well, and allowed us to play video games while conversing with each other—at least, until we wanted to add a third participant. So, I went out searching for some software that could handle multiple voices (the word was conferencing, but I didn’t even know that at the time, having had little exposure to PBX platforms). I searched the Internet but didn’t find anything in particular I liked (or that was free). I turned to IRC and explained what I was looking for. Someone (I wish I knew who) mentioned that I should check out some software called Asterisk (he presumably must have thought I was looking for MeetMe(), which I was). Having the name, I grabbed the software and started looking at what it could do. Incredibly, the functionality I was looking for, which I thought would be the entirety of the software, was only one component in a sea of functionality. And having run a BBS for years prior to going to college, the fact that I could install a PCI card and connect it to the phone network was not lost on me. After a couple of hours of looking at the software and getting it compiled, I started telling one of my teachers about the PCI cards and how maybe we could get some for the classroom for labs and such (our classroom had 30 computers at 10 tables of 3). He liked the idea and started talking to the program coordinator, and within about 30 minutes an order had been placed for 20 cards. Pretty amazing considering they were TDM400Ps decked out with four daughter cards, and they had only heard about them an hour prior to that. Then the obsession began. I spent every extra moment of that semester with a couple of computers dedicated to Asterisk use. In those two months, I learned a lot. Then we had a co-op break. I didn’t find any work immediately, so I moved home and continued working on Asterisk, spending time on IRC, reading through examples posted by John Todd, and just trying to wrap my head around how the software worked. Luckily I had a lot of help on IRC (for these were the days prior to any documentation on Asterisk), and I learned a lot more during that semester. Seeing that the people who took a great interest in Asterisk at the time had a strong sense of community and wanted to contribute back, I wanted to do the same. Having no practical level of coding knowledge, I decided documentation would be something useful to start doing. Besides, I had been writing a lot of papers at school, so I was getting better at it. One night I put up a website called The Asterisk Documentation Assigned (TADA) and started writing down any documentation I could. A couple of weeks later Jared Smith and I started talking, and started the Asterisk Documentation
xxx Preface
Project (http://www.asteriskdocs.org), with the goal of writing an Asterisk book for the community. That project became the basis of the first edition of this book, Asterisk: The Future of Telephony. Nine years later, I’m still writing Asterisk documentation and have become the primary bug marshal and release manager for the Asterisk project, spoken at every single AstriCon since 2004 (at which Jared and I spoke about the Asterisk Documentation Project; I still have the AsteriskDocs magnet his wife made), and become a consultant specializing in database integration (thanks Tilghman for func_odbc) and clustering (thanks Mark Spencer for DUNDi). I really love Asterisk, and all that it’s allowed me to do. First, thanks to my parents Rick and Carol, for the understanding and support in everything I’ve done in my life. From the first computer they purchased for far too much money when I was in grade 6 (I started taking an interest in computers in grade 2 using a Commodore 64, and they got me a computer after a parent-teacher interview a few years later) to letting me use the home phone line for my BBS endeavors (and eventually getting me my own phone line), and everything else they have ever done for me, I can never thank them enough. I love you both more than you’ll ever imagine. Thanks to my Grandma T for letting me use her 286 during the years when I didn’t have a computer at home, and for taking me shopping every year on my birthday for 15 years. Love lots! To my beautiful wife, Danielle, for setting the alarm every morning before she left for work, letting me sleep those extra 10 minutes before starting on this book, and understanding when I had to work late because I went past my 9 A.M. stop-writing time, thank you and I love you so much. There are so many people who help me and teach me new things every day, but the most influential on my life in Asterisk are the following: Mark Spencer for writing software that has given me a fantastic career, John Todd for his early examples, Brian K. West for his early help and enthusiasm on IRC, Steve Sokol and Olle Johansson for flying me to my first AstriCon (and subsequent ones!) and letting me be part of the first Asterisk training classes, Jared Smith for helping start the documentation project and doing all the infrastructure that I could never have done, Jim Van Meggelen for joining in early on the project and teaching me new ways to look at life, and Russell Bryant for being an amazing project leader and easy to work with every day, and for not holding a grudge about the bush.
Jim Van Meggelen When we set out to write the very first edition of this book over five years ago, we were confident that Asterisk was going to be a huge success. Now, a half-decade later, we’ve written this third edition of what the worldwide Asterisk community calls “The Asterisk Book,” and we’ve matured from revolutionaries into Asterisk professionals.
Preface xxxi
Asterisk has proven that open source telecom is a lasting idea, and the open source telecom landscape is nowadays complemented by more than just Asterisk. Projects like Freeswitch, sipXecs (from SipFoundry), OpenSER/Kamailio/OpenSIPS, and many, many more (and more to come) help to round out the ecosystem. I want to take this opportunity to thank my very good friend Leif Madsen, who has been with me through all three editions. In our daily lives we don’t always have many opportunities to work with each other (or even grab a pint, these days!), and it’s always a delight to work with you. I also want to thank Russell Bryant, who joined us for this edition, and whose dedication to this project and the Asterisk project in general is an inspiration to me. You’re a Renaissance man, Russell. To Jared Smith, who helped found the Asterisk Documentation Project and coauthored the first two editions with Leif and me (but has since moved on to the Fedora project), I can only say: Asterisk’s loss is Fedora’s gain. I would like to thank my business partners at Core Telecom Innovations and iConverged LLC, without whom I could not do all the cool things I get to do in my professional career. I would like to thank all my friends in the improv community, for helping me to keep laughing at all the challenges that life presents. Thanks to all my family, who bring love into my life. Finally, thanks to you, the Asterisk community. This book is our gift to you. We hope you enjoy reading it as much as we’ve enjoyed writing it.
Russell Bryant I started working on Asterisk in 2004. I was a student at Clemson University and was working as a co-op engineer at ADTRAN in Huntsville, Alabama. My first job at ADTRAN was working in the Product Qualification department. I remember working with Keith Morgan to use Asterisk as a VoIP traffic generator for testing QoS across a router test network. Meanwhile, a fellow co-op and friend, Adam Schreiber, introduced me to Mark Spencer. Over the next six months, I immersed myself in Asterisk. I learned as much as I could about Asterisk, telephony, and C programming. When Asterisk 1.0 was released in the fall of 2004, I was named the release maintainer. At the beginning of 2005, I was hired by Digium to continue my work on Asterisk professionally. I have spent the past six amazing years working with Digium to improve Asterisk. I have worked as a software developer, a software team lead, and now as the engineering manager of the Asterisk development team. I am extremely grateful for the opportunity to contribute to so many areas of the Asterisk project. There are many people that deserve thanks for the support they have provided along the way.
xxxii Preface
To my wife, Julie, I cannot thank you enough for all the love and support you have given me. Thank you for keeping my life balanced and happy. You are the best. I love you! To my parents, thank you for giving me so many great opportunities in my life to explore different things and find what I really enjoy. You taught me to work hard and never give up. To Leif and Jim, thank you for your invitation to contribute to this book. It has been a fun project, largely due to the pleasure of working with the two of you. Thanks for the laughs and for your dedication to this book as a team effort. I have learned a lot from many people at Digium. There are three people who stand out the most as my mentors: Mark Spencer, Kevin P. Fleming, and David Deaton. Thank you all for going the extra mile to teach me along the way. I am extremely grateful. To the software development team at Digium, thank you for being such an amazing team to work with. Your dedication and brilliance play a huge part in the success of Asterisk and make Digium a great place to work. To Travis Axtell, thank you for your help in my early days of learning about Linux and for being a good friend. To my dogs, Chloe and Baxter, thanks for keeping me company while I worked on the book every morning. To all of my friends and family, thank you for your love, support, and fun times. To the entire Asterisk community, thank you for using, enjoying, and contributing to Asterisk. We hope you enjoy the book!
Preface xxxiii
CHAPTER 1
A Telephony Revolution
First they ignore you, then they laugh at you, then they fight you, then you win. —Mahatma Gandhi
When we first set out—nearly five years ago—to write a book about Asterisk, we confidently predicted that Asterisk would fundamentally change the telecommunications industry. Today, the revolution we predicted is all but complete. Asterisk is now the most successful private branch exchange (PBX) in the world, and is an accepted (albeit perhaps not always loved) technology in the telecom industry. Unfortunately, over the past five years the telecom industry has continued to lose its way. The methods by which we communicate have changed. Whereas 20 years ago phone calls were the preferred way to converse across distances, the current trend is to message via text (email, IM, etc.). The phone call is seen as a bit of a dead thing, especially by up-and-coming generations. Asterisk remains pretty awesome technology, and we believe it is still one of the best hopes for any sort of sensible integration between telecom and all the other technologies businesses might want to interconnect with. With Asterisk, no one is telling you how your phone system should work, or what technologies you are limited to. If you want it, you can have it. Asterisk lovingly embraces the concept of standards compliance, while also enjoying the freedom to develop its own innovations. What you choose to implement is up to you—Asterisk imposes no limits. Naturally, this incredible flexibility comes with a price: Asterisk is not a simple system to configure. This is not because it’s illogical, confusing, or cryptic; on the contrary, it is very sensible and practical. People’s eyes light up when they first see an Asterisk dialplan and begin to contemplate the possibilities. But when there are literally thousands of ways to achieve a result, the process naturally requires extra effort. Perhaps it can be compared to building a house: the components are relatively easy to understand, but a person contemplating such a task must either a) enlist competent help or 1
b) develop the required skills through instruction, practice, and a good book on the subject.
Asterisk and VoIP: Bridging the Gap Between Traditional and Network Telephony Voice over IP (VoIP) is often thought of as little more than a method of obtaining free long-distance calling. The real value (and—let’s be honest—challenge as well) of VoIP is that it allows voice to become nothing more than another application in the data network. It sometimes seems that we’ve forgotten that the purpose of the telephone is to allow people to communicate. It is a simple goal, really, and it should be possible for us to make it happen in far more flexible and creative ways than are currently available to us. Technologies such as Asterisk lower the barriers to entry.
The Zapata Telephony Project When the Asterisk project was started (in 1999), there were other open-source telephony projects in existence. However, Asterisk, in combination with the Zapata Telephony Project, was able to provide public switched telephone interface (PSTN) interfaces, which represented an important milestone in transitioning the software from something purely network-based to something more practical in the world of telecom at that time, which was PSTN-centric. The Zapata Telephony Project was conceived of by Jim Dixon, a telecommunications consulting engineer who was inspired by the incredible advances in CPU speeds that the computer industry has now come to take for granted. Dixon’s belief was that far more economical telephony systems could be created if a card existed that had nothing more on it than the basic electronic components required to interface with a telephone circuit. Rather than having expensive components on the card, digital signal processing (DSP)* would be handled in the CPU by software. While this would impose a tremendous load on the CPU, Dixon was certain that the low cost of CPUs relative to their performance made them far more attractive than expensive DSPs, and, more importantly, that this price/performance ratio would continue to improve as CPUs continued to increase in power. Like so many visionaries, Dixon believed that many others would see this opportunity, and that he merely had to wait for someone else to create what to him was an obvious improvement. After a few years, he noticed that not only had no one created these cards,
* The term DSP also means digital signal processor, which is a device (usually a chip) that is capable of interpreting and modifying signals of various sorts. In a voice network, DSPs are primarily responsible for encoding, decoding, and transcoding audio information. This can require a lot of computational effort.
2 Chapter 1: A Telephony Revolution
but it seemed unlikely that anyone was ever going to. At that point it was clear that if he wanted a revolution, he was going to have to start it himself. And so the Zapata Telephony Project was born: Since this concept was so revolutionary, and was certain to make a lot of waves in the industry, I decided on the Mexican revolutionary motif, and named the technology and organization after the famous Mexican revolutionary Emiliano Zapata. I decided to call the card the “tormenta” which, in Spanish, means “storm,” but contextually is usually used to imply a big storm, like a hurricane or such.†
Perhaps we should be calling ourselves Asteristas. Regardless, we owe Jim Dixon a debt of thanks, partly for thinking this up and partly for seeing it through, but mostly for giving the results of his efforts to the open source community. As a result of Jim’s contribution, Asterisk’s PSTN engine came to be. Over the years, the Zapata Telephony interface in Asterisk has been modified and improved. The Digium Asterisk Hardware Device Interface (DAHDI) Telephony interface in use today is the offspring of Jim Dixon’s contribution.
Massive Change Requires Flexible Technology Every PBX in existence suffers from shortcomings. No matter how fully featured it is, something will always be left out, because even the most feature-rich PBX will always fail to anticipate the creativity of the customer. A small group of users will desire an odd little feature that the design team either did not think of or could not justify the cost of building, and, since the system is closed, the users will not be able to build it themselves. If the Internet had been thusly hampered by regulation and commercial interests, it is doubtful that it would have developed the wide acceptance it currently enjoys. The openness of the Internet meant that anyone could afford to get involved. So, everyone did. The tens of thousands of minds that collaborated on the creation of the Internet delivered something that no corporation ever could have.‡ As with many other open source projects, such as Linux and so much of the critical software running the Internet, the development of Asterisk was fueled by the dreams of folks who knew that there had to be something more than what traditional industries were producing. These people knew that if one could take the best parts of various PBXs and separate them into interconnecting components—akin to a boxful of LEGO bricks—one could begin to conceive of things that would not survive a traditional
† Jim Dixon, “The History of Zapata Telephony and How It Relates to the Asterisk PBX” (http://www .asteriskdocs.org/modules/tinycontent/index.php?id=10). ‡ We realize that the technology of the Internet formed out of government and academic institutions, but what we’re talking about here is not the technology of the Internet so much as the cultural phenomenon of it, which exploded in the early ’90s.
Massive Change Requires Flexible Technology 3
corporate risk-analysis process. While no one can seriously claim to have a complete picture of what this thing should look like, there is no shortage of opinions and ideas.§ Many people new to Asterisk see it as unfinished. Perhaps these people can be likened to visitors to an art studio, looking to obtain a signed, numbered print. They often leave disappointed, because they discover that Asterisk is the blank canvas, the tubes of paint, the unused brushes waiting.‖ Even at this early stage in its success, Asterisk is nurtured by a greater number of artists than any other PBX. Most manufacturers dedicate no more than a few developers to any one product; Asterisk has scores. Most proprietary PBXs have a worldwide support team comprising a few dozen real experts; Asterisk has hundreds. The depth and breadth of the expertise that surrounds this product is unmatched in the telecom industry. Asterisk enjoys the loving attention of old telco guys who remember when rotary dial mattered, enterprise telecom people who recall when voicemail was the hottest new technology, and data communications geeks and coders who helped build the Internet. These people all share a common belief—that the telecommunications industry needs a proper revolution.# Asterisk is the catalyst.
Asterisk: The Hacker’s PBX Telecommunications companies that choose to ignore Asterisk do so at their peril. The flexibility it delivers creates possibilities that the best proprietary systems can scarcely dream of. This is because Asterisk is the ultimate hacker’s PBX. The term hacker has, of course, been twisted by the mass media into meaning “malicious cracker.” This is unfortunate, because the term actually existed long before the media corrupted its meaning. Hackers built the networking engine that is the Internet. Hackers built the Apple Macintosh and the Unix operating system. Hackers are also building your next telecom system. Do not fear; these are the good guys, and they’ll be able to build a system that’s far more secure than anything that exists today. Rather than being constricted by the dubious and easily cracked security of closed systems,
§ Between the releases of Asterisk 1.2 and Asterisk 1.4, over 4,000 updates were made to the code in the SVN repository. Between the releases of Asterisk 1.4 and 1.8, over 10,000 updates were made. ‖ It should be noted that these folks need not leave disappointed. Several projects have arisen to lower the barriers to entry for Asterisk. By far the most popular and well known is the FreePBX interface (and the multitude of projects based on it). These interfaces (check out http://www.voip-info.org/wiki/view/Asterisk +GUI for an idea of how many there are) do not make it easier to learn Asterisk, because they separate you from the platform or dialplan configuration, but many of them will deliver a working PBX to you much faster than the more hands-on approach we employ in this book. #The telecom industry has been predicting a revolution since before the crash; time will tell how well it responds to the open source revolution.
4 Chapter 1: A Telephony Revolution
the hackers will be able to quickly respond to changing trends in security and fine-tune the telephone system in response to both corporate policy and industry best practices. Like other open source systems, Asterisk will be able to evolve into a far more secure platform than any proprietary system, not in spite of its hacker roots, but rather because of them.
Asterisk: The Professional’s PBX Never in the history of telecommunications has a system so suited to the needs of business been available, at any price. Asterisk is an enabling technology, and as with Linux, it will become increasingly rare to find an enterprise that is not running some version of Asterisk, in some capacity, somewhere in the network, solving a problem as only Asterisk can. This acceptance is likely to happen much faster than it did with Linux, though, for several reasons: • Linux has already blazed the trail that led to open source acceptance. Asterisk is following that lead. • The telecom industry is crippled, with no leadership being provided by the giant industry players. Asterisk has a compelling, realistic, and exciting vision. • End users are fed up with incompatible and limited functionality, and horrible support. Asterisk solves the first two problems; entrepreneurs and the community are addressing the latter.
The Asterisk Community One of the compelling strengths of Asterisk is the passionate community that developed and supports it. This community, led by the fine folks at Digium, is keenly aware of the cultural significance of Asterisk and has an optimistic view of the future. One of the more powerful side effects of the Asterisk community’s energy is the cooperation it has spawned among telecommunications, networking, and information technology professionals who share a love for this phenomenon. While these cadres have traditionally been at odds with each other, in the Asterisk community they delight in each others’ skills. The significance of this cooperation cannot be underestimated. If the dream of Asterisk is to be realized, the community must continue to grow—yet one of the key challenges that the community currently faces is a rapid influx of new users. The members of the existing community, having birthed this thing called Asterisk, are generally welcoming of new users, but they’ve grown impatient with being asked the kinds of questions whose answers can often be obtained independently, if one is willing to devote some time to research and experimentation.
The Asterisk Community 5
Obviously, new users do not fit any particular kind of mold. While some will happily spend hours experimenting and reading various blogs describing the trials and tribulations of others, many people who have become enthusiastic about this technology are completely uninterested in such pursuits. They want a simple, straightforward, stepby-step guide that’ll get them up and running, followed by some sensible examples describing the best methods of implementing common functionality (such as voicemail, auto attendants, and the like). To the members of the expert community, who (correctly) perceive that Asterisk is like a web development language, this approach doesn’t make any sense. To them, it’s clear that you have to immerse yourself in Asterisk to appreciate its subtleties. Would one ask for a step-by-step guide to programming and expect to learn from it all that a language has to offer? Clearly, there’s no one approach that’s right for everyone. Asterisk is a different animal altogether, and it requires a totally different mind-set. As you explore the community, though, be aware that it includes people with many different skill sets and attitudes. Some of these folks do not display much patience with new users, but that’s often due to their passion for the subject, not because they don’t welcome your participation.
The Asterisk Mailing Lists As with any community, there are places where members of the Asterisk community meet to discuss matters of mutual interest. Of the mailing lists you will find at http:// lists.digium.com, these three are currently the most important: Asterisk-Biz Anything commercial with respect to Asterisk belongs in this list. If you’re selling something Asterisk-related, sell it here. If you want to buy an Asterisk service or product, post here. Asterisk-Dev The Asterisk developers hang out here. The purpose of this list is the discussion of the development of the software that is Asterisk, and its participants vigorously defend that purpose. Expect a lot of heat if you post anything to this list not specifically relating to programming or development of the Asterisk code base. General coding questions (such as queries on interfacing with AGI or AMI) should be directed to the Asterisk-Users list. The Asterisk-Dev list is not second-level support! If you scroll through the mailing list archives, you’ll see this is a strict rule. The Asterisk-Dev mailing list is about discussion of core Asterisk development, and questions about interfacing your external programs via AGI or AMI should be posted on the Asterisk-Users list.
6 Chapter 1: A Telephony Revolution
Asterisk-Users This is where most Asterisk users hang out. This list generates several hundred messages per day and has over ten thousand subscribers. While you can go here for help, you are expected to have done some reading on your own before you post a query.
Asterisk Wiki Sites The Asterisk Wiki (which exists in large part due to the tireless efforts of James Thompson—thanks James!) is a source of much enlightenment and confusion. Another important resource is the community-maintained repository of VoIP knowledge at http: //www.voip-info.org, which contains a truly inspiring cornucopia of fascinating, informative, and frequently contradictory information about many subjects, just one of which is Asterisk. Since Asterisk documentation forms by far the bulk of the information on this website,* and it probably contains more Asterisk knowledge than all other sources put together (with the exception of the mailing list archives), it is a popular place to go for Asterisk knowledge. An important new wiki project is the official Asterisk Wiki, found at http://wiki.asterisk .org. While not yet as full of content as voip-info.org, this wiki will be more formally supported and is therefore more likely to contain information that is kept current and accurate.
The IRC Channels The Asterisk community maintains Internet Relay Chat (IRC) channels on irc.freenode.net. The two most active channels are #asterisk and #asterisk-dev.† To cut down on spam-bot intrusions, both of these channels now require registration to join.‡
Asterisk User Groups Over the past decade, in many cites around the world, lonely Asterisk users began to realize that there were other like-minded people in their towns. Asterisk User Groups (AUGs) began to spring up all over the place. While these groups don’t have any official affiliation with each other, they generally link to one anothers’ websites and welcome members from anywhere. Type “Asterisk User Group” into Google to track down one in your area.
* More than 30%, at last count. † The #asterisk-dev channel is for the discussion of changes to the underlying code base of Asterisk and is also not second-tier support. Discussions related to programming external applications that interface with Asterisk via AGI or AMI are meant to be in #asterisk. ‡ To register, run /msg nickserv help when you connect to the service via your favorite IRC client.
The Asterisk Community 7
The Asterisk Documentation Project The Asterisk Documentation Project was started by Leif Madsen and Jared Smith, but several people in the community have contributed. The goal of the documentation project is to provide a structured repository of written work on Asterisk. In contrast with the flexible and ad hoc nature of the Wiki, the Docs project is passionate about building a more focused approach to various Asterisk-related subjects. As part of the efforts of the Asterisk Docs project to make documentation available online, this book is available at the http://www.asteriskdocs.org website, under a Creative Commons license.
The Business Case It is very rare to find businesses these days that do not have to reinvent themselves every few years. It is equally rare to find a business that can afford to replace its communications infrastructure each time it goes in a new direction. Today’s businesses need extreme flexibility in all of their technology, including telecom. In his book Crossing the Chasm (HarperBusiness), Geoffrey Moore opines, “The idea that the value of the system will be discovered rather than known at the time of installation implies, in turn, that product flexibility and adaptability, as well as ongoing account service, should be critical components of any buyer’s evaluation checklist.” What this means, in part, is that the true value of a technology is often not known until it has been deployed. How compelling, then, to have a system that holds at its very heart the concept of openness and the value of continuous innovation.
Conclusion So where to begin? Well, when it comes to Asterisk, there is far more to talk about than we can fit into one book. This book can only lay down the basics, but from this foundation you will be able to come to an understanding of the concept of Asterisk—and from that, who knows what you will build?
8 Chapter 1: A Telephony Revolution
CHAPTER 2
Asterisk Architecture
First things first, but not necessarily in that order. —Doctor Who
Asterisk is very different from other, more traditional PBXs, in that the dialplan in Asterisk treats all incoming channels in essentially the same manner. In a traditional PBX, there is a logical difference between stations (telephone sets) and trunks (resources that connect to the outside world). This means, for example, that you can’t install an external gateway on a station port and route external calls to it without requiring your users to dial the extension number first. Also, the concept of an off-site resource (such as a reception desk) is much more difficult to implement on a traditional PBX, because the system will not allow external resources any access to internal features.* Asterisk, on the other hand, does not have an internal concept of trunks or stations. In Asterisk, everything that comes into or goes out of the system passes through a channel of some sort. There are many different kinds of channels; however, the Asterisk dialplan handles all channels in a similar manner, which means that, for example, an internal user can exist on the end of an external trunk (e.g., a cell phone) and be treated by the dialplan in exactly the same manner as that user would be if she were on an internal extension. Unless you have worked with a traditional PBX, it may not be immediately obvious how powerful and liberating this is. Figure 2-1 illustrates the differences between the two architectures.
* To be fair, many traditional PBXs do offer this sort of functionality. However, it is generally kludgy, limited in features, and requires complex, proprietary software to be installed in the PBX (such as vendor-specific protocol extensions).
9
Figure 2-1. Asterisk vs. PBX architecture
Modules Asterisk is built on modules. A module is a loadable component that provides a specific functionality, such as a channel driver (for example, chan_sip.so), or a resource that allows connection to an external technology (such as func_odbc.so). Asterisk modules are loaded based on the /etc/asterisk/modules.conf file. We will discuss the use of many modules in this book. At this point we just want to introduce the concept of modules, and give you a feel for the types of modules that are available. It is actually possible to start Asterisk without any modules at all, although in this state it will not be capable of doing anything. It is useful to understand the modular nature of Asterisk in order to appreciate the architecture. You can start Asterisk with no modules loaded by default and load each desired module manually from the console, but this is not something that you’d want to put into production; it would only be useful if you were performance-tuning a system where you wanted to eliminate everything not required by your specific application of Asterisk.
The types of modules in Asterisk include the following: • • • •
Applications Bridging modules Call detail recording (CDR) modules Channel event logging (CEL) modules
10 Chapter 2: Asterisk Architecture
• • • • • • • •
Channel drivers Codec translators Format interpreters Dialplan functions PBX modules Resource modules Addons modules Test modules
In the following sections we will list each module available within these categories, briefly identify its purpose, and give our opinion on its relative popularity and/or importance (while some modules are proven and deservedly popular, others are quite old, are barely ever used anymore, and are only maintained for the purpose of backwardcompatibility). The details of how specific modules work will be covered in various chapters throughout the book, depending on what the module is and what it does. Some modules will be covered thoroughly; others may not be covered at all. Regarding the Popularity/Status column in the tables that follow, the following list contains our opinions with respect to the meanings we have chosen (your mileage may vary): Insignificant This module is ancient history. If you use it, be aware that you are mostly on your own when it comes to any sort of community support. Unreliable This module is new or experimental, and is not suitable for production. Useful This module is current, maintained, popular, and recommended. Usable This module works but may be incomplete or unpopular, and/or is not recommended by the authors. New This module is quite new, and its completeness and popularity are difficult to gauge at this time. Deprecated This module has been replaced by something that is considered superior. Limited This module has limitations that may make it unsuitable to your requirements. Essential This module is one you’ll never want to be without.
Modules 11
And now, without further ado, let’s take a look at the modules, grouped by module type.
Applications Dialplan applications are used in extensions.conf to define the various actions that can be applied to a call. The Dial() application, for example, is responsible for making outgoing connections to external resources and is arguably the most important dialplan application. The available applications are listed in Table 2-1. Table 2-1. Dialplan applications Name
Purpose
Popularity/Status
app_adsiprog
Loads Analog Display Services Interface (ADSI) scripts into compatible analog phones
Insignificant
app_alarmreceiver
Supports receipt of reports from alarm equipment
Insignificant
app_amd
Detects answering machines
Unreliable
app_authenticate
Compares dual-tone multi-frequency (DTMF) input against a provided string (password)
Useful
app_cdr
Writes ad hoc record to CDR
Useful
app_celgenuserevent
Generates user-defined events for CEL
New
app_chanisavail
Checks the status of a channel
Unreliable
app_channelredirect
Forces another channel into a different part of the dialplan
Useful
app_chanspy
Allows a channel to listen to audio on another channel
Useful
app_confbridge
Provides conferencing (new version)
New—not fully featured yet
app_controlplayback
Plays back a prompt and offers fast forward and rewind functions
Useful
app_dahdibarge
Allows barging in on a DAHDI channel
Deprecated—see app_chanspy
app_dahdiras
Creates a RAS server over a DAHDI channel (no modem emulation)
Insignificant
app_db
Used to add/change/delete records in Asterisk’s built-in Berkeley database
Deprecated—see func_db
app_dial
Used to connect channels together (i.e., make phone calls)
Essential
app_dictate
Plays back a recording and offers start/stop functions
Useful
app_directed_pickup
Answers a call for another extension
Useful
app_directory
Presents the list of names from voicemail.conf
Useful
app_disa
Provides dialtone and accepts DTMF input
Usefula
app_dumpchan
Dumps channel variables to Asterisk command-line interface (CLI)
Useful
12 Chapter 2: Asterisk Architecture
Name
Purpose
Popularity/Status
app_echo
Loops received audio back to source channel
Useful
app_exec
Contains Exec(), TryExec(), and ExecIf(); executes a dialplan application based on conditions
Useful
app_externalivr
Controls Asterisk as with an AGI, only asynchronously
Useful
app_fax
Provides SendFax() and ReceiveFax()
Usefulb
app_festival
Enables basic text to speech using Festival TTS engine
Usable
app_flash
Performs a hook-switch flash on channels (primarily analog)
Useful
app_followme
Performs find me/follow me functionality based on followme.conf
Useful
app_forkcdr
Starts new CDR record on current call
Usable
app_getcpeid
Gets the ADSI CPE ID
Insignificant
app_ices
Sends audio to an Icecast server
Usable
app_image
Transmits an image to supported devices
Limited
app_ivrdemo
Sample application for developers
Insignificant
app_jack
Works with JACK Audio Connection Kit to share audio between compatible applications
Useful
app_macro
Triggers dialplan macros
Deprecated—see GoSub()
app_meetme
Provides multiparty conferencing
Useful—fully featured
app_milliwatt
Generates 1004-Hz tone for testing loss on analog circuits
Useful
app_minivm
Provides primitive functions to allow you to build your own voicemail application in dialplan
Usable
app_mixmonitor
Records both sides of a call and mixes them together
Useful
app_morsecode
Generates Morse code
Usable
app_mp3
Uses mpg123 to play an MP3
Insignificant
app_nbscat
Streams audio from Network Broadcast Stream (NBS)
Insignificant
app_originate
Allows origination of a call
Useful
app_osplookup
Performs Open Settlement Protocol (OSP) lookup
Usable
app_page
Creates multiple audio connections to specified devices for public address (paging)
Useful
app_parkandannounce
Enables automated announcing of parked calls
Usable
app_playback
Plays a file to the channel (does not accept input)
Useful
app_playtones
Plays pairs of tones of specified frequencies
Useful
app_privacy
Requests input of caller’s phone number if no CallerID is received
Insignificant
app_queue
Provides Automatic Call Distribution (ACD)
Useful
Modules 13
Name
Purpose
Popularity/Status
app_read
Requests input of digits from callers and assigns input to a variable
Useful
app_readexten
Requests input of digits from callers and passes call to a designated extension and context
Usable
app_readfile
Loads contents of a text file into a channel variable
Deprecated—see the FILE() function in func_env
app_record
Records received audio to a file
Useful
app_rpt
Provides a method to interface with an audio board for the app_rpt project
Limited
app_sayunixtime
Plays back time in specified format
Useful
app_senddtmf
Transmits DTMF to calling party
Useful
app_sendtext
Sends a text string to compatible channels
Insignificant
app_setcallerid
Sets CallerID on a channel
Deprecated—see func_call
app_skel
Sample application for developers
Usefulc
app_sms
Sends SMS message in compatible countries
Limited
app_softhangup
Requests hangup of channel
Useful
app_speech_utils
Provides utilities relating to speech recognition
Usefuld
app_stack
Provides Gosub(), GoSubIf(), Return(), Stack Pop(), LOCAL(), and LOCAL_PEEK()
Essential
app_system
Executes commands in a Linux shell
Useful
app_talkdetect
Similar to app_background, but allows for any received audio to interrupt playback
Useful
app_test
Client/server testing application
Usable
app_transfer
Performs a transfer on the current channel
Useful
app_url
Passes a URI to the called channel
Limited
app_userevent
Generates a custom event in the Asterisk Manager Interface (AMI)
Useful
app_verbose
Generates a custom event in the Asterisk CLI
Useful
app_voicemail
Provides voicemail
Essential
app_waitforring
Waits for a RING signaling event (not to be confused with RINGING); most likely unnecessary, as only chan_dahdi with analog channels where ringing is received (such as an FXO port) generates the RING signaling event
Insignificant
app_waitforsilence
Includes WaitForSilence() and WaitForNoise(); listens to the incoming channel for a specified number of milliseconds of noise/silence
Useful
app_waituntil
Waits until current Linux epoch matches specified epoch
Useful
erid
14 Chapter 2: Asterisk Architecture
a b c d
Name
Purpose
Popularity/Status
app_while
Includes While(), EndWhile(), ExitWhile(), and ContinueWhile(); provides while-loop functionality in the dialplan
Useful
app_zapateller
Generates SIT tone to discourage telemarketers
Usable
The use of (DISA) is considered to be a security risk. Requires a suitable DSP engine to handle encoding/decoding of fax signaling (see Chapter 19). If you are a developer. Requires an external speech recognition application.
Bridging Modules Bridging modules are new in Asterisk 1.8: they perform the actual bridging of channels in the new bridging API. Each provides different features, which get used in different situations depending on what a bridge needs. These modules, listed in Table 2-2, are currently only used for (and are essential to) app_confbridge. Table 2-2. Bridging modules Name
Purpose
Popularity/Status
bridge_builtin_features
Performs bridging when utilizing built-in user features (such as those found in features.conf).
New
bridge_multiplexed
Performs complex multiplexing, as would be required in a large conference room (multiple participants). Currently only used by app_confbridge.
New
bridge_simple
Performs simple channel-to-channel bridging.
New
bridge_softmix
Performs simple multiplexing, as would be required in a large conference room (multiple participants). Currently only used by app_confbridge.
New
Call Detail Recording Modules The CDR modules, listed in Table 2-3, are designed to facilitate as many methods of storing call detail records as possible. You can store CDRs to a file (default), a database, RADIUS, or syslog. Call detail records are not intended to be used in complex billing applications. If you require more control over billing and call reporting, you will want to look at channel event logging, discussed next. The advantage of CDR is that it just works.
Modules 15
Table 2-3. Call detail recording modules Name
Purpose
Popularity/Status
cdr_adaptive_odbc
Allows writing of CDRs through ODBC framework with ability to add custom fields
Useful
cdr_csv
Writes CDRs to disk as a comma-separated values file
Usable
cdr_custom
As above, but allows for the addition of custom fields
Useful
cdr_manager
Outputs CDRs to Asterisk Manager Interface (AMI)
Useful
cdr_odbc
Writes CDRs through ODBC framework
Usable
cdr_pgsql
Writes CDRs to PostgreSQL
Useful
cdr_radius
Writes CDRs to RADIUS
Usable—does not support custom fields
cdr_sqlite
Writes CDRs to SQLite2 database
Deprecated—use sqlite3_custom
cdr_sqlite3_custom
Writes CDRs to SQLite3 with custom fields
Useful
cdr_syslog
Writes CDRs to syslog
Useful
cdr_tds
Writes CDRs to Microsoft SQL or Sybase
Usable—requires an old version of libtds
We will discuss some reporting packages that you may wish to use with CDR in Chapter 25.
Channel Event Logging Modules Channel event logging provides much more powerful control over reporting of call activity. By the same token, it requires more careful planning of your dialplan, and by no means will it work automatically. Asterisk’s CEL modules are listed in Table 2-4. Table 2-4. Channel event logging modules Name
Purpose
Popularity/Status
cel_custom
CEL to disk/file
Useful
cel_manager
CEL to AMI
Useful
cel_odbc
CEL to ODBC
Useful
cel_pgsql
CEL to PostgreSQL
Useful
cel_radius
CEL to RADIUS
Usable—does not support custom fields
cel_sqlite3_custom
CEL to Sqlite3
Useful
cel_tds
CEL to Microsoft SQL or Sybase
Usable—requires an old version of libtds
16 Chapter 2: Asterisk Architecture
Channel Drivers Without channel drivers, Asterisk would have no way to make calls. Each channel driver is specific to the protocol or channel type it supports (SIP, ISDN, etc.). The channel module acts as a gateway to the Asterisk core. Asterisk’s channel drivers are listed in Table 2-5. Table 2-5. Channel drivers
a b
Name
Purpose
Popularity/Status
chan_agent
Provides agent channel for Queue()
Useful
chan_alsa
Provides connection to Advanced Linux Sound Architecture
Useful
chan_bridge
Used internally by the ConfBridge() application; should not be used directly
Essential a
chan_console
Provides connection to portaudio
New
chan_dahdi
Provides connection to PSTN cards that use DAHDI channel drivers
Useful
chan_gtalk
Provides connection to Google Talk
Usable
chan_h323
Provides connection to H.323 endpoints
Deprecated—see chan_ooh323 in Table 2-11
chan_iax2
Provides connection to IAX2 endpoints
Useful
chan_jingle
Provides connection to Jingle-enabled endpoints
Usable
chan_local
Provides a mechanism to treat a portion of the dialplan as a channel
Useful
chan_mgcp
Media Gateway Control Protocol channel driver
Usable
chan_misdn
Provides connection to mISDN supported ISDN cards
Limited
chan_multicast_rtp
Provides connection to multicast RTP streams
Useful
chan_nbs
Network Broadcast Sound channel driver
Insignificant
chan_oss
Open Sound System driver
Useful
chan_phone
Linux telephony interface driver (very old)
Insignificant
chan_sip
Session Initiation Protocol channel driver
Essential
chan_skinny
Cisco Skinny Client Control Protocol (SCCP) channel driver
Usable
chan_unistim
Nortel Unistim protocol channel driver
Usable
chan_usbradio
Channel driver for CM108 USB cards with radio interface
Usable
chan_vpb
Voicetronix channel driver
Insignificantb
If you are using the ConfBridge() application. Some Voicetronix hardware is supported by Zaptel using an addon Zaptel module distributed by Voicetronix. However, Zaptel is no longer supported by Asterisk and this driver has not been ported to DAHDI.
Modules 17
Codec Translators The codec translators (Table 2-6) allow Asterisk to convert audio stream formats between calls. So if a call comes in on a PRI circuit (using G.711) and needs to be passed out a compressed SIP channel (e.g., using G.729, one of many codecs that SIP can handle), the relevant codec translator would perform the conversion.† If a codec (such as G.729) uses a complex encoding algorithm, heavy use of transcoding can place a massive burden on the CPU. Specialized hardware for the decoding/encoding of G.729 is available from hardware manufacturers such as Sangoma and Digium (and likely others). Table 2-6. Codec translators
a
Name
Purpose
Popularity/Status
codec_adpcm
Adaptive Differential Pulse Coded Modulation codec
Insignificant
codec_alaw
A-law PCM codec used all over the world (except Canada/USA) on the PSTN
Essential
codec_a_mu
A-law to mu-law direct converter
Useful
codec_dahdi
Utilizes proprietary Digium hardware transcoding card
Essentiala
codec_g722
Wideband audio codec
Useful
codec_g726
Flavor of ADPCM
Insignificant
codec_gsm
Global System for Mobile Communications (GSM) codec
Useful
codec_ilbc
Internet Low Bitrate Codec
Insignificant
codec_lpc10
Linear Predictive Coding vocoder (extremely low bandwidth)
Insignificant
codec_resample
Resamples between 8-bit and 16-bit signed linear
Usable
codec_speex
Speex codec
Usable
codec_ulaw
Mu-law PCM codec used in Canada/USA on PSTN
Essential
If you are using a Digium codec transcoder card.
Format Interpreters Format interpreters (Table 2-7) perform the function of codec translators, but they do their work on files rather than channels. If you have a recording on a menu that has been stored as GSM, a format interpreter would need to be used to play that recording to any channels not using the GSM codec.‡
† More information about what codecs are and how they work is available in “Codecs” on page 625. ‡ It is partly for this reason that we do not recommend the default GSM format for system recordings. WAV recordings will sound better and use less CPU.
18 Chapter 2: Asterisk Architecture
If you store a recording in several formats (such as WAV, GSM, etc.), Asterisk will determine the least costly format§ to use when a channel requires that recording. Table 2-7. Format interpreters Name
Plays files stored in
Popularity/Status
format_g723
G.723 .g723
Insignificant
format_g726
G.726 .g726
Insignificant
format_g729
G.729 .g729
Useful
format_gsm
RPE-LTP (original GSM codec) .gsm
Usable
format_h263
H.263—video h263
Usable
format_h264
H.264—video h264
Usable
format_ilbc
Internet Low Bitrate Codec .ilbc
Insignificant
format_jpeg
Graphic file .jpeg .jpg
Insignificant
format_ogg_vorbis
Ogg container .ogg
Usable
format_pcm
Various Pulse-Coded Modulation formats: .alaw, .al, .alw, .pcm, .ulaw, .ul, .mu, .ulw, .g722, .au
Useful
format_siren14
G.722.1 Annex C (14 kHz) siren14
New
format_siren7
G.722.1 (7 kHz) siren7
New
format_sln16
16-bit signed linear .sln16
New
format_sln
8-bit signed linear sln .raw
Useful
format_vox
.vox
Insignificant
format_wav
.wav
Useful
format_wav_gsm
GSM audio in a WAV container .WAV, .wav49
Usable
Dialplan Functions Dialplan functions, listed in Table 2-8, complement the dialplan applications (see “Applications” on page 12). They provide many useful enhancements to things like string handling, time and date wrangling, and ODBC connectivity. Table 2-8. Dialplan functions Name
Purpose
Popularity/Status
func_aes
Encrypts/decrypts an AES string
Useful
func_audiohookinherit
Allows calls to be recorded after transfer
Useful
func_base64
Encodes/decodes a base-64 string
Usable
func_blacklist
Writes/reads blacklist in astdb
Useful
§ Some codecs can impose a significant load on the CPU, such that a system that could support several hundred channels without transcoding might only be able to handle a few dozen when transcoding is in use.
Modules 19
Name
Purpose
Popularity/Status
func_callcompletion
Gets/sets call completion configuration parameters for the channel
New
func_callerid
Gets/sets CallerID
Useful
func_cdr
Gets/sets CDR variable
Useful
func_channel
Gets/sets channel information
Useful
func_config
Includes AST_CONFIG(); reads variables from config file
Usable
func_connectedline
Changes connected line information on supported handsets
New
func_curl
Uses cURL to obtain data from a URI
Useful
func_cut
Slices and dices strings
Useful
func_db
Provides astdb functions
Useful
func_devstate
Gets state of device
Useful
func_dialgroup
Creates a group for simultaneous dialing
Useful
func_dialplan
Validates that designated target exists in dialplan
Useful
func_enum
Performs ENUM lookup
Useful
func_env
Includes FILE(), STAT(), and ENV(); performs operating system actions
Useful
func_extstate
Returns status of a hinted extension
Useful
func_global
Gets/sets global variables
Useful
func_groupcount
Gets/sets channel count for members of a group
Useful
func_iconv
Converts between character sets
Usable
func_lock
Includes LOCK(), UNLOCK(), and TRYLOCK(); sets a lock that can be used to avoid race conditions in the dialplan
Useful
func_logic
Includes ISNULL(), SET(), EXISTS(), IF(), IFTIME(), and IMPORT(); performs various logical functions
Useful
func_math
Includes MATH(), INC(), and DEC(); performs mathematical functions
Useful
func_md5
Converts supplied string to an MD5 hash
Useful
func_module
Checks to see if supplied module is loaded into memory
Usable
func_odbc
Allows dialplan integration with ODBC resources
Useful
func_pitchshift
Shifts the pitch of an audio stream
Useful
func_rand
Returns a random number within a given range
Useful
func_realtime
Performs lookups within the Asterisk Realtime Architecture (ARA)
Useful
func_redirecting
Provides access to information about where this call was redirected from
Useful
func_sha1
Converts supplied string to an SHA1 hash
Useful
func_shell
Performs Linux shell operations and returns results
Useful
func_speex
Reduces noise and performs dB gain/loss on an audio stream
Useful
20 Chapter 2: Asterisk Architecture
Name
Purpose
Popularity/Status
func_sprintf
Performs string format functions similar to C function of same name
Useful
func_srv
Perform SRV lookups in the dialplan
Useful
func_strings
Includes over a dozen string manipulation functions
Useful
func_sysinfo
Gets system information such as RAM, swap, load average, etc.
Useful
func_timeout
Gets/sets timeouts on channel
Useful
func_uri
Converts strings to URI-safe encoding
Useful
func_version
Returns Asterisk version information
Usable
func_vmcount
Returns count of messages in a voicemail folder for a particular user
Useful
func_volume
Sets volume on a channel
Useful
PBX Modules The PBX modules are peripheral modules that provide enhanced control and configuration mechanisms. For example, pbx_config is the module that loads the traditional Asterisk dialplan. The currently available PBX modules are listed in Table 2-9. Table 2-9. PBX modules
a b
Name
Purpose
Popularity/Status
pbx_ael
Asterisk Extension Logic (AEL) offers a dialplan scripting language that looks like a modern programming language.
Usablea
pbx_config
This is the traditional, and most popular, dialplan language for Asterisk. Without this module, Asterisk cannot read extensions.conf.
Useful
pbx_dundi
Performs data lookups on remote Asterisk systems.
Useful
pbx_loopback
Performs something similar to a dialplan include, but in a deprecated manner.
Insignificantb
pbx_lua
Allows creation of a dialplan using the Lua scripting language.
Useful
pbx_realtime
Provides functionality related to the Asterisk Realtime Architecture.
Useful
pbx_spool
Provides outgoing spool support relating to Asterisk call files.
Useful
We have not found too many people using AEL. We suspect this is because most developers will tend to use AGI/AMI if they do not want to use traditional dialplans. We’ve never heard of this being used in production.
Resource Modules Resource modules integrate Asterisk with external resources. For example, res_odbc allows Asterisk to interoperate with ODBC database connections. The currently available resource modules are listed in Table 2-10.
Modules 21
Table 2-10. Resource modules Name
Purpose
Popularity/Status
res_adsi
Provides ADSI
Essentiala
res_ael_share
Provides shared routines for use with pbx_ael
Essential if you’re using AEL
res_agi
Provides Asterisk Gateway Interface
Useful
res_ais
Provides distributed message waiting indication (MWI) and device state notifications via an implementation of the AIS standard, such as OpenAIS
Useful
res_calendar
Enables base integration to calendaring systems
Useful
res_calendar_caldav
Provides CalDAV-specific capabilities
Useful
res_calendar_exchange
Provides MS Exchange capabilities
Useful
res_calendar_icalendar
Provides Apple/Google iCalendar capabilities
Useful
res_clialiases
Creates CLI aliases
Useful
res_clioriginate
Originates a call from the CLI
Usable
res_config_curl
Pulls configuration information using cURL
Useful
res_config_ldap
Pulls configuration information using LDAP
Usable
res_config_odbc
Pulls configuration information using ODBC
Useful
res_config_pgsql
Pulls configuration information using PostgreSQL
Usable
res_config_sqlite
Pulls configuration information using SQLite
Usable
res_convert
Uses the CLI to perform file conversions
Usable
res_crypto
Provides cryptographic capabilities
Useful
res_curl
Provides common subroutines for other cURL modules
Useful
res_fax
Provides common subroutines for other fax modules
Useful
res_fax_spandsp
Plug-in for fax using the spandsp package
Useful
res_http_post
Provides POST upload support for the Asterisk HTTP server
Usable
res_jabber
Provides Jabber/XMPP resources
Useful
res_limit
Enables adjusting of system limits on the Asterisk process
Usable
res_monitor
Provides call recording resources
Useful
res_musiconhold
Provides music on hold (MOH) resources
Essential
res_mutestream
Allows muting/unmuting of audio streams
New
res_odbc
Provides common subroutines for other ODBC modules
Useful
res_phoneprov
Provisions phones from Asterisk HTTP server
New
res_pktccops
Provides PacketCable COPS resources
New
res_realtime
Provides CLI commands for the Asterisk Realtime Architecture (ARA)
Useful
res_rtp_asterisk
Provides RTP
Essential
res_rtp_multicast
Provides multicast-RTP
New
22 Chapter 2: Asterisk Architecture
a b
Name
Purpose
Popularity/Status
res_security_log
Enables security logging
New
res_smdi
Provides voicemail notification using the SMDI protocol
Limited
res_snmp
Provides system status information to an SNMP-managed network
Usable
res_speech
Generic speech recognition API
Limitedb
res_timing_dahdi
Provides timing using the DAHDI kernel interface
Useful
res_timing_kqueue
Provides timing using a kernel feature in some BSDs, including Mac OS X
New
res_timing_pthread
Provides timing using only parts of the standard pthread API; less efficient but more portable than other timing modules.
Useful
res_timing_timerfd
Provides timing using the timerfd API provided by newer versions of the Linux kernel
Useful
While most of the ADSI functionality in Asterisk is never used, the voicemail application uses this resource. Requires a separately licensed product in order to be used.
Addon Modules Addon modules are community-developed modules with different usage or distribution rights from those of the main code. They are kept in a separate directory and are not compiled and installed by default. To enable these modules, use the menuselect build configuration utility. Currently available addon modules are listed in Table 2-11. Table 2-11. Addon modules
a
Name
Purpose
Popularity/Status
app_mysql
Executes MySQL queries with a dialplan application
Deprecated—see func_odbc
app_saycountpl
Says Polish counting words
Deprecated—now integrated in say.conf
cdr_mysql
Logs call detail records to a MySQL database
Usable—we recommend cdr_adaptive_odbc instead
chan_mobile
Enables making and receiving phone calls using cell phones over Bluetooth
Limiteda
chan_ooh323
Enables making and receiving VoIP calls using the H.323 protocol
Usable
format_mp3
Allows Asterisk to play MP3 files
Usable
res_config_mysql
Uses a MySQL database as a realtime configuration backend
Useful
While chan_mobile works great with many phones, problems have been reported with some models. When a problem does occur, it is very difficult for developers to solve unless they have a phone of the same model to test with.
Modules 23
Test Modules Test modules are used by the Asterisk development team to validate new code. They are constantly changing and being added to, and are not useful unless you are developing Asterisk software. If you are an Asterisk developer, however, the Asterisk Test Suite may be of interest to you as you can build automated tests for Asterisk and submit those back to the project, which runs on several different operating systems and types of machines. By expanding the number of tests constantly, the Asterisk project avoids the creation of regressions in code. By submitting your own tests to the project, you can feel more confident in future upgrades. More information about installing the Asterisk Test Suite is available in this blog post: http://blogs.asterisk.org/2010/04/29/installing-the-asterisk-test-suite/. More information about building tests is available in this document: http://svn.asterisk.org/svn/test suite/asterisk/trunk/README.txt or you can join the #asterisk-testing channel on the Freenode IRC network.
File Structure Asterisk is a complex system, composed of many resources. These resources make use of the filesystem in several ways. Since Linux is so flexible in this regard, it is helpful to understand what data is being stored, so that you can understand where you are likely to find a particular bit of stored data (such as voicemail messages or log files).
Configuration Files The Asterisk configuration files include extensions.conf, sip.conf, modules.conf, and dozens of other files that define parameters for the various channels, resources, modules, and functions that may be in use. These files will be found in /etc/asterisk. You will be working in this folder a lot as you configure and administer your Asterisk system.
Modules Asterisk modules are usually installed to the /usr/lib/asterisk/modules folder. You will not normally have to interact with this folder; however, it will be occasionally useful to know where the modules are located. For example, if you upgrade Asterisk and select different modules during the menuselect phase of the install, the old (incompatible) modules from the previous Asterisk version will not be deleted, and you will get a warning from the install script. Those old files will need to be deleted from the modules folder. This can be done either manually or with the “uninstall” make (make uninstall) target.
24 Chapter 2: Asterisk Architecture
The Resource Library There are several resources that require external data sources. For example, music on hold (MOH) can’t happen unless you have some music to play. System prompts also need to be stored somewhere on the hard drive. The /var/lib/asterisk folder is where system prompts, AGI scripts, music on hold, and other resource files are stored.
The Spool The spool is where Linux stores files that are going to change frequently, or will be processed by other processes at a later time. For example, under Linux print jobs and pending emails are normally written to the spool until they are processed. For Asterisk, the spool is used to store transient items such as voice messages, call recordings,‖ call files, and so forth. The Asterisk spool will be found under the /var/spool/asterisk directory.
Logging Asterisk is capable of generating several different kinds of log files. The /var/log/asterisk folder is where things such as call detail records (CDRs), channel events from CEL, debug logs, queue logs, messages, errors, and other output are written. This folder will be extremely important for any troubleshooting efforts you undertake. We will talk more about how to make use of Asterisk logs in Chapter 24.
The Dialplan The dialplan is the heart of Asterisk. All channels that arrive in the system will be passed through the dialplan, which contains the call-flow script that determines how the incoming calls are handled. A dialplan can be written in one of three ways: • Using traditional Asterisk dialplan syntax in /etc/asterisk/extensions.conf • Using asterisk Extension Logic (AEL) in /etc/asterisk/extensions.ael • Using LUA in /etc/asterisk/extensions.lua Later in this book, we’ll have devoted several chapters to the subject of how to write a dialplan using traditional dialplan syntax (by far the most popular choice). Once you learn this language, it should be fairly easy to transition to AEL or LUA, should you desire.
‖ Not call detail records (CDRs), but rather audio recordings of calls generated by the MixMonitor() and related applications.
The Dialplan 25
Hardware Asterisk is capable of communicating with a vast number of different technologies. In general, these connections are made across a network connection; however, connections to more traditional telecom technologies, such as the PSTN, require specific hardware. Many companies produce this hardware, such as Digium (the sponsor, owner, and primary developer of Asterisk), Sangoma, Rhino, OpenVox, Pika, Voicetronix, Junghanns, Dialogic, Xorcom, beroNet, and many others. The authors prefer cards from Digium and Sangoma; however, the products offered by other Asterisk hardware manufacturers may be more suitable to your requirements. The most popular hardware for Asterisk is generally designed to work through the Digium Asterisk Hardware Device Interface (known as DAHDI). These cards will all have different installation requirements and different file locations. In Chapter 7, we will discuss DAHDI in more detail; however, we will limit our discussion to DAHDI only. You will need to refer to the specific documentation provided by the manufacturers of any cards you install for details on those cards.
Asterisk Versioning The Asterisk release methodology has gone through a couple of iterations over the last few years, and this section is designed to help you understand what the version numbers mean. Of particular relevance is the change in versioning that happened with the 1.6.x series of releases, which followed a different numbering logic than all other Asterisk releases (1.0 to 1.8 and onward for the foreseeable future).
Previous Release Methodologies When we had just Asterisk 1.2 and 1.4, all new development was carried out in trunk (it still is), and only bug fixes went into the 1.2 and 1.4 branches. The Asterisk 1.2 branch has been marked as EOL (End of Life), and is no longer receiving bug fixes or security updates. Prior to the 1.6.x branches, bug fixes were carried out only in trunk and in the 1.4 branch. Because all new development was done in trunk, until the 1.6 branch was created people were unable to get access to the new features and functionality. This isn’t to say the new functionality wasn’t available, but with all the changes that can happen in trunk, running a production server based on it requires a very Asterisk-savvy (and C code– savvy) administrator. To try to relieve the pressure on administrators, and to enable faster access to new features (in the time frame of months, and not years), a new methodology was created. Branches in 1.6 would actually be marked as 1.6.0, 1.6.1, 1.6.2, etc., with the third 26 Chapter 2: Asterisk Architecture
number increasing by one each time a new feature release was created. The goal was to provide new feature releases every 3–4 months (which would be branched from trunk), providing a shorter and clearer upgrade path for administrators. If you needed a new feature, you’d only have to wait a few months and could then upgrade to the next branch. Tags from these branches look like this: • 1.6.0.1 -- 1.6.0.2 -- 1.6.0.3 -- 1.6.0.4 -- etc. • 1.6.1.1 -- 1.6.1.2 -- 1.6.1.3 -- 1.6.1.4 -- etc. • 1.6.2.1 -- 1.6.2.2 -- 1.6.2.3 -- 1.6.2.4 -- etc. Figure 2-2 gives a visual representation of the branching and tagging process in relation to Asterisk trunk.
Figure 2-2. The Asterisk 1.6.x release process
So, so far we have branches, which are 1.2, 1.4, 1.6.0, 1.6.1, and 1.6.2 (there is no 1.6 branch). Within each of those branches, we create tags (releases), which look like 1.2.14, 1.4.30, 1.6.0.12, 1.6.1.12, and 1.6.2.15. Unfortunately, it ended up not working out that 1.6.x branches were created from trunk every 3–4 months: the development process has led to a minimum release time of 6–8 months. Not only that, but the 1.6.x numbering methodology adds problems of its own. People got confused as to what version to run, and that the 1.6.0, 1.6.1, and 1.6.2 branches were all separate major version upgrades. When you increase the number from 1.2 to 1.4, and then to 1.8, it is obvious that those are distinct branches and major version changes. With 1.6.0, 1.6.1, and 1.6.2, it is less obvious.
The New Release Methodology The development team learned a lot of things during the 1.6.x releases. The idea surrounding the releases was noble, but the implementation ended up being flawed when put into real use. So, with Asterisk 1.8, the methodology has changed again, and will look a lot more like that used in the 1.2 and 1.4 releases. Asterisk Versioning 27
While the development team still wants to provide access to new features and core changes on a more regular basis (every 12 months being the goal), there is recognition that it is also good to provide long-term support to a stable, popular version of Asterisk. You can think of the Asterisk 1.4 branch as being a long-term support (LTS) version. The 1.6.0, 1.6.1, and 1.6.2 branches can be thought of as feature releases that continue to receive bug fixes after release, but are supported for a shorter period of time (about a year). The new LTS version is Asterisk 1.8 (what this book is based on); it will receive bug fixes for four years and an additional year of security releases after that, providing five years of support from the Digium development team. During the long-term support phase of Asterisk 1.8, additional branches will be created on a semi-regular basis as feature releases. These will be tagged as versions 1.10, 1.12, and 1.14, respectively. Each of these branches will receive bug fixes for a period of one year, and security releases will continue to be made for an additional year before the branches are marked as EOL. The current statuses of all Asterisk branches, their release dates, when they will go into security release–only mode, and when they will reach EOL status are all documented on the Asterisk wiki at https://wiki.asterisk.org/wiki/display/AST/Asterisk+Versions.
Conclusion Asterisk is composed of many different technologies, most of which are complicated in their own right. As such, the understanding of Asterisk architecture can be overwhelming. Still, the reality is that Asterisk is well-designed for what it does and, in our opinion, has achieved remarkable balance between flexibility and complexity.
28 Chapter 2: Asterisk Architecture
CHAPTER 3
Installing Asterisk
I long to accomplish great and noble tasks, but it is my chief duty to accomplish humble tasks as though they were great and noble. The world is moved along, not only by the mighty shoves of its heroes, but also by the aggregate of the tiny pushes of each honest worker. —Helen Keller
In this chapter we’re going to walk through the installation of Asterisk from the source code. Many people shy away from this method, claiming that it is too difficult and timeconsuming. Our goal here is to demonstrate that installing Asterisk from source is not actually that difficult to do. More importantly, we want to provide you with the best Asterisk platform on which to learn. In this book we will be helping you build a functioning Asterisk system from scratch. In this chapter you will build a base platform for your Asterisk system. Given that we are installing from source, there is potentially a lot of variation in how you can do this. The process we discuss here is one that we’ve used for many years, and following it will provide you with a suitable foundation for Asterisk. As part of this process we will also explain installation of some of the software dependencies on the Linux platform that will be needed for topics covered later in this book (such as database integration). We will show instructions for installing Asterisk on both CentOS (a Red Hat–based distribution) and Ubuntu (a Debian-based distribution), which we believe covers the vast majority of Linux distributions being installed today. We’ll try to keep the instructions general enough that they should be useful on any distribution of your choice.*
* If you are using another distribution, we’re willing to bet you are quite comfortable with Linux and should have no trouble installing Asterisk.
29
We have chosen to install on CentOS and Ubuntu because they are the most popular options, but Asterisk is generally distribution-agnostic. Asterisk will even install on Solaris, BSD, or OS X† if you like. We won’t be covering them in this book, though, as Asterisk is most heavily developed on the Linux platform.
Asterisk Packages There are also packages that exist for Asterisk that can be installed using popular package-management programs such as yum or apt-get. You are welcome to experiment with them. Prebuilt packages may not always be kept up-to-date, though, so for the latest version we always recommend installing from source. You can find package instructions at http://www.asterisk.org/downloads/yum.
Some commands you see in this chapter will be split into separate rows, each labeled for the distribution on which the command should be performed. Commands for which distributions are not specified are for common commands that can be run on both distributions.
Asterisk-Based Projects Many projects have been created that use Asterisk as their underlying platform. Some of these, such as Trixbox, have become so popular that many people mistake them for the Asterisk product itself. These projects generally will take the base Asterisk product and add a web-based administration interface, a complex database, and a rigid set of constraints on how changes can be made to the configuration. We have chosen not to cover these projects in this book, for several reasons: 1. This book tries, as much as possible, to focus on Asterisk and only Asterisk. 2. Books have already been written about some of these Asterisk-based projects. 3. We believe that if you learn Asterisk in the way that we will teach you, the knowledge will serve you well, regardless of whether you eventually choose to use one of these prepackaged versions of Asterisk. 4. For us, the power of Asterisk is that it does not attempt to solve your problems for you. These projects are an excellent example of what can be built with Asterisk. They are truly amazing. However, if you are looking to build your own Asterisk application (which is really what Asterisk is all about), these projects will impose limitations on you, because they are focused on simplifying the process of building a business PBX, not on making it easier to access the full potential of the Asterisk platform. † Leif calls this “Oh-Eh-Sex,” but Jim thinks it should be pronounced “OS Ten.” We wasted several precious minutes arguing about this.
30 Chapter 3: Installing Asterisk
Some of the most popular Asterisk-based projects include: AsteriskNOW
http //www.asterisk.org/asterisknow
Trixbox
http //www.trixbox.org
Elastix
http //www.elastix.org
PBX in a Flash
http //www.pbxinaflash.net
We recommend that you check them out.‡
Installation Cheat Sheet If you just want the nitty-gritty on how to get Asterisk up and running quickly, perform the following at the shell prompt. We encourage you to read through the entire chapter at least once, though, in order to better understand the full process.§ The instructions provided here assume you’ve already installed either CentOS or Ubuntu using the steps outlined in “Distribution Installation” on page 35. Remember that Ubuntu requires commands to be prefixed with sudo.
1. Perform a system update and reboot: CentOS
yum update -y && reboot
CentOS 64-bit
yum remove *.i386 && yum update -y && reboot
Ubuntu
sudo apt-get update && sudo apt-get upgrade && sudo reboot
2. Synchronize time and install the NTP (Network Time Protocol) daemon: CentOS
yum install -y ntp && ntpdate pool.ntp.org && chkconfig ntpd on && service ntpd start
CentOS 64-bit
yum install -y ntp && ntpdate pool.ntp.org && chkconfig ntpd on && service ntpd start
Ubuntu
sudo apt-get install ntp
‡ After you read our book, of course. § Once you have experience with several Asterisk installations, you’ll agree that it’s a quick and painless process. Nevertheless, this chapter may make the process look complex. This is simply because we have an obligation to ensure you are provided with all the information you need to accomplish a successful install.
Installation Cheat Sheet 31
Some additional configuration of text files is required on Ubuntu. See “Enable NTP for accurate system time” on page 43.
3. On CentOS, add a new system user: CentOS (32 and 64 bit)
adduser asteriskpbx && passwd asteriskpbx && yum install sudo && visudo
See “Adding a system user” on page 39 for specific information.
For an Ubuntu install, we are assuming that the user created during the installation process is asteriskpbx.
4. Install software dependencies: CentOS
sudo yum install gcc gcc-c++ make wget subversion libxml2-devel ncurses-devel openssl-devel vim-enhanced
CentOS 64-bit
sudo yum install gcc.x86_64 gcc-c++.x86_64 make.x86_64 wget.x86_64 subversion.x86_64 libxml2-devel.x86_64 ncurses-devel.x86_64 openssl-devel.x86_64 vim-enhanced.x86_64
Ubuntu
sudo apt-get install build-essential subversion libncurses5-dev libssl-dev libxml2-dev vim-nox
5. Create your directory structure: $ mkdir -p ~/src/asterisk-complete/asterisk $ cd ~/src/asterisk-complete/asterisk
6. Get the latest source code via Subversion: $ svn co http://svn.asterisk.org/svn/asterisk/branches/1.8
Or alternatively, you could check out a specific tag: $ svn co http://svn.asterisk.org/svn/asterisk/tags/1.8.1
7. Build and install the software: $ cd ~/src/asterisk-complete/asterisk/1.8/ $ ./configure
32 Chapter 3: Installing Asterisk
$ make $ sudo make install $ sudo make config
8. Install additional sound prompts from menuselect: $ cd ~/src/asterisk-complete/asterisk/1.8/ $ make menuselect $ sudo make install
9. Modify the file permissions of the directories Asterisk was installed to: $ $ $ $ $ $
sudo sudo sudo sudo sudo sudo
chown chown chown chown chown chown
-R asteriskpbx:asteriskpbx /usr/lib/asterisk/ -R asteriskpbx:asteriskpbx /var/lib/asterisk/ -R asteriskpbx:asteriskpbx /var/spool/asterisk/ -R asteriskpbx:asteriskpbx /var/log/asterisk/ -R asteriskpbx:asteriskpbx /var/run/asterisk/ asteriskpbx:asteriskpbx /usr/sbin/asterisk
10. On CentOS, disable SELinux: $ sudo vim /etc/selinux/config
Change the value of SELINUX from enforcing to disabled, then reboot. 11. Create the /etc/asterisk/ directory and copy the indications.conf sample file into it: $ sudo mkdir -p /etc/asterisk $ sudo chown asteriskpbx:asteriskpbx /etc/asterisk $ cd /etc/asterisk/ $ cp ~/src/asterisk-complete/asterisk/1.8/configs/indications.conf.sample ./indications.conf
12. Copy the sample asterisk.conf file into /etc/asterisk and change runuser and run group to have values of asteriskpbx: $ cp ~/src/asterisk-complete/asterisk/1.8/configs/asterisk.conf.sample /etc/asterisk/asterisk.conf $ vim /etc/asterisk/asterisk.conf
See “indications.conf and asterisk.conf” on page 53 for more information. 13. Create the modules.conf file. Enable loading of modules automatically, and disable extra modules: $ cat >> /etc/asterisk/modules.conf ; The modules.conf file, used to define which modules Asterisk should load (or ; not load). ; [modules] autoload=yes ; Resource modules currently not needed noload => res_speech.so noload => res_phoneprov.so noload => res_ael_share.so noload => res_clialiases.so noload => res_adsi.so
Installation Cheat Sheet 33
; PBX modules currently not needed noload => pbx_ael.so noload => pbx_dundi.so ; Channel noload => noload => noload => noload => noload => noload => noload =>
modules currently not needed chan_oss.so chan_mgcp.so chan_skinny.so chan_phone.so chan_agent.so chan_unistim.so chan_alsa.so
; Application modules currently not needed noload => app_nbscat.so noload => app_amd.so noload => app_minivm.so noload => app_zapateller.so noload => app_ices.so noload => app_sendtext.so noload => app_speech_utils.so noload => app_mp3.so noload => app_flash.so noload => app_getcpeid.so noload => app_setcallerid.so noload => app_adsiprog.so noload => app_forkcdr.so noload => app_sms.so noload => app_morsecode.so noload => app_followme.so noload => app_url.so noload => app_alarmreceiver.so noload => app_disa.so noload => app_dahdiras.so noload => app_senddtmf.so noload => app_sayunixtime.so noload => app_test.so noload => app_externalivr.so noload => app_image.so noload => app_dictate.so noload => app_festival.so Ctrl + D
14. Configure musiconhold.conf: $ cat >> musiconhold.conf ; musiconhold.conf [default] mode=files directory=moh Ctrl + D
34 Chapter 3: Installing Asterisk
15. Save your changes and your module configuration is done. Your system is ready to configure your dialplan and channels.
Distribution Installation Because Asterisk relies so heavily on having priority access to the CPU, it is essential that you install Asterisk onto a server without any graphical interface, such as the X Windowing system (Gnome, KDE, etc.). Both CentOS and Ubuntu ship a GUI-free distribution designed for server usage. We will cover instructions for both distributions.
CentOS Server CentOS means “Community Enterprise Operating System,” and it is based on Red Hat Enterprise Linux (RHEL). For more information about what CentOS is and its history, see http://www.centos.org. You will need to download an ISO from the CentOS website, located at http://mirror .centos.org/centos/5/isos/. Select either the i386 or x86_64 directory for 32-bit or 64-bit hardware, respectively. You will then be presented with a list of mirrors that appear to be close to you physically. Choose one of the mirrors, and you will be presented with a list of files to download. Likely you will want the first available selection, which is the first ISO file of a set. You will only need the first ISO file of the set as we’ll be installing additional software with yum. Once you’ve downloaded the ISO file, burn it to a CD or DVD and start the installation process. If you’re installing into a virtual machine (which we don’t recommend for production use,‖ but can be a great way to test out Asterisk), you should be able to mount the ISO file directly and install from there.
Base system installation Upon booting from the CD, type linux text and then press Enter .# At this point the text installation interface will start. You will be asked whether you want to test the media. These instructions assume you’ve already done so, and therefore can skip that step. CentOS will then welcome you to the installation. Press Enter to continue.
‖ Actually, some people have great success running Asterisk inside virtual machines. It does depend what you’re planning on using it for though, as you’ll have limited access to hardware, for example. #You should test the media the first time you are using that particular CD/DVD.
Distribution Installation 35
Choose your language and make a keyboard selection.* If you’re in North America, you will probably just select the defaults. If you’ve previously formatted your hard drive, you will be asked to initialize the drive, which will erase all data. Select Yes . The installer will ask if you want to remove the existing partitioning scheme and create a new one. Select Remove all partitions on selected drives and create default layout. If a more appropriate option exists, select that instead. In the drive window, verify that the correct disk drive is selected. (Pressing Tab will cycle through the selections on the screen.) Once the drive window is selected, you can scroll up and down (presuming you have multiple drives) and select which hard drive you wish to install to. Toggle the selections by pressing space bar . Verify that the correct drive is selected, press Tab until the OK button is highlighted, and press Enter . A message confirming that you want to remove all Linux partitions and create the new partition scheme will be presented. Select Yes . You will be asked to review the partitioning layout. Feel free to modify the partition scheme if you prefer something different (see the following sidebar for some advice on this); however, the default answer No is fine for light production use where storage requirements will be low.†
Separating the /var Mount Point to Its Own Partition On a system dedicated to Asterisk, the directory with the largest storage requirement is /var. This is where Asterisk will store recordings, voicemails, log files, prompts, and a myriad of constantly growing information. In normal operation, it is unlikely that Asterisk will fill the hard disk. However, if you have extensive logging turned on or are recording all calls, this could, in theory, occur. (This is likely to happen several months after you’ve completed the install and to take your entire staff by surprise.) If the drive the operating system is mounted on fills up, there is the potential for a kernel panic. By separating /var from the rest of the hard drive, you significantly lower the risk of a system failure. Having a full volume is still a major problem; however, you will at least be able to log into the system to rectify the situation.
* Bear in mind that Asterisk is developed using the US keyboard and language, and we’re not aware of any testing having been done on anything other than US English. † Due to the ever-increasing size of hard drives, capacity is becoming less of a problem. A system with a 1 terabyte drive can store somewhere in the range of 2 million minutes of telephony-quality recordings.
36 Chapter 3: Installing Asterisk
At the Review and modify the partitioning layout screen, you can create a separate volume for /var. Selecting Yes will bring up the Partitioning tool. To partition the drive accurately, you need to know what the hard drive size is; this may not jibe with what is stamped on the outside of the drive because you have to tell the tool how to chop up the drive. A limitation of the tool is that there is no option to say “use all available space”; that is, you can’t simply could use 500 MB on the / partition and then say “use the rest for /var”. The workaround is to make a note of the size it has selected for / currently, as that is the full space, subtract 500 MB from that, and make that the size for the / partition. The subtracted amount will then be reserved for /var.
A message will appear asking if you’d like to configure the eth0 network interface on your system. Select Yes . Be sure the Activate on boot and Enable IPv4 support options are enabled, then select OK . If your network provides automatic IP provisioning via DHCP, you can just select OK . Otherwise, select Manual address configuration, enter the appropriate information, and then select OK . Next, you’ll be asked to provide a hostname. You can either allow the DHCP server to provide one for you (if your network assigns hostnames automatically) or enter one manually, then select OK . You will be presented with a list of time zones. Highlight your local time zone and select OK . At this point, you will be asked for a root password. Enter a secure password and type it again to confirm. After entering your secure password, select OK . Next up will be the package selection. Several packages that you don’t need to install (and that require additional ISO files you probably haven’t downloaded) are selected by default. Deselect all options in the list using the space bar, then select the Customize software selection option. Once you’ve done that, select OK . You will then be presented with the Package Group Selection screen. Scroll through the whole list, deselecting each item. If any packages are selected, you’ll be prompted for additional CDs that you have not downloaded. We’ll be installing additional packages with the yum application after the operating system is installed. Once you’ve deselected all packages, select OK . A dependency check will then be performed and a confirmation that installation is ready to begin will be presented. Select OK to start the installation. The filesystem will then be formatted, the installation image transferred to the hard drive, and installation of the system packages performed. Upon installation, you will be asked to reboot. Remove any media in the drives and select the Reboot button.
Distribution Installation 37
Base system update Once you’ve rebooted your system, you need to run the yum update command to make sure you have the latest base packages. To do this, log in using the username root and the password you created during installation. Once logged in, run the following: # yum update Is this ok [y/N]: y
When prompted to install the latest packages, press y and wait for the packages to update. If you’re asked to accept a GPG key, press y . When complete, reboot the system as it is likely the kernel will have been updated‡: # reboot
If you’re running CentOS Server 64-bit, you’ll need to remove all the 32-bit libraries manually. Once you’ve rebooted, or just prior to reboot, run the following command: # yum remove *.i386 -y
This will remove all the 32-bit libraries on your 64-bit system, which can otherwise cause conflicts and issues when compiling Asterisk and other software.
Congratulations! You’ve successfully installed and updated the base CentOS system.
Enabling NTP for accurate system time Keeping accurate time is essential on your Asterisk system, both for maintaining accurate call detail records and for synchronization with your other programs. You don’t want the times of your voicemail notifications to be off by 10 or 20 minutes, as this can lead to confusion and panic from those who might think their voicemail notifications are taking took too long to be delivered. The ntpd command can be used to ensure that the time on your Asterisk server remains in sync with the rest of the world: # yum install ntp .. Is this ok [y/N]: y .. # ntpdate pool.ntp.org # chkconfig ntpd on # service ntpd start
The defaults shipped with CentOS are sufficient to synchronize the time and keep the machine’s time in sync with the rest of the world.
‡ This reboot step is essential prior to installing Asterisk.
38 Chapter 3: Installing Asterisk
Adding a system user The Ubuntu server install process asks you to add a system user other than root, but CentOS does not. In order to be consistent in the book and to be more secure, we’re going to add another system user and provide it sudo access.§ To add the new user, execute the adduser command: # adduser asteriskpbx # passwd asteriskpbx Changing password for user asteriskpbx. New UNIX password: Retype new UNIX password:
Now we need to provide the asteriskpbx user sudo access. We do this by modifying the sudoers file with the visudo command. You’ll need to install visudo the first time you use it: # yum install sudo
With the sudo-related applications and file installed, we can modify the sudoers file. Execute the visudo command and look for the lines shown below: # visudo ## Allows people in group wheel to run all commands %wheel ALL=(ALL) ALL
With the %wheel line uncommented as shown in our example, save the file by pressing Esc , then typing :wq and pressing Enter . Now open the /etc/group file in your favorite editor (nano is easy to use) and find the line that starts with the word wheel. Modify it like so: wheel:x:10:root,asteriskpbx
Save the file, log out from root by typing exit, and log in as the asteriskpbx user you created. Test your sudo access by running the following command: $ sudo ls /root/ [sudo] password for asteriskpbx:
After typing your password, you should get the output of the /root/ directory. If you don’t, go back and verify the steps to make sure you didn’t skip or mistype anything. The rest of the instructions in this chapter will assume that you’re the asteriskpbx user and that you have sudo access. One last thing needs to done, which will allow you to enter commands without having to enter the full path. By default only root has /sbin/ and /usr/sbin/ in the default system PATH, but we’ll add it to our asteriskpbx user as well since we’ll be running many applications located in those directories.
§ sudo is an application that allows a user to execute commands as another user, such as root, or the superuser.
Distribution Installation 39
Start by opening the hidden file .bash_profile located within the asteriskpbx home directory with an editor. We’re then going to append :/usr/sbin:/sbin to the end of the line starting with PATH: $ vim ~/.bash_profile PATH=$PATH:$HOME/bin:/usr/sbin:/sbin
As previously, save the file by pressing Esc and then typing :wq and pressing Enter . With the operating system installed, you’re ready to install the dependencies required for Asterisk. The next section deals with Ubuntu, so you can skip ahead to the section “Software Dependencies” on page 44, which provides an in-depth review of the installation process. Alternatively, if you’ve already reviewed the information in that section, you may want to refer back to the “Installation Cheat Sheet” on page 31 for a high-level review of how to install Asterisk.
Ubuntu Server Ubuntu Server is a popular Linux distribution loosely based on Debian. There is also a popular desktop version of the software. The Ubuntu Server package contains no GUI and is ideal for Asterisk installations. To get the latest version of Ubuntu Server,‖ visit http://www.ubuntu.com and select the Server tab at the top of the page. You will be provided with a page that contains information about Ubuntu Server Edition. Clicking the orange Download button in the upper-right corner will take you to a page where you can select either the 32-bit or 64bit version of Ubuntu Server. After selecting one of the options, you can press the Start download button. Once you’ve downloaded the ISO file, burn it to a CD and start the installation process. If you’re installing into a virtual machine (which we don’t recommend for production use, but can be a great way to test out Asterisk), you should be able to mount the ISO file directly and install from there.
Base system installation Upon booting from the CD, you will be presented with a screen where you can select your language of choice. By default English is the selected language, and after a timeout period, it will be automatically selected. After selecting your language, press Enter . The next screen will give you several options, the first of which is Install Ubuntu Server. Select it by pressing Enter . You will then be asked which language to use for the installation (yes, this is slightly redundant). Select your language of choice (the default is English), and press Enter .
‖ Of course, projects can change their websites whenever they want. Hopefully the instructions we’ve provided here are accurate enough to help guide you through the site even in the event of changes.
40 Chapter 3: Installing Asterisk
You will be presented with a list of countries. Once you’ve found your country and highlighted it, press Enter . You will then be asked if you would like to use the keyboard layout detector. If you know which keyboard type you have, you can select No and then pick it from a list of formats. If you are utilizing the keyboard layout detector, you will be prompted to press a series of keys. If you use the keyboard detector and it does not detect your keyboard correctly (typical when installing into a virtual machine via a remote console), you can go back and select from a list manually. Once you’ve picked your keyboard, the installation will continue by attempting to set up your network automatically. If all goes well, you will be prompted to enter a hostname for your system. You can pick anything you want here, unless your network requires your system to a have a specific hostname. Input it now and then press Enter . The installer will attempt to contact a Network Time Protocol (NTP) server to synchronize your clock. Ubuntu will then try to autodetect your time zone and present you with its choice. If correct, select Yes , otherwise, select No and you’ll be presented with a list of time zones to select from. Select your time zone, or select from the worldwide list if your time zone is not shown. Once you’ve selected your time zone, press Enter to continue. The installer will then ask you some questions about partitioning your system. Typically the default is fine, which is to use the guided system, utilizing the entire disk, and to set up the Logical Volume Manager (LVM). Press Enter once you’ve made your selection. Then you’ll be asked which partition to install to, which likely is the only one on your system. Press Enter to continue, at which point you’ll be asked to confirm the changes to the partition table. Select Yes and press Enter to continue. You will now be asked how much space to use (the default value will be to use the entire disk). Press Enter once you’ve entered and confirmed the amount of space you want to use. The installer will then request one last confirmation before making the changes to the disk. Select Yes to write the changes to disk. The installer will now format the hard disk, write the partitioning scheme to disk, copy the files, and perform the file installation. When the file installation is complete, you’ll be asked to enter the Full name of the new user, from which a username will be generated. The system will suggest a username, but you are free to change the username to whatever you like.
Distribution Installation 41
After entering your username, you’ll be asked to supply a password, and then asked to confirm the password you’ve entered. Ubuntu does a good job of providing a secure system by not providing direct access to root, but rather using the sudo application, which allows you to run commands as root without being the root user. Enter a username,# such as asteriskpbx, and a secure password to continue. You’ll use these to log into the system once the installer ends. The installer will then ask you if you want to encrypt your home directory. This is not necessary and will add CPU overhead. The rest of the installation instructions will assume that asteriskpbx was chosen as the username.
If your system is behind a web proxy, enter the proxy information now. If you’re not behind a proxy, or don’t know if you are, simply press Enter . You will then be asked if you want to install updates automatically. The default is to perform no automatic updates, which is what we recommend. Should a system reboot occur, an update to the kernel will render Asterisk nonstartable until you recompile it* (which won’t make you popular). It is better practice to identify updates on a regular basis and perform them manually in a controlled manner. Normally, you would want to advise your users of the expected downtime and schedule the downtime to happen after business hours (or while a redundant system is running). Select No automatic updates and press Enter . Since we’ll be installing our dependencies with apt-get, we only need to select one package during the install: OpenSSH server. SSH is essential if you wish to perform remote work on the system. However, if your local policy states that your server needs to be managed directly, you may not want to install the OpenSSH server. Pressing the Enter key will accept the current selections and move on with the install. You need to use space bar to toggle your selections.
After you’ve selected OpenSSH server, press Enter . If this is the only operating system on the machine (which it likely is), Ubuntu will give you the option to install the GRUB bootloader on your system. It provides this prompt in order to give you the option of skipping the GRUB installation, as it will modify the master boot record (MBR) on your system. If there is another operating system it has
#Ubuntu has reserved the username asterisk internally. * While we say Asterisk here, specifically it is DAHDI that is the problem. DAHDI is a set of Linux kernel modules used with Asterisk.
42 Chapter 3: Installing Asterisk
failed to detect that has information loaded into the MBR, it’s nice to be able to skip modifying it. If this is the only operating system installed on your server, select Yes . When the system has finished the install, you’ll be asked to remove any media in the drives and to reboot the system by selecting Continue, at which point the installation will be complete and the system will reboot.
Base system update Now that we’ve completed installing Ubuntu Server, we need to perform a system update with apt-get to make sure we have the latest packages installed. You’ll be presented with a login prompt where you’ll log in with the username and password you created in the installer (e.g., asteriskpbx). Once logged in, run the following command: $ sudo apt-get update [sudo] password for asteriskpbx: .. Reading package lists.. Done $ sudo apt-get upgrade Reading state information.. Done .. Do you want to continue [Y/n]? y
The password that sudo wants is the password you just logged in with.
Press Enter when prompted to continue, at which point the latest package updates will be installed. When complete, reboot the system for the changes to take effect as the kernel has probably been updated. $ sudo reboot
Congratulations! You’ve successfully installed and updated the base Ubuntu Server system.
Enable NTP for accurate system time Keeping accurate time is essential on your Asterisk system, both for maintaining accurate call detail records as well as for synchronization with your other programs. You don’t want the times of your voicemail notifications to be off by 10 or 20 minutes, as this can lead to confusion and panic from those who might think their voicemail notification took too long to be delivered: $ sudo apt-get install ntp
Distribution Installation 43
The default on Ubuntu is to run a time sync server without ever changing the time on your own machine. This won’t work for our needs, so we’ll need to change the configuration file slightly. Because of this, we need to guide you through using a command line editor. The nano editor is already installed on your Ubuntu machine and is remarkably easy to use†: $ sudo nano /etc/ntp.conf
Your terminal will switch to full-screen output. Use your arrow keys to move down to the section that looks like # By default, exchange time with everybody, but don't allow configuration. restrict -4 default kod notrap nomodify nopeer noquery restrict -6 default kod notrap nomodify nopeer noquery
Add two new lines after this section, to allow ntpd to synchronize your time with the outside world, such that the above section now looks like # By default, exchange time with everybody, but don't allow configuration. restrict -4 default kod notrap nomodify nopeer noquery restrict -6 default kod notrap nomodify nopeer noquery restrict -4 127.0.0.1 restrict -6 ::1
That’s everything we need to change, so exit the editor by pressing Ctrl + X . When prompted whether to save the modifications, press Y ; nano will additionally ask you for the filename. Just hit Enter to confirm the default /etc/ntp.conf. Now restart the NTP daemon: $ sudo /etc/init.d/ntp restart
With the operating system installed, you’re ready to install the dependencies required for Asterisk. The next section provides an in-depth review of the installation process. If you’ve already reviewed the information in “Software Dependencies” on page 44, you may want to refer back to “Installation Cheat Sheet” on page 31 for a high-level review of how to install Asterisk.
Software Dependencies The first thing you need to do once you’ve completed the installation of your operating system is to install the software dependencies required by Asterisk. The commands listed in Table 3-1 have been split into two columns, for Ubuntu Server and CentOS Server. These packages will allow you to build a basic Asterisk system, along with DAHDI and LibPRI. Not every module will be available at compile time with these † If you’re already familiar with another editor, go ahead and use it. The nano editor has been selected for its ease of use and its handy on-screen instructions. We even know a developer at Digium who uses it while writing code for Asterisk, though most people tend to use more complex editors such as emacs or vim.
44 Chapter 3: Installing Asterisk
dependencies; only the most commonly used modules will be built. If additional dependencies are required for other modules used later in the book, instructions will be provided as necessary. Please be aware that the dependency information on CentOS 64-bit does not take into account that 32-bit libraries should not be installed. If such libraries are installed, you will end up with additional packages that use disk space and can cause conflicts if the system attempts to compile against a 32-bit library instead of its 64-bit counterpart. In order to resolve this problem, add .x86_64 to the end of each package name when installing it. So, for example, instead of executing yum install ncursesdevel, you will execute yum install ncurses-devel.x86_64. This is not necessary on a 32-bit platform. Table 3-1. Software dependencies for Asterisk on Ubuntu Server and CentOS Server Ubuntu
CentOS
sudo apt-get install build-essential
sudo yum install gcc gcc-c++ make wget
subversion libncurses5-dev libssl-dev
subversion libxml2-devel ncurses-devel
libxml2-dev vim-nox
openssl-devel vim-enhanced
These packages will get you most of what you’ll need to get started with installing Asterisk, DAHDI, and LibPRI. Note that you will also require the software dependencies for each package that we indicate needs to be installed. These will be resolved automatically for you when you use either yum or apt-get. We have also included the OpenSSL development libraries, which are not strictly necessary to compile Asterisk, but are good to have: they enable key support and other encryption functionality. We have installed vim as our editor, but you can choose anything you want, such as nano, joe, or emacs. Asterisk contains a script that will install the dependencies for all features in Asterisk. At this time it is complete for Ubuntu but does not list all required packages for CentOS. Once you have downloaded Asterisk using the instructions in “Downloading What You Need” on page 46, use the following commands if you would like to run it: $ cd ~/src/asterisk-complete/asterisk/1.8 $ sudo ./contrib/scripts/install_prereq install $ sudo ./contrib/scripts/install_prereq install-unpackaged
Software Dependencies 45
Third-Party Repositories For certain software dependencies, a third-party repository may be necessary. This appears to be most often the case when using CentOS. A couple of repositories that seem to be able to provide all the extra dependencies required are RPMforge (http://dag .wieers.com/rpm/) and EPEL (Extra Packages for Enterprise Linux, http://fedoraproject .org/wiki/EPEL). We may occasionally refer to these third-party repositories when they are required to obtain a dependency for a module we are trying to build and use.
Downloading What You Need There are several methods of getting Asterisk: via the Subversion code repository, via wget from the downloads site, or via a package-management system such as apt-get or yum. We’re only going to cover the first two methods, since we’re interested in building the latest version of Asterisk from source. Typically, package-management systems will have versions that are older than those available from Subversion or the downloads site, and we want to make sure we have the most recent fixes available to us, so we tend to avoid them. The official packages from Digium do tend to stay up to date. There are currently packages for CentOS/RHEL available at http://www.asterisk .org/downloads/yum.
Before we start getting the source files, let’s create a directory structure to house the downloaded code. We’re going to create the directory structure within the home directory for the asteriskpbx user on the system. Once everything is built, it will be installed with the sudo command. We’ll then go back and change the permissions and ownership of the installed files in order to build a secure system. To begin, issue the following command: $ mkdir -p ~/src/asterisk-complete/asterisk
Now that we’ve created a directory structure to hold everything, let’s get the source code. Choose one of the following two methods to get your files: 1. Subversion 2. wget
46 Chapter 3: Installing Asterisk
Getting the Latest Version Asterisk is a constantly evolving project, and there are many different versions of the software that you can implement. In Chapter 2, we talked about Asterisk versioning. The concept of how Asterisk is versioned is important to understand because the versioning system for Asterisk has undergone a few changes of methodology over the years. So, if you’re not up to speed on Asterisk versioning, we strongly recommend that you go back and read “Asterisk Versioning” on page 26. Having said all that, in most cases all you need to do is grab the latest version from the http://www.asterisk.org/downloads website. We will be installing and using Asterisk 1.8 throughout this book.
Getting the Source via Subversion Subversion is a version control system that is used by developers to track changes to code over a period of time. Each time the code is modified, it must first be checked out of the repository; then it must be checked back in, at which point the changes are logged. Thus, if a change creates a regression, the developers can go back to that change and remove it if necessary. This is a powerful and robust system for development work. It also happens to be useful for Asterisk administrators seeking to retrieve the software. To download the source code to the latest version of Asterisk 1.8, use these commands: $ cd ~/src/asterisk-complete/asterisk $ svn co http://svn.asterisk.org/svn/asterisk/branches/1.8
You can now skip directly to “How to Install It” on page 48. The preceding commands will retrieve the latest changes to the source in that particular branch, which are changes that have been made after the latest release. If you would prefer to use a released version, please refer to the next section.
Getting the Source via wget To obtain the latest released versions of DAHDI, LibPRI, and Asterisk using the wget application, issue the following commands: $ cd ~/src/asterisk-complete/asterisk $ wget http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-1.8-current.tar.gz $ tar zxvf asterisk-1.8-current.tar.gz
The next step is to compile and install the software, so onward to the next section.
Downloading What You Need 47
How to Install It With the source files downloaded you can compile the software and install it. The order for installing is: 1. LibPRI‡ 2. DAHDI§ 3. Asterisk‖ Installing in this order ensures that any dependencies for DAHDI and Asterisk are installed prior to running the configuration scripts, which will subsequently ensure that any modules dependent on LibPRI or DAHDI will be built. So, let’s get started.
LibPRI LibPRI is a library that adds support for ISDN (PRI and BRI). The use of LibPRI is optional, but since it takes very little time to install, doesn’t interfere with anything, and will come in handy if you ever want to add cards to a system at a later point, we recommend that you install it now. Check out the latest version of LibPRI and compile it like so: $ $ $ $ $ $ $
cd ~/src/asterisk-complete/ mkdir libpri cd libpri/ svn co http://svn.asterisk.org/svn/libpri/tags/1.4. cd 1.4. make sudo make install
You can also download the source via wget from http://downloads.aster isk.org/pub/telephony/libpri/.
With LibPRI installed, we can now install DAHDI.
‡ Strictly speaking, if you are not going to be using any ISDN connections (BRI and PRI), you can install Asterisk without LibPRI. However, we are going to install it for the sake of completeness. § This package contains the kernel drivers to allow Asterisk to connect to traditional PSTN circuits. It is also required for the MeetMe() conferencing application. Again, we will install this for completeness. ‖ If you don’t install this, none of the examples in this book will work, but it could still make a great bathroom reader. Just sayin’.
48 Chapter 3: Installing Asterisk
DAHDI The Digium Asterisk Hardware Device Interface, or DAHDI (formerly known as Zaptel), is the software Asterisk uses to interface with telephony hardware. We recommend that you install it even if you have no hardware installed, because DAHDI is a dependency required for building the timing module res_timing_dahdi and is used for Asterisk dialplan applications such as MeetMe().
DAHDI-tools and DAHDI-linux DAHDI is actually a combination of two separate code bases: DAHDI-tools, which provides various administrator tools such as dahdi_cfg, dahdi_scan, etc.; and DAHDIlinux, which provides the kernel drivers. Unless you’re only updating one or the other, you’ll be installing both at the same time, which is referred to as DAHDI-linux-complete. The version numbering for DAHDI-linux-complete will look something like 2.4.0+2.4.0, where the number to the left of the plus sign is the version of DAHDIlinux included, and the version number to the right of the plus sign is the DAHDItools version included. There are also FreeBSD drivers for DAHDI, which are maintained by the community. These drivers are available at http://downloads.asterisk.org/pub/telephony/dahdi-freebsd -complete/.
Another dependency is required for installing DAHDI, and that is the kernel source. It is important that the kernel version being used match exactly that of the kernel source being installed. You can use uname -a to verify the currently running kernel version: • CentOS: sudo yum install kernel-devel-`uname -r` • Ubuntu: sudo apt-get install linux-headers-`uname -r` The use of uname -r surrounded by backticks (`) is for filling in the currently running kernel version so the appropriate package is installed. The following commands show how to install DAHDI-linux-complete 2.4.0+2.4.0. There may be a newer version available by the time you are reading this, so check downloads.asterisk.org first. If there is a newer version available, just replace the version number in the commands: $ $ $ $ $ $ $ $
cd ~/src/asterisk-complete/ mkdir dahdi cd dahdi/ svn co http://svn.asterisk.org/svn/dahdi/linux-complete/tags/2.4.0+2.4.0 cd 2.4.0+2.4.0 make sudo make install sudo make config
How to Install It 49
You will need to have Internet access when running the make all command, as it will attempt to download the latest hardware firmware from the Digium servers.
After installing DAHDI, we can move on to installing Asterisk. You can also download the source via wget from http://downloads.aster isk.org/pub/telephony/dahdi-linux-complete/.
Asterisk With both DAHDI and LibPRI installed, we can now install Asterisk: $ $ $ $ $
cd ~/src/asterisk-complete/asterisk/1.8 ./configure make sudo make install sudo make config
With the files now installed in their default locations, we need to modify the permissions of the directories and their contents. There is an additional step that is not strictly required, but is quite common (and arguably important): the make menuselect command, which provides a graphical interface that allows detailed selection of which modules and features will be compiled. We will discuss this in “make menuselect” on page 59.
Setting File Permissions In order to run our system more securely, we’ll be installing Asterisk and then running it as the asteriskpbx user. After installing the files into their default locations, we need to change the file permissions to match those of the user we’re going to be running as. Execute the following commands after running make install (which we did previously): $ $ $ $ $ $
sudo sudo sudo sudo sudo sudo
chown chown chown chown chown chown
-R asteriskpbx:asteriskpbx /usr/lib/asterisk/ -R asteriskpbx:asteriskpbx /var/lib/asterisk/ -R asteriskpbx:asteriskpbx /var/spool/asterisk/ -R asteriskpbx:asteriskpbx /var/log/asterisk/ -R asteriskpbx:asteriskpbx /var/run/asterisk asteriskpbx:asteriskpbx /usr/sbin/asterisk
In order to use MeetMe() and DAHDI with Asterisk as non-root, you must change the /etc/udev/rules.d/dahdi.rules so that the OWNER and GROUP fields match the non-root user Asterisk will be running as. In this case, we’re using the asteriskpbx user.
50 Chapter 3: Installing Asterisk
Change the last line of the dahdi.rules file to the following: SUBSYSTEM'dahdi', OWNER='asteriskpbx', GROUP='asteriskpbx', MODE='0660'
With that out of the way, we can move on to performing the base configuration that should be done after all installations.
Base Configuration Now that we’ve got Asterisk installed, we can get our system up and running. The purpose here is to get Asterisk loaded up and ready to go, as it isn’t doing anything useful yet. These are the steps that all system administrators will need to start out with when installing a new system. If the commands that need to be run differ on CentOS and Ubuntu, you will see a table with rows labeled for each distribution; otherwise, you will see a single command that should be run regardless of which Linux distribution you have chosen.
Disable SELinux This section applies only to CentOS users, so if you’re using Ubuntu, you can skip to the next section.
In CentOS, the Security-Enhanced Linux (SELinux) system is enabled by default, and it often gets in the way of Asterisk. Sometimes the issues are quite subtle, and at least one of the authors has spent a good number of hours debugging issues in Asterisk that turned out to be resolved by disabling SELinux. There are many articles on the Internet that describe the correct configuration of SELinux, but we’re going to disable it for the sake of simplicity. While disabling SELinux is not the ideal situation, the configuration of SELinux is beyond the scope of this book, and frankly, we just don’t have enough experience with it to configure it correctly.
To temporarily switch off SELinux, perhaps in order to verify whether an issue you’re having is being caused by SELinux, run the following command as root: $ sudo echo 0 > /selinux/enforce
You can reenable SELinux by doing the same thing, but replacing the 0 with a 1: $ sudo echo 1 > /selinux/enforce
Base Configuration 51
To disable SELinux permanently, modify the /etc/selinux/config file: $ cd /etc/selinux/ $ sudo vim config
Change the SELINUX option from enforcing to disabled. Alternatively, you can change the value of enforcing to permissive, which simply logs the errors instead of enforcing the policy.
When you’re done modifying the configuration file, you’ll have the following: # This file controls the state of SELinux on the system. # SELINUX= can take one of these three values: # enforcing - SELinux security policy is enforced. # permissive - SELinux prints warnings instead of enforcing. # disabled - SELinux is fully disabled. SELINUX=disabled # SELINUXTYPE= type of policy in use. Possible values are: # targeted - Only targeted network daemons are protected. # strict - Full SELinux protection. SELINUXTYPE=targeted # SETLOCALDEFS= Check local definition changes SETLOCALDEFS=0
Since you can’t disable SELinux without rebooting, you’ll need to do that now: $ sudo reboot
Initial Configuration In order to get Asterisk up and running cleanly, we need to create some configuration files. We could potentially install the sample files that come with Asterisk (by executing the make samples command in our Asterisk source) and then modify those files to suit our needs, but the make samples command installs many sample files, most of them for modules that you will never use. We want to limit which modules we are loading, and we also believe that it’s easier to understand Asterisk configuration if you build your config files from scratch, so we’re going to create our own minimal set of configuration files.# The first thing we need to do (assuming it does not already exist) is create the /etc/ asterisk/ directory where our configuration files will live: $ sudo mkdir /etc/asterisk/ $ sudo chown asteriskpbx:asteriskpbx /etc/asterisk/
#If your /etc/asterisk/ folder has files in it already, move those files to another directory, or delete them if you are sure you don’t need what is there.
52 Chapter 3: Installing Asterisk
Running make samples on a system that already has configuration files will overwrite the existing files.
Using make samples to Create Sample Configuration Files for Future Reference Even though we are not going to use the sample configuration files that come with Asterisk, the fact is that they are an excellent reference. If there is a module that you are not currently using but wish to put into production, the sample file will show you exactly what syntax to use, and what options are available for that module. Running the sudo make samples command in your Asterisk source directory* is harmless on a new system that has just been built, but it is very dangerous to run on a system that already has configuration files, as this command will overwrite any existing files (which would be a disaster for you if you do not have a current backup). If you’ve run the sudo make samples command, you will want to move the files that it has created in /etc/asterisk/ to another folder. We like to create a folder called /etc/ asterisk/unused/ and put any sample/unused configuration files in there, but feel free to store them wherever you like.
We’re now going to step through all the files that are required to get a simple Asterisk system up and running.
indications.conf and asterisk.conf The first file needed is indications.conf, a file that contains information about how to detect different telephony tones for different countries. There is a perfectly good sample file that we can use in the Asterisk source, so let’s copy it into our /etc/asterisk/ directory: $ cp ~/src/asterisk-complete/asterisk/1.8/configs/indications.conf.sample /etc/asterisk/indications.conf
Because we’re running Asterisk as non-root, we need to tell Asterisk which user to run as. This is done with the asterisk.conf file. We can copy a sample version of it from the Asterisk source to /etc/asterisk: $ cp ~/src/asterisk-complete/asterisk/1.8/configs/asterisk.conf.sample /etc/asterisk/asterisk.conf
The asterisk.conf file contains many options that we won’t go over here (they are covered in “asterisk.conf” on page 71), but we do need to make an adjustment. Near the end of the [options] section, there are two options we need to enable: runuser and rungroup. * /usr/src/asterisk-complete/asterisk/asterisk-1.8./
Base Configuration 53
Open the asterisk.conf file with an editor such as nano or vim: Uncomment the run user and rungroup lines, and modify them so that they each contain asteriskpbx as the assigned value. Open the /etc/asterisk/asterisk.conf file with vim: $ vim /etc/asterisk/asterisk.conf
Then modify the file by uncommenting the two lines starting with runuser and run group and modifying the value to asteriskpbx. runuser=asteriskpbx rungroup=asteriskpbx
We now have all the configuration files required to start a very minimal version of Asterisk.† Give it a shot by starting Asterisk up in the foreground: $ /usr/sbin/asterisk -cvvv
We are specifying the full path to the asterisk binary, but if you modify your PATH system variable to include the /usr/sbin/ directory you don’t need to specify the full path. See “Adding a system user” on page 39 for information about modifying the $PATH environment variable.
Asterisk will start successfully without any errors or warnings (although it does warn you that some files are missing), and present to you the Asterisk command-line interface (CLI). At this point there are no modules, minimal core functionality, and no channel modules with which to communicate, but Asterisk is up and running. Executing the module show command at the Asterisk CLI shows that there are no external modules loaded: *CLI> module show Module 0 modules loaded
Description
Use Count
We’ve done this simply to demonstrate that Asterisk can be run in a very minimal state, and doesn’t require the dozens of modules that a default install will enable. Let’s stop Asterisk with the core stop now CLI command: *CLI> core stop now
† So minimal, in fact, that it’s completely useless at this point. But we digress.
54 Chapter 3: Installing Asterisk
The Asterisk Shell Command Asterisk can be run either as a daemon or as an application. In general, you will want to run it as an application when you are building, testing, and troubleshooting, and as a daemon when you put it into production. The command to start Asterisk is the same regardless of whether you’re running it as a daemon or an application: asterisk However, without any arguments, this command will assume certain defaults and start Asterisk as a background application. In other words, you never want to run the command asterisk on its own, but rather will want to pass some options to it to better define the behavior you are looking for. The following list provides some examples of common usages. -h
This command displays a helpful list of the options you can use. For a complete list of all the options and their descriptions, run the command man asterisk. -c
This option starts Asterisk as an application (in the foreground). This means that Asterisk is tied to your user session. In other words, if you close your user session by logging out or losing the connection, Asterisk dies. This is the option you will typically use when building, testing, and debugging, but you would not want to use this option in production. If you started Asterisk in this manner, type core stop now at the CLI prompt to stop Asterisk and exit. -v, -vv, -vvv, -vvvv, etc.
This option can be used with other options (e.g., -cvvv) in order to increase the verbosity of the console output. It does exactly the same thing as the CLI command core set verbose n where n is any integer between 0 and 5 (any integer greater than 5 will work, but will not provide any more verbosity). Sometimes it’s useful to not set the verbosity at all. For example, if you are looking to see only startup errors, notices, and warnings, leaving verbosity off will prevent all the other startup messages from being displayed. -d, -dd, -ddd, -dddd, etc.
This option can be used in the same way as -v, but instead of normal output, this will specify the level of debug output (which is primarily useful for developers who wish to troubleshoot problems with the code). You will also need to enable output of debugging information in the logger.conf file (which we will cover in more detail in Chapter 24). -r
This command is essential if you want to connect to the CLI of an Asterisk process running as a daemon. You will probably use this option more than any other for Asterisk systems that are in production. This option will only work if you have a daemonized instance of Asterisk already running. To exit the CLI when this option has been used, type exit.
Base Configuration 55
-T
This option will add a timestamp to CLI output. -x
This command allows you to pass a string to Asterisk that will be executed as if it had been typed at the CLI. As an example, to get a quick listing of all the channels in use without having to start the Asterisk console, simply type asterisk -rx 'core show channels' from the shell, and you’ll get the output you are looking for. -g
This option instructs Asterisk to dump a core file if it crashes. We recommend you try out a few combinations of these commands to see what they do.
safe_asterisk When you install Asterisk using the make config directive it will create a script called safe_asterisk, which is run during the init process of Linux each time you boot. The safe_asterisk script provides the following benefits: • Restarts Asterisk automatically after a crash • Can be configured to email the administrator if a crash has occurred • Defines where crash files are stored (/tmp by default) • Executes a script if a crash has occurred You don’t need to know too much about this script, other than to understand that it should normally be running. In most environments this script works fine in its default format.
modules.conf So, we’ve managed to get Asterisk running, but it’s not able to do anything useful for us yet. To tell Asterisk what modules we expect it to load, we’ll need a modules.conf file. Create the file modules.conf in your /etc/asterisk/ directory with the following command (replace the >> with > if you instead want to overwrite an existing file): $ cat >> /etc/asterisk/modules.conf
Type (or paste) the following lines, and press Ctrl + D on a new line when you’re finished: ; The modules.conf file, used to define which modules Asterisk should load (or ; not load). ; [modules] autoload=yes
56 Chapter 3: Installing Asterisk
Using cat to Quickly Create Files and Add Content to Them There are many cases in a Linux system where it is necessary to create a file, and then add some content to it. This is commonly done by using the touch command to create the file, and then opening it with an editor to add the content. However, there is a lessknown way of doing this that lets you create the file and add the content all at once: • Use the cat program to redirect output to the file you want (use >> to append, or > to overwrite). • Paste or type the content you want to add to the file. • Press Ctrl + D to complete your changes. Presto! File created and content added.
The autoload=yes line will tell Asterisk to automatically load all modules located in the /usr/lib/asterisk/modules/ directory. If you wanted to, you could leave the file like this, and Asterisk would simply load any modules it found in the modules folder. With your new modules.conf file in place, starting Asterisk will cause a whole slew of modules to be loaded. You can verify this by starting Asterisk and running the module show command: $ asterisk -c *CLI> module show Module res_speech.so res_monitor.so .. func_math.so 171 modules loaded
Description Generic Speech Recognition API Call Monitoring Resource
Use Count 0 0
Mathematical dialplan function
0
We now have many modules loaded, and many additional dialplan applications and functions at our disposal. We don’t need all these resources loaded, though, so let’s filter out some of the more obscure modules that we don’t need at the moment. Modify your modules.conf file to contain the following noload lines, which will tell Asterisk to skip loading the identified modules: ; Resource modules noload => res_speech.so noload => res_phoneprov.so noload => res_ael_share.so noload => res_clialiases.so noload => res_adsi.so ; PBX modules noload => pbx_ael.so noload => pbx_dundi.so
Base Configuration 57
; Channel noload => noload => noload => noload => noload => noload => noload =>
modules chan_oss.so chan_mgcp.so chan_skinny.so chan_phone.so chan_agent.so chan_unistim.so chan_alsa.so
; Application modules noload => app_nbscat.so noload => app_amd.so noload => app_minivm.so noload => app_zapateller.so noload => app_ices.so noload => app_sendtext.so noload => app_speech_utils.so noload => app_mp3.so noload => app_flash.so noload => app_getcpeid.so noload => app_setcallerid.so noload => app_adsiprog.so noload => app_forkcdr.so noload => app_sms.so noload => app_morsecode.so noload => app_followme.so noload => app_url.so noload => app_alarmreceiver.so noload => app_disa.so noload => app_dahdiras.so noload => app_senddtmf.so noload => app_sayunixtime.so noload => app_test.so noload => app_externalivr.so noload => app_image.so noload => app_dictate.so noload => app_festival.so
There are, of course, other modules that you could remove, and others that you may find extremely useful, so feel free to tweak this file as you wish. Ideally, you should be loading only the modules that you need for the system you are running. The examples in this book assume that your modules.conf file looks like our example here. Additional information about the modules.conf file can be found in the section “modules.conf” on page 75.
musiconhold.conf The musiconhold.conf file defines the classes for music on hold in your Asterisk system. By defining different classes, you can specify different hold music to be used in various situations, such as different announcements to be played while holding in a queue, or different hold music if you have multiple PBXs hosted on the same system. For now,
58 Chapter 3: Installing Asterisk
we’ll just create a default music on hold class so that we have at a minimum some hold music when placing callers on hold: $ cd /etc/asterisk/ $ cat >> musiconhold.conf ; musiconhold.conf [default] mode=files directory=moh Ctrl + D
We’ve created a musiconhold.conf file and defined our [default] hold music class. We’re also assuming you installed the hold music from the menuselect system; by default there is at least one music on hold package installed, so unless you disabled it, you should have music in at least one format. Additional information about musiconhold.conf can be found in the section “musiconhold.conf” on page 79.
make menuselect menuselect is a text-based menu system in Asterisk used to configure which modules to compile and install. The modules are what give Asterisk its power and functionality. New modules are constantly being created. In the installation sections, we conveniently skipped over using the menuselect system in order to keep the instructions simple and straightforward. However, it is important enough that we have given menuselect its own section. In addition to specifying which modules to install, menuselect also allows you to set flags that can aid in debugging issues (see Chapter 2), set optimization flags, choose different sound prompt files and formats, and do various other nifty things.
Uses for menuselect We would need a whole chapter in order to fully explore menuselect, and for the most part you won’t need to make many changes to it. However, the following example will give you an idea of how menuselect works, and is recommend for any installation. By default Asterisk only installs the core sound prompt files, and only in GSM format. Also, the three OpSound music on hold files available for download are only selected in .wav format.‡
‡ A good way to put the final touches on your new system is to install some appropriate sound files to be used as music on hold. There are only three songs installed by default, and callers will quickly tire of listening to the same three songs over and over again. We’ll discuss this more in “musiconhold.conf” on page 79.
Base Configuration 59
We’re going to want extra sound prompts installed instead of just the default core sound prompts, and in a better-sounding format than GSM. We can do this with the menuselect system by running make menuselect in the Asterisk source directory. Before exploring that, though, let’s talk about the different menuselect interfaces.
menuselect interfaces There are two interfaces available for menuselect: curses and newt. If the libnewt libraries are installed, you will get the blue and red interface shown in Figure 3-1. Otherwise, by default menuselect will use the curses (black and white) interface shown in Figure 3-2. The minimum screen size for the curses interface is 80x27, which means it may not load if you’re using the default terminal size for a simple distribution installation. This is not a problem when you’re using SSH to reach the server remotely, as typically your terminal can be resized, but if you’re working at the terminal directly you may need to have screen buffers installed to enable a higher resolution, which is not recommended for a system running Asterisk. The solution is to use the newt-based menuselect system.
Figure 3-1. menuselect using the newt interface
60 Chapter 3: Installing Asterisk
Figure 3-2. menuselect using the curses interface
Installing Dependencies for newt-Based menuselect To get the newt-based menuselect working, you need to have the libnewt development libraries installed: • CentOS: sudo yum install libnewt-devel • Ubuntu: sudo apt-get install libnewt-dev If you’ve previously used menuselect with the curses interface, you need to rebuild. You can do this with the following commands: $ $ $ $ $ $
cd ~/src/asterisk-complete/asterisk/1.8./ cd menuselect make clean ./configure cd . make menuselect
After that you should have the newt-based interface available to you.
Using menuselect Run the following commands to start menuselect: $ cd ~/src/asterisk-complete/asterisk/1.8./ $ make menuselect
Base Configuration 61
You will be presented with a screen such as that in Figure 3-1 or Figure 3-2. You can use the arrow keys on your keyboard to move up and down. The right arrow key will take you into a submenu, and the left arrow key will take you back. You can use the space bar or Enter key to select and deselect modules. Pressing the q key will quit without saving, while the x key will save your selections and then quit.
Module Dependencies Modules that have XXX in front of them are modules that cannot be compiled because the configure script was not able to find the dependencies required (for example, if you don’t have the unixODBC development package installed, you will not be able to compile func_odbc§). Whenever you install a dependency, you will always need to rerun configure before you run menuselect, so that the new dependency will be properly located. The dependant module will at that point be available in menuselect. If the module selection still contains XXX, either the configure script is still unable to find the dependency or not all dependencies have been satisfied.
Once you’ve started menuselect, scroll down to Core Sound Packages and press the right arrow key (or Enter ) to open the menu. You will be presented with a list of available options. These options represent the core sound files in various languages and formats. By default, the only set of files selected is CORE-SOUNDS-EN-GSM, which is the English-language Core Sounds package in GSM format. Select CORE-SOUNDS-EN-WAV and CORE-SOUNDS-EN-ULAW (or ALAW if you’re outside of North America or Japan‖), and any other sound files that may be applicable in your network. The reason we have multiple formats for the same files is that Asterisk can play back the appropriate format depending on which codec is negotiated by an endpoint. This can lower the CPU load on a system significantly.
After selecting the appropriate sound files, press the left arrow key to go back to the main menu. Then scroll down two lines to the Extra Sound Packages menu and press the right arrow key (or Enter ). You will notice that by default there are no packages selected. As with the core sound files, select the appropriate language and format to be installed. A good option is probably to install the English sound files in the WAV, ULAW, and ALAW formats. § Which we will cover in Chapter 16, along with many other cool things. ‖ If you want to understand all about mu-law and A-law, you can read the section “Logarithmic companding” on page 607. All you need to know here is that outside of North America and Japan, A-law is used.
62 Chapter 3: Installing Asterisk
Once you’ve completed selecting the sound files, press the x key to save and exit menuselect. You then need to install your new prompts by downloading them from the Asterisk downloads site. This is done simply by running make install again: $ sudo make install $ sudo chown -R asteriskpbx:asteriskpbx /var/lib/asterisk/sounds/
The files will be downloaded, extracted, and installed into the appropriate location (/var/lib/asterisk/sounds// by default). Your Asterisk server will need to have a working Internet connection in order to retrieve the files.
Scripting menuselect Administrators often build tools when performing installations on several machines, and Asterisk is no exception. If you need to install Asterisk onto several machines, you may wish to build a set of scripts to help automate this process. The menuselect system contains command-line options that you can use to enable or disable the modules that are built and installed by Asterisk. If you are starting with a fresh checkout of Asterisk, you must first execute the configure script in order to determine what dependencies are installed on the system. Then you need to build the menuselect application and run the make menuselect-tree command to build the initial tree structure: $ cd ~/src/asterisk-complete/asterisk/1.8./ $ ./configure $ cd menuselect $ make menuselect $ cd . $ make menuselect-tree Generating input for menuselect ..
For details about the options available, run menuselect/menuselect --help from the top level of your Asterisk source directory. You will be returned output like the following: Usage: menuselect/menuselect [--enable