Setting up Asterisk and SPA-3000

Asterisk has a bit of a reputation of being difficult to setup. There are LiveCD versions which provide GUI front ends which are meant to be much easier, but I didn't want to dedicate a box purely to Asterisk. Google finds lots of references to setting up Asterisk and even some which describe using it with a SPA-3000, but I didn't find any that were that easy to understand. I don't know if the following will be an easier, but if nothing else it will add a bit more information.

Note: I don't claim to be an expert at Asterisk configuration. So please also read documentation where you can find it. For all I know, you'll create security holes by following these instructions - If you do see any security problems please let me know :-)

The following describes what I ended up doing to achieve the following fairly simple goals:

Probably one of the most daunting aspects of configuring Asterisk is the number of configuration files which are in /etc/asterisk. It turned out for what I needed to do that I only needed to edit a handful of them.

For reference, I set this up on an Ubuntu Dapper installation with the following packages installed:

Asterisk is installed on my firewall box, so there are no NAT related issues in my configuration. There are most likely better ways to configure and debug Asterisk than what I describe below, but its what worked for me, and what was easy to glean from the documentation I could find.

Useful references

The most useful website I found for documentation about Asterisk was the wiki at voip-info.org. It has both descriptions about basic voip concepts as well as reference type information on the various Asterisk configuration files.

There is also a very good book Asterisk: The Future of Telephone available online.

Useful debugging info

I'd recommend attaching to the Asterisk console when setting up and debugging Asterisk. 


# asterisk -r
Asterisk 1.2.7.1, Copyright (C) 1999 - 2006 Digium, Inc. and others.
Created by Mark Spencer 
Asterisk comes with ABSOLUTELY NO WARRANTY; type 'show warranty' for details.
This is free software, with components licensed under the GNU General Public
License version 2 and other licenses; you are welcome to redistribute it under
certain conditions. Type 'show license' for details.
=========================================================================
Connected to Asterisk 1.2.7.1 currently running on enterprise (pid = 3870)
Verbosity is at least 3
enterprise*CLI>

The sip related commands are especially useful to inspect the state of connections.

The reload command reloads the configuration files. Its worth carefully checking the verbose output of this command for a report of any errors in the config files as they're dispersed through the output rather than summarised at the end.

The log files in /var/log/asterisk, namely messages and cdr-csv/Master.csv are also worth monitoring to see what is going on inside Asterisk.

Editing sip.conf to allow the SPA-3000 to connect for outgoing calls

To the [general] section I set the realm to my domain name and :

realm=yeoh.info

Add a SIP account for the SPA-3000 to connect (under the 'Definitions of locally connected SIP phones' section). Username is spa3000, password is foo.


[spa3000]
mailbox=3000                    ; Mailbox number (numerical so can be selected through phone)
type=friend
host=dynamic
secret=foo
call-limit=2
disallow=all                    ; need to disallow=all before we can use allow=
allow=ulaw                      ; Note: In user sections the order of codecs
                                ; listed with allow= does NOT matter!
allow=alaw
allow=g723.1                    ; Asterisk only supports g723.1 pass-thru!
allow=g729                      ; Pass-thru only unless g729 license obtained
allow=gsm
context=local_phone             ; This links sip.conf with the 
				; entry local_phone in extensions.conf

Editing sip.conf to allow the softphones to connect for outgoing calls

I found it very useful when testing to have a few spare VoIP accounts and use softphones from my laptop to test the Asterisk setup. Using a softphone to connect to Asterisk can help determine whether a problem is on the SPA-3000 side or the Asterisk side. Accounts for softphones can be added in an identical manner (username chris, password foo):


[chris]
type=friend
host=dynamic
secret=foo
call-limit=2
disallow=all                    ; need to disallow=all before we can use allow=
allow=ulaw                      ; Note: In user sections the order of codecs
                                ; listed with allow= does NOT matter!
allow=alaw
allow=g723.1                    ; Asterisk only supports g723.1 pass-thru!
allow=g729                      ; Pass-thru only unless g729 license obtained
allow=gsm
context=local_phone

All the softphones (linphone, kphone, ekiga) I tried sucked (exhibited weird behaviour, crashed or got stuck often) in various ways but I ended up using linphone for most of the testing. Ekiga is prettier than the rest though.

Editing sip.conf to allow incoming PSTN calls (your normal phone line) to connect to Asterisk

If you can be bothered reading the SPA-3000 documentation, you'll discover that there are two logical VoIP units inside the box. One is used for connecting the handset to VoIP services and the other for the PSTN line to VoIP services. So if you want incoming PSTN calls to be handled by Asterisk, its necessary to create another account for the second VoIP unit (username pstn, password foo: 


[pstn]
type=friend
host=dynamic
secret=foo
call-limit=2
disallow=all                    ; need to disallow=all before we can use allow=
allow=ulaw                      ; Note: In user sections the order of codecs
                                ; listed with allow= does NOT matter!
allow=alaw
allow=g723.1                    ; Asterisk only supports g723.1 pass-thru!
allow=g729                      ; Pass-thru only unless g729 license obtained
allow=gsm
context=incoming

Setup the SPA-3000 for outgoing VoIP calls

There are lots of configuration settings for the SPA-3000, but I think the following are the major ones which need to be set. Using the advanced web menu configuration:

In the Line 1 tab:


Line Enable: Yes
Proxy: <IP Address of Asterisk Server>
Register: Yes
User ID: spa3000
Password: foo
Dial Plan: (9#x.|91747xxxxxxx|000S0<:@gw0>|106S0<:@gw0>|1[38]xxxxxxxxS0<:@gw0>|13[1-9]xxxS0<:@gw0>|1[9]xxxxxxxxS0<:@gw0>|0[23478]xxxxxxxxS0|[2-9]xxxxxxxS0|001xxxx.S5|xxx.<:@gw0>|*xx.|<*,:>xx.|<#,:><:@gw0>)

The dial plan syntax for the SPA-3000 is in the documentation. The dial plan above is pretty much the Internode recommended dial plan for their VoIP service with a couple of additions to access services on Asterisk and to use Sipphone as the VoIP provider. The extras at the front allow for calls starting with 9# and 91747 to be passed to asterisk for the purpose of accessing voicemail functionality and making SipPhone calls respectively. The 9 prefix is bad if valid phone numbers can start with 9 where you are. If you change it you'll need to make corresponding changes in the local_phone section of extensions.conf.

In the PSTN Line tab:


Line Enable: Yes
Proxy: <IP Address of Asterisk Server>
Register: Yes
User ID: pstn
Password: foo
Dial Plan 2: (S0<:192.168.1.1>)
PSTN-To-VoIP Gateway Enable: Yes
PSTN Ring Thru Line 1: Yes
PSTN CID For VoIP CID: Yes
PSTN Caller Default DP: 2

Editing sip.conf to outgoing VoIP calls from from Asterisk.

Configuration of SIP connections to VoIP services is done in a similar manner to the ATA and softphone ones.


[sip.internode.on.net]
   type=peer
   secret=yourInternodePassword
   username=yourInternodePhoneNumber
   host=sip.internode.on.net
   fromdomain=sip.internode.on.net
   fromuser=yourInternodePhoneNumber
   canreinvite=no
   insecure=very
   nat=no
   qualify=yes
   dtmfmode=rfc2833
   context=incoming               ; This connects incoming calls to the corresponding entry in extensions.conf
   disallow=all
   allow=g729
   allow=ulaw
   allow=alaw
   allow=g723.1                    ; Asterisk only supports g723.1 pass-thru!
   allow=g729                      ; Pass-thru only unless g729 license obtained
   allow=gsm

[sipphone]
   type=peer
   context=default
   disallow=all
   allow=ulaw
   allow=alaw
   allow=g723.1                 ; Asterisk only supports g723.1 pass-thru!
   allow=g729                   ; Pass-thru only unless g729 license obtained
   allow=gsm
   dtmfmode=rfc2833
   host=proxy01.sipphone.com
   fromdomain=proxy01.sipphone.com
   fromuser=yourSipphoneNumber
   insecure=very                
   secret=yourSipphonePassword
   username=yourSipphoneNumber
   canreinvite=no
   context=incoming             ; This connects incoming calls to the corresponding entry in extensions.conf
   nat=no

Yes, it seems odd to specify insecure=very in a configuration file of an application you don't want to be insecure, but I think this how its meant to work.

Editing sip.conf to allow incoming VoIP calls from VoIP providers.

Most of the Asterisk configuration files are full of comments which are often quite useful. However in some areas there is so much documentation that it hides the structure of the configuration syntax. Although its tempting to put the configuration information for incoming VoIP calls next to the configuration information for outgoing ones, it has to go in the [global] section. Put them next to the other example registrations.


; internode
register => XXXXXXXXXX:InternodePassword@sip.internode.on.net

; sipphone (chris)
; register => 1747YYYYYYY:SipPhonePassword@proxy01.sipphone.com
Replace XXXXXXXXXX with your internode phone number and 1747YYYYYYY with youre SipPhone phone number.

Add a voicemail box to voicemail.conf

Specify a mailbox to store voicemails into:


3000 => 1234,Chris and Kelly and Gizzy and Pipe,voicemail@localhost

where 1234 is the password for the mailbox.

Firewall configuration

By default asterisk will listen for udp packets on port 5060. My firewall configuration has a default of dropping packets not explicitly allowed so I added a rule to allow udp packets on the internal network side of the firewall to port 5060. This configuration mostly worked, but some sorts of calls (handset to sipphone account) would result in only one end being able to hear the audio.

I eventually realised that problems only occurred when Asterisk was doing codec conversions for a SIP client. It appears that when this occurs, the audio stream is transmitted on a different dynamically allocated udp port and the packets were being dropped by the firewall rules. I ended up allowing all udp packets from the internal network side of my firewall. Its probably possible to restrict the range.

Glueing everything together with extensions.conf

Its worth reading the wiki pages on extensions.conf as well as the pages on contexts and extensions as well as extension names and patterns.

The local_phone section handles the interpretation of the digits dialled from the SPA-3000 or softphone. It was specified as the context in the configuration sections for the SPA-3000 outgoing connection ([spa3000]) and softphone ([chris]). 


[local_phone]
; internode
; national/international
exten => _0XX.,1,Dial(SIP/${EXTEN}@sip.internode.on.net,200,r)
; local
exten => _6XXXXXXX,1,Dial(SIP/${EXTEN}@sip.internode.on.net,200,r)
; The local section is pretty much Canberra specific

; sipphone
exten => _91747XXXXXXX,1,Dial(SIP/${EXTEN:1}@proxy01.sipphone.com,200,r)

; Dialling 9#0 on the handset connects to the voicemail box
exten => 9#0,1,VoiceMailMain(s3000)

For incoming calls and voicemail:


[incoming]
exten => s,1,Dial(SIP/spa3000, 20)
exten => s,2,VoiceMail(u3000@default)

Asterisk will ring the handset connected to the SPA-3000 for 20 seconds before sending the call to voicemail box 3000. If you want you can do fancier things here. For example, you can have different greeting messages depending on whether the extension is engaged or if no one answers the phone in time.

Checking things are working

Well obviously you can make calls everything is ok. From a debugging point of view, the cdr-csv/Master.csv log file displays all incoming and outgoing calls. The Asterisk messages file can have useful information in it when things go wrong.

On the console running:


enterprise*CLI> sip show peers
Name/username              Host            Dyn Nat ACL Port     Status
pstn/pstn                  192.168.1.20     D          5061     Unmonitored
spa3000/spa3000            192.168.1.20     D   N      5060     Unmonitored
chris                      (Unspecified)    D   N      0        Unmonitored
sipphone/1747XXXXXXX       198.65.166.131              5060     Unmonitored
sip.internode.on.net/0261  203.2.134.1                 5060     OK (41 ms)
6 sip peers [6 online , 0 offline]

... shows all of the SIP peers. Note the line with chris has the host listed as (Unspecified). This means that the client (a softphone) is not currently registered.

On the console running:


enterprise*CLI> sip show registry
Host                            Username       Refresh State
proxy01.sipphone.com:5060       1747XXXXXXX        145 Registered
sip.internode.on.net:5060       026116XXXX          45 Registered

... indicates from which voip providers calls can currently come from.

TODO