5.5. Adding Phone Extensions to Asterisk and Making Calls

Problem

Playing around on the Asterisk server is fun, but you're ready to set up some user accounts and make real phone calls. How do you set this up?

Solution

First, we'll set up some local user accounts including voicemail, and test them on the server. (In Recipe 5.6, we'll set up some softphones for some real calling.) You'll be editing these files on the Asterisk server:

/etc/asterisk/sip.conf
/etc/asterisk/extensions.conf
/etc/asterisk/voicemail.conf

The default files are huge and full of helpful comments, but rather a chore to edit, so let's move them out of the way:

	# mv sip.conf sip.conf.old
	# mv extensions.conf extensions.conf.old
	# mv voicemail.conf voicemail.conf.old

We'll create three users: Ellen Ripley, Sarah Connor, and Dutch Schaeffer. Create a new sip.conf with these entries. Note that semicolons are used to comment out lines, not hash marks:

	;;/etc/asterisk/sip.conf;;
	[general]
	context=default
	port=5060
	bindaddr=0.0.0.0
	disallow=all
	allow=gsm
	allow=ulaw
	allow=alaw

	[ellenr]
	;Ellen Ripley
	type=friend
	username=ellenr
	secret=4545
	host=dynamic
	context=local-users

	[sarahc]
	;Sarah Connor
	type=friend
	username=sarahc
	secret=5656
	host=dynamic
	context=local-users

	[dutchs]
	;Dutch Schaeffer
	type=friend
	username=dutchs
	secret=6767
	host=dynamic
	context=local-users

Then, create a new extensions.conf with these entries:

	;;/etc/asterisk/extensions.conf;;
	[general]
	autofallthrough=yes
	clearglobalvars=yes

	[globals]
	CONSOLE=Console/dsp

	[default]
	;no entries yet

	[local-users]
	exten => 250,1,Dial(SIP/ellenr,10)
	exten => 250,2,VoiceMail(250@local-vm-users,u)

	exten => 251,1,Dial(SIP/sarahc,10)
	exten => 251,2,VoiceMail(251@local-vm-users,u)

	exten => 252,1,Dial(SIP/dutchs,10)
	exten => 252,2,VoiceMail(252@local-vm-users,u)

	;Internal users can call each other directly with their 3-digit extensions:
	exten => _2XX,1,Dial(SIP/${EXTEN},30)
	exten => _2XX,n,Voicemail(${EXTEN})
	exten => _2XX,n,Hangup

	;retrieve messages by dialing ext. 550
	exten => 550,1,VoiceMailMain(@local-vm-users)

Finally, set up voicemail boxes in voicemail.conf:

	;;/etc/asterisk/voicemail.conf;;
	[general]
	format=wav49
	skipms=3000
	maxsilence=10
	silencethreshold=128
	maxlogins=3

	[local-vm-users]
	;mailbox number, password, username
	250 => 1234,Ellen Ripley
	251 => 3456,Sarah Connor
	252 => 4567,Dutch Schaeffer

Load the new configurations, then make some calls:

	asterisk1*CLI> reload
	asterisk1*CLI> dial 250@local-vm-users
	asterisk1*CLI> console hangup

You'll see a lot of console output between these commands, and hear voice prompts that tell you what to do. Leave some voicemail messages, then retrieve them like this example for Ellen, who is at extension 250. You will be prompted for the mailbox number and password:

	asterisk1*CLI> dial 550
	asterisk1*CLI> dial 250
	asterisk1*CLI> dial 1234
	asterisk1*CLI> console hangup

Follow the prompts to listen to the messages. Remember, you have to use the dial command every time you need to enter some numbers. When everything works, you're ready to install and use some softphones.

Discussion

Type help at the Asterisk CLI to see the current command set. The READMEs, changes, and UPGRADE.txt files in the source tarballs are full of useful information, and will tell you what has changed between releases.

A verbosity of 3 (asterisk -rvvv) is just right for monitoring call activities on the server. If there are any errors, you can see them live. Console output and /var/log/asterisk/messages are the same.

sip.conf

This file defines all the SIP channels you'll be using. This is where you set up internal users and external trunks. It also contains options for selecting hold music, NAT firewall tweaks, codecs, jitter buffering, and proxies.

The [general] section includes global constants.

port=5060 is the standard SIP port. Don't change this.

bindaddr=0.0.0.0 means listen on all interfaces. You may change this if your Asterisk server has more than one network interface.

Codecs (coder/decoders) convert analog signals to digital formats. In sip.conf and iax.conf, you must first deny all codecs with disallow=all, then specify the ones you wish to allow in order of preference. Which ones do you allow? This depends on what people calling your network use, what your service provider requires (if you have one), and your own requirements for your network. Any incoming call that uses a codec your server does not support will be transcoded into a format that your server does support. This incurs a CPU hit, and might cause some voice-quality problems. It's most efficient to use the same codec from endpoint to endpoint, though that may not always be possible.

This list shows the most commonly used Asterisk-supported voice codecs and the correct configuration file syntax:

	Codec name = configuration file entry
	G.711u ulaw = ulaw
	G.711a alaw = alaw
	G.726 = g726
	G.729 = g729
	GSM = gsm
	iLBC = ilbc
	LPC10 = lpc10
	Speex = speex

VoIP codecs are compromises between bandwidth and CPU usage. Compressed codecs require less bandwidth, but at a cost of more CPU cycles. Less compression = less CPU and more bandwidth:

G.711u/a: G.711 ulaw is used in the U.S. and Japan, while G.711 alaw is used the rest of the world. It is a high-quality companded codec; this is the native language of the modern digital telephone phone network, and is almost universally supported in VoIP networks and devices. A T1 trunk carries 24 digital PCM (Pulse Code Modulation) channels, and the European E1 standard carries 30 channels. It requires less CPU power, but consumes more bandwidth. It runs at a fixed bitrate of 64 Kbps per call each way, plus around 20 Kbps for packet headers. G.711 has an open source license, and delivers the best voice quality and least latency.
G.726: G.726 runs at several different bitrates: 16, 24, or 32, and don't forget an additional 20 Kbps or so for headers. 32 Kbps is the most common, and the only one supported by Asterisk. It's easy on CPU usage, has good voice quality, and has an open source license. G.726 is becoming more popular and is supported on most VoIP devices.
G.729: A high-quality compressed proprietary codec that is easy on bandwidth, with a bitrate of 8 Kbps.(Add about 20 Kbps for headers.) The price for this is more CPU cycles. For example, AstLinux on a Soekris 48xx board can handle about eight concurrent G.711 calls, but only two G.729 calls. Plus, there are patent encumbrances—using G.729 on Asterisk requires a licensing fee of $10 per channel, which you can purchase from Digium.
GSM: GSM stands for Global System for Mobile communications, which is a cellular phone system standard. It includes a voice codec, and that is the bit that Asterisk uses. It is proprietary, but royalty-free, so anyone can use it. It has a bitrate of 13 Kbps, and uses about 30 Kbps total. GSM delivers acceptable voice quality. (GSM is also the file format of the free voice prompts included with Asterisk.) There are three flavors of the GSM codec. The royalty-free edition is also known as GSM Full-Rate. There are two newer versions that are patent-encumbered: Enhanced Full Rate (EFR) and Half Rate (HR).
iLBC: iLBC is designed for low-bandwidth high-packet loss networks. It has better voice quality than G.729 for about the same computational price, and it uses a total of about 20–30 Kbps per call each way. Its special strength is graceful degradation over poor-quality networks, so even with packet losses as high as 10 percent, it still sounds good. It is free of cost, and comes with a liberal license that allows modifications.
LPC-10: This delivers low but clear voice quality, or, as the sample iax.conf files says "disallow=lpc10; Icky sound quality… Mr. Roboto." Developed by the U.S. Department of Defense, its main virtue is very low bandwidth and CPU requirements; it uses as little as 2.5 Kbps per call, and you can stuff up to three times as many calls over the wires as you can with GSM. So, don't forget that Asterisk supports it—you just may find yourself in a situation where it will be useful. (OK, so most desert islands don't have Internet. But you never know.)
Speex: Speex is a high-quality, BSD-style licensed, dynamically variable bitrate codec that was developed as an alternative to restrictive patent-encumbered codecs. It is very flexible, and can be manually fine-tuned in /etc/asterisk/codecs.conf. Its one drawback is it's the most computationally expensive of the codecs. It has an active developer and user community, and is finding widespread acceptance, so it's bound to continue to improve.

The default sip.conf uses phone names instead of people names for the human user extensions. I prefer to name them for the users. There are three types of users: Peers, Users, and Friends. Peers and Users have different sets of privileges, and Friends get all privileges. See the default extensions.conf for details.

"Username" and "secret" are the login and password that users will use in their softphone configurations to register the phone with the server.

Using host=dynamic tells the server that the phone needs to be registered. This happens every time you start or restart your phone. Then, a timeout is negotiated each time a device registers, usually 3,600 seconds (60 minutes). The device must reregister, or Asterisk removes the registry entry.

You need to name a default context for each user; this tells Asterisk where to start in the dialplan to process calls for each user. This is a nice mechanism for providing different sets of privileges for different groups of users.

Dialplans

extensions.conf is the heart of your Asterisk server because it contains your dialplan. A dialplan has four elements—extensions, contexts, priorities, and applications:

Extensions

The word extensions is a bit unfortunate because it sounds like plain old numbered telephone phone extensions. But Asterisk extensions are sturdy little workhorses that do all kinds of things. Extension syntax looks like this:

	exten => name,priority,application( )

Names can be words or numbers. Usually, multiple extensions are required to handle a single call; these are called contexts.

Contexts

Named groups of extensions are called contexts. Each context is a separate unit, and does not interact with other contexts unless you configure it to do so, with the include directive.

Priorities

You must always specify a number one priority; this is the first command Asterisk follows when processing a call.

Applications

Asterisk comes with a large assortment of applications; these are built-in Asterisk commands. You can see a list of applications by running the core list applications command on the Asterisk console.

The extensions.conf file has these sections:

	[general]
	[globals]
	[contexts]

[general] and [globals] are special reserved words, so don't change them. [contexts] are named whatever you want.

The [general] context contains system-wide variables. In this recipe, autofallthrough=yes terminates calls with BUSY, CONGESTION, or HANGUP in case the configuration is not clear on what the next step is supposed to be.

clearglobalvars=yes means that variables will be cleared and reparsed on an extensions reload or Asterisk reload. Otherwise, global variables will persist through reloads, even if they are deleted from extensions.conf.

Global constants are set in the [globals] section, such as dialplan and environment values. CONSOLE=Console/dsp sets the default sound device.

Now, we get into the good stuff: user-defined contexts. Contexts define call routing and what users can do. The [local-users] context in this recipe defines the extension numbers for our users, and does their call routing. These examples are as simple as they can be—dial the extension numbers, and if no one answers, you are sent to the appropriate voicemail context. The u voicemail option means "play the unavailable message when no one answers."

The underscores in extensions mean wildcards ahead. In the example that allows users to call each other by their three-digit extensions, the first number dialed must be 2, then the next two numbers dialed are matched to existing extensions. EXTEN is a channel variable that passes in the numbers you dial.

Sequence in contexts is very important—the steps must be numbered or listed in order (you can use "n" for "next" to do so). Using numbered priorities lets you jump around to different priorities, as you'll see later in this chapter.

Extension 550 is configured in the recipe to be the number users dial to retrieve voicemail. You may use any number you want. The recipe uses the VoiceMailMain application, which is Asterisk's built-in voicemail retrieval application, and points to the appropriate voicemail context. When you have more than one voicemail context, you need to specify the correct one, like in the recipe with @local-vm-users:

voicemail.conf: The [general] section defines global constants.
format: The options for this are wav49, gsm, and wav. Voicemails will be recorded in as many formats as you name here. Asterisk will choose the optimum format for playback. If you want to attach voicemail messages to email, use wav49. wav49 is identical to gsm; the difference is it has Microsoft Windows-friendly headers, which makes the file readable to virtually all client software. It creates files about one-tenth the size of WAVE files.

WAVE files are huge because they are uncompressed, but they deliver the best sound quality.