The Little Asterisk Handbook

Andy Powell 2005

 

 

http://www.automated.it/asterisk/

 

 

 

 

Version 0.1a for Asterisk releases to 1.0.7

 

 

 

 

 

 


 

 

Copyright 2005 by Andy Powell. All Rights Reserved.

 

You may distribute this document electronically, print copies of it or give copies away. You may NOT charge ANYTHING for it or require any fee of any kind to gain access to it or download it. If you distribute this document then you must distribute the entire document with no changes or modifications.

 

 

You may convert this document specifically for those with poor sight, the blind or those with physical disabilities into an appropriate format for them to read or hear. You must however maintain the copyright information and credit the author.

 

 

You may not use this document on any fee based training course without prior consent from the author.

 

 

 


 

 

 

 

 

 

 

The Little Asterisk Handbook is dedicated to my wife Jennie, without who, I'd have neither the inclination or time to write it.

 

 

 

 

 

 

 

 

 

 

 

 

 

 


Contents


Document Conventions.......................................................................................................................... 6

Introduction........................................................................................................................................... 7

Target Audience................................................................................................................................ 9

What is Asterisk? ........................................................................................................................... 10

Who Made Asterisk? ..................................................................................................................... 10

The Basics........................................................................................................................................... 11

Setup A Test Phone........................................................................................................................ 11

Understanding Extensions................................................................................................................ 16

Special Variables........................................................................................................................ 19

Contexts..................................................................................................................................... 20

Include, Not Exclude.................................................................................................................. 22

Pattern Match............................................................................................................................. 25

Let's Get It Working........................................................................................................................ 27

Starting, Stopping and Reloading Asterisk........................................................................................ 31

Codecs........................................................................................................................................... 33

Channels......................................................................................................................................... 36

Common Dialplan Commands......................................................................................................... 37

Answer...................................................................................................................................... 39

Background................................................................................................................................ 39

Dial............................................................................................................................................ 40

Echo ......................................................................................................................................... 44

Goto.......................................................................................................................................... 45

Gotoif......................................................................................................................................... 45

Hangup...................................................................................................................................... 46

NoOp........................................................................................................................................ 46

Playback.................................................................................................................................... 46

SetVar....................................................................................................................................... 47

VoiceMail.................................................................................................................................. 48

VoiceMailMain........................................................................................................................... 49

Wait........................................................................................................................................... 50

Logging........................................................................................................................................... 52

Rotate logs................................................................................................................................. 55

Verbosity................................................................................................................................... 55

Getting to Grips with sip.conf........................................................................................................... 57

DNS for SIP.............................................................................................................................. 60

Getting to Grips with iax.conf........................................................................................................... 61

Setting Up Cards............................................................................................................................. 62

X100P Installation...................................................................................................................... 63

TDM400P Installation................................................................................................................ 63

TE410P/TE405P Installation...................................................................................................... 64

Configuration.............................................................................................................................. 65

Voice Mail...................................................................................................................................... 66

Music On Hold............................................................................................................................... 67

Call Parking.................................................................................................................................... 69

Queues........................................................................................................................................... 71

A Basic Configuration.......................................................................................................................... 72

An Advanced Configuration................................................................................................................. 73

Tips And Tricks................................................................................................................................... 74

Marco Polo test.............................................................................................................................. 74

Separate Applications/Macros......................................................................................................... 74

Set Your CallerID........................................................................................................................... 74

Office hours.................................................................................................................................... 75

Quick Reference.................................................................................................................................. 76

Codec Bandwidth Requirements........................................................................................................... 77

Useful Links......................................................................................................................................... 84


 

 

 

 

 

 

 

 


Document Conventions

 

This document uses some simple conventions to represent how the information contained should be viewed by the reader.

 

Elements that appear in boxes like the one below are designed to be typed in to the asterisk/linux machine directly by the user

 

 

 

ls -lah

 

 

 

Responses from the machine or screen display output appear in boxes such as the one below,

 

 

total 832K

drwxr-xr-x 8 root root 3.0K Apr 15 15:36 .

drwxr-xr-x 63 root root 5.0K Apr 14 13:28 ..

-rw-r--r-- 1 root root 1.8K Dec 4 2003 2q

-rwxr-xr-x 1 root root 140 Dec 4 2003 adsi.conf

-rwxr-xr-x 1 root root 840 Dec 4 2003 adtranvofr.conf

 

 

 

The output may be trimmed or edited for brevity. If there is a particular item the reader should take note of it may appear as:

 

 

 


You may find notes indicated by the symbol to the left useful or time saving. Notes are in italics to separate from the text body.

 

 

 


Introduction

 

You probably already know this but it is worth reinforcing the idea. Asterisk tears the arms and legs off traditional PBX systems, and beats them with the soggy ends.

 

 

Traditional PBX's allow you to perform the functions that the manufacturer thinks you might want or need. Asterisk allows you to do this and more. You get full control and the ability to extend and expand its functionality in reality, your imagination is the limit.

 

 

What? You don't believe me? How about this as an example. I've left the house and forgotten to take my keys.. oh no, how am I going to get back in? Simple. I have a special number I can call, enter my passwords and have the door catch release all controlled from my PBX.

 

 

 


Do not use Caller ID as the sole method of authenticating callers, in reality caller id is simply an indication of who might be calling and is easily spoofed. Use Caller ID in conjunction with passwords for items requiring security.

 

 

Asterisk can be easily expanded by adding your own modules or, remember we're dealing with open source here, you can change the existing modules to suit your specific needs.

 

 

Commercial PBX's offering only a subset of the features in Asterisk retail for huge sums of money, be thankful that Digium made their code GPL so you, me and your pet dog/cat/goldfish/badger could enjoy the power of Asterisk for free. It is my firm belief that Asterisk has made a huge contribution to VoIP and its acceptance.

 

 

One thing I will not mention in this document is Skype well ok, I'll mention it in passing but in my opinion it is bad for VoIP simply because it's a closed system. For me the freedom I get from VoIP systems and what makes them powerful is their ability to inter operate with other systems using STANDARDS. In the world of Skype, if you aren't using their client, you don't exist. Do yourself a favor, forget about Skype and join something like Free World Dialup ( http://www.freeworlddialup.com ) - It's free and inter operates with most networks.

 

 

Please note that this document is in constant flux, as a result things may change or you may find yourself drifting through space and time. I accept no responsibility for this. Please ensure you have adequate insurance to cover any such eventuality. No return keys were harmed in the making of this document, any references to 'hit the return key' should not be taken literally, hammers should not be used.


Target Audience

 

I'll confess straight up, this document is designed for people who have Asterisk installed already or are using something like my Asterisk Live! CD, CF card or PXE editions found at my website http://www.automated.it/asterisk/ . It will not deal with installing Asterisk, there are numerous guides available, including my own Getting Started With Asterisk Guide at http://www.automated.it/guidetoasterisk.htm Nothing like a bit of self promotion, eh? This Document is intended to help you configure an installed Asterisk System

 

 

There are other versions of Live installs of asterisk and I've listed some at the end of this document in the useful links section.

 

 

The document is split into three different sections, the basics, a simple configuration and advanced and custom setup. The basics will introduce the main concepts and explain the essential information you need in order to understand how the configuration elements hang together.

 

 

Special Thanks

 

Special thanks go to Ian Lowe of Wintermute Ltd ( http://www.wintermute-ltd.com ) and James Hoye, for proof reading this document.

 


What is Asterisk?

Asterisk PBX, from now on just called Asterisk, is Linux based, Open Source and free PBX software. Or to quote from the Asterisk website http://www.asterisk.org (with corrected spelling ;) )

 

Asterisk is a complete PBX in software. It runs on Linux and provides all of the features you would expect from a PBX and more. Asterisk does voice over IP in three protocols, and can inter operate with almost all standards-based telephony equipment using comparatively inexpensive hardware.

 

Asterisk provides Voice mail services with Directory, Call Conferencing, Interactive Voice Response, Call Queuing. It has support for three-way calling, caller ID services, ADSI, SIP and H.323 (as both client and gateway). Check the Features section for a more complete list.

 

Asterisk needs no additional hardware for Voice over IP. For interconnection with digital and analog telephony equipment, Asterisk supports a number of hardware devices, most notably all of the hardware manufactured by Asterisk's sponsors, Digium. Digium has single and quad span T1 and E1 interfaces for interconnection to PRI lines and channel banks. In addition, an analog FXO card is available, and more analog interfaces are in the works.

 

Who Made Asterisk?

Asterisk was originally written by Mark Spencer of Digium dba Linux Support Services, Inc. Code has been contributed from Open Source coders around the world, and testing and bug-patches from the community have provided invaluable aid to the development of this software.

 


The Basics

 

With the exception of one file (/etc/zaptel.conf) all of the Asterisk configuration files live in /etc/asterisk/ . Listing them produces a somewhat daunting array of about 40 files. The good news is that you don't have to edit all of them, you'll only need to modify those that you need or want to use.

 

 

The single most important file you need to understand is extensions.conf, this file defines the extensions (phone numbers) and actions carried out when an extension is called. It is the core element of Asterisk configuration, everything else you do relies on this.

 

 

Of course this creates a little problem for someone starting out. To use and understand the extensions.conf file, you need to use and understand the configuration files that define phones so that you can test as see for yourself how things hang together. As a consequence of this the first thing we'll do is setup a phone blindly for use in our testing, then we'll go into detail on the extensions file. When I say blindly, I simply mean that I'll tell you what to type and you'll type it without particularly understanding it. Don't worry we'll come back to it later and I'll explain everything.

 

Setup A Test Phone

 

For our test phone we're going to use SIP, and it's going to be a softphone. Some of you may be squealing like little children at this point, complaining that you've just spent your hard earned money on a hardphone and you want to use that. No problem, you can use that, but since there are so many makes and models YOU will need to configure the phone side on your own.

 

 

 


A softphone is simply a piece of software for your PC that looks a bit like a phone, a hardphone is something solid, made of plastic/metal which will need a power supply and network connection it resembles a real telephone.

 

 

 

Why SIP? Well, there's a large array of usable soft and hard phones out there that all use SIP which means it's easy for you to find a free one or one you are comfortable with. The first thing you're going to need to do is download and install a softphone. For the remainder of this document I'm going to assume that you've downloaded and installed Xlite from Xten software. Xlite can be downloaded from the Xten website, http://www.xten.com/index.php?menu=products&smenu=download .

 

 

You will, at the minimum, need a sound card and some speakers in your PC/Mac, that way you'll at least get to hear things when we demonstrate them, you really should have a microphone too but if it's not a headset then be very aware of potential feedback.

 

 

The first thing we'll do is setup the Asterisk side, then we'll go on to configure the phone. Connect to your Asterisk machine via either the console or an application like Putty ( http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html ) and login as the root user. Since you've already learned that Asterisk configuration files live in /etc/asterisk (ahem, ok a little reminder never hurt) we should go to that directory, type the following in the console/putty window and hit return

 

 

 

cd /etc/asterisk

 

 

 

Since we're dealing with SIP, we need to modify the sip configuration file, or sip.conf (that was difficult eh?!)

 

 

 

vi sip.conf

 

 

 

vi is an editor for linux machines, more than likely it's really vim not vi on your machine, but let's not dwell on that. When you first start up vi you'll be in command mode.

 

 


Here are a few tips for using vi:

 

Hit the insert key once to get into insert mode

Hit it again to get into replace mode

Hit the escape key to get into command mode

 

To quit without saving, hit the escape key followed by a colon (:) then lower case Q and an exclamation mark (!) then hit return, eg:

 

:q!

 

To save a file and then quit, hit the escape key followed by a colon (:) then lower case W and lower case Q

 

then hit return eg:

 

:wq

 

Hint:

If you'd prefer not to use vi, try nano or pico but remember the save/exit commands are different!

 

We need to define an account for this install, for the moment scroll all the way down to the end of the file and add these lines:

 

 

 

 

[1000]

username=1000

secret=abc123

context=mytest

host=dynamic

 

 

 

Then save the file.

 

 

Now that you've installed X-lite, start it up, you should see two windows, the main phone interface window and the configuration window.

 

 

 


 

 


We're going to configure the softphone, save the settings and then shut it down and continue with the document, and since I haven't told you to start Asterisk yet, you haven't right? If you have, then connect to the server and stop Asterisk using the commands

 

 

 

asterisk -r

 

 

 

And then issuing the stop now command in the Asterisk cli.

 

 

 

stop now

 

 

 

You should see something like

 

 

 

 

asterisk*CLI> stop now

asterisk*CLI> Asterisk ended with exit status 0

Asterisk shutdown normally.

 

Disconnected from Asterisk server

 

 

If you've behaved yourself and not started Asterisk you get a gold star. In Xlite's configuration window change the following to their corresponding value:

 

 

Enabled Yes

Display Name Your Name

Username 1000

Authorisation User 1000

Password abc123

SIP Proxy The IP address of your Asterisk server

Domain/Realm The IP address of your Asterisk server (if you have an FQDN

(domain name) then you can use that )

Register Always

 

 

Scroll all the way down to the bottom of the list and double click Update settings, and then double click Confirm Update Settings. Close the system settings window and the Xlite main window. Be careful, Xlite likes to 'close' to the system tray. If you see a yellow box like this (the red ring is just to highlight the icon, ok, don't complain yours doesn't have a red ring around it... sheeesssh some people).


 

 


Xlite is still running, right click on it and select Exit. Xlite is now ready for use with Asterisk, but Asterisk isn't quite ready for Xlite just yet...

 


Continue...->