Asterisk: The Definitive Guide, 4th Edition

Chapter 4. Initial Configuration Tasks

Careful. We don’t want to learn from this.

—Calvin & Hobbes

In the last chapter, we covered how to install Asterisk. But where should you get started with configuration? That is the question this chapter answers. There are a few common configuration files that are relevant regardless of what you are using Asterisk to accomplish. In some cases they may not require any modification, but you need to be aware of them.

asterisk.conf

The asterisk.conf configuration file allows you to tweak various settings that can affect how Asterisk runs as a whole.

There is a sample asterisk.conf file included with the Asterisk source. It is not necessary to have this file in your /etc/asterisk folder to have a working system, but you may find that some of the possible options will be of use to you.

Note

Asterisk will look for asterisk.conf in the default configuration location, which is usually /etc/asterisk. To specify a different location for asterisk.conf, use the -C command-line option:

$ asterisk -C /custom/path/to/asterisk.conf

The [directories] Section

For most installations of Asterisk, changing the directories is not necessary. However, this can be useful for running more than one instance of Asterisk at the same time, or if you would like files stored in nonstandard locations.

The default directory locations and the options you can use to modify them are listed in Table 4-1. For additional information about the usage of these directories, see File Structure in Chapter 2.

Note

The [directories] header in the sample asterisk.conf contains a (!) that marks it as a template (meaning changes under this header will not take effect). To make the changes under [directories] take effect, remove the (!). See sip.conf for a tip on using templates.

Table 4-1. asterisk.conf [directories] section

Option	Value/Example	Notes
astetcdir	/etc/asterisk	The location where the Asterisk configuration files are stored.
astmoddir	/usr/lib/asterisk/modules	The location where loadable modules are stored.
astvarlibdir	/var/lib/asterisk	The base location for variable state information used by various parts of Asterisk. This includes items that are written out by Asterisk at runtime.
astdbdir	/var/lib/asterisk	Asterisk will store its internal database in this directory as a file called astdb.
astkeydir	/var/lib/asterisk	Asterisk will use a subdirectory called keys in this directory as the default location for loading keys for encryption.
astdatadir	/var/lib/asterisk	This is the base directory for system-provided data, such as the sound files that come with Asterisk.
astagidir	/var/lib/asterisk/ agi-bin	Asterisk will use a subdirectory called agi-bin in this directory as the default location for loading AGI scripts.
astspooldir	/var/spool/asterisk	The Asterisk spool directory, where voicemail, call recordings, and the call origination spool are stored.
astrundir	/var/run/asterisk	The location where Asterisk will write out its Unix control socket as well as its process ID (PID) file.
astlogdir	/var/log/asterisk	The directory where Asterisk will store its logfiles.

The [options] Section

This section of the asterisk.conf file configures defaults for global runtime options. The available options are listed in Table 4-2. Most of these are also controllable via command-line parameters to the asterisk application. For a complete list of the command-line options that relate to these options, see the Asterisk manpage:

$ man asterisk

Table 4-2. asterisk.conf [options] section

Option	Value/Example	Notes
verbose	3	Sets the default verbose setting for the Asterisk logger. This value is also set by the -v command-line option. The verbose level is 0 by default.
debug	3	Sets the default debug setting for the Asterisk logger. This value is also set by the -d command-line option. The debug level is 0 by default.
alwaysfork	yes	Forking forces Asterisk to always run in the background. This option is set to no by default.
nofork	yes	Forces Asterisk to always run in the foreground. This option is set to no by default.
quiet	yes	Quiet mode reduces the amount of output seen at the console when Asterisk is run in the foreground. This option is set to no by default.
timestamp	yes	Adds timestamps to all output except output from a CLI command. This option is set to no by default.
execincludes	yes	Enables the use of #exec in Asterisk configuration files. This option is set to no by default.
console	yes	Runs Asterisk in console mode. Asterisk will run in the foreground and will present a prompt for CLI commands. This option is set to no by default.
highpriority	yes	Runs the Asterisk application with realtime priority. This option is set to no by default.
initcrypto	yes	Loads keys from the astkeydir at startup. This option is set to no by default.[a]
nocolor	yes	Suppresses color output from the Asterisk console. This is useful when saving console output to a file. This option is set to no by default.
dontwarn	yes	Disables a few warning messages. This option was put in place to silence warnings that are generally correct but may be considered to be so obvious that they become an annoyance. This option is set to no by default.
dumpcore	yes	Tells Asterisk to generate a core dump in the case of a crash. This option is set to no by default.[b]
languageprefix	yes	Configures how the prompt language is used in building the path for a sound file. By default, this is yes, which places the language before any subdirectories, such as en/digits/1.gsm. Setting this option to no causes Asterisk to behave as it did in previous versions, placing the language as the last directory in the path (e.g., digits/en/1.gsm).
internal_timing	yes	Uses a timing source to synchronize audio that will be sent out to a channel in cases such as file playback or music on hold. This option is set to yes by default and should be left that way; its usefulness has greatly diminished over the last few major versions of Asterisk.
systemname	my_ system _name	Gives this instance of Asterisk a unique name. When this has been set, the system name will be used as part of the uniqueid field for channels. This is incredibly useful if more than one system will be logging CDRs to the same database table. By default, this option is not set.
autosystemname	yes	Automatically sets the system name by using the hostname of the system. This option is set to no by default.
mindtmfduration	80	Sets the minimum duration of DTMF messages. If Asterisk receives a DTMF message with a duration less than this minimum amount, the duration value of the DTMF message will be changed to the amount configured by this option.
maxcalls	100	Sets a maximum number of simultaneous inbound channels. No limit is set by default.
maxload	0.9	Sets a maximum load average. If the load average is at or above this threshold, Asterisk will not accept new calls. No threshold is set by default.
maxfiles	1000	Sets the maximum number of file descriptors that Asterisk is allowed to have open. The default limit imposed by the system is commonly 1024, which is not enough for heavily loaded systems. It is common to set this limit to a very high number. By default, a system-imposed limit is used.[c]
minmemfree	1	Sets the minimum number of megabytes of free memory required for Asterisk to continue accepting calls. If Asterisk detects that there is less free memory available than this threshold, new calls will not be accepted. This option is not set by default.
cache_record_files	yes	When doing recording, stores the file in the record_cache_dir until recording is complete. Once complete, it will be moved into the originally specified destination. The default for this option is no.
record_cache_dir	/tmp	Sets the directory to be used when cache_record_files is set to yes. The default location is a directory called tmp within the astspooldir.
transmit_silence	yes	Transmits silence to the caller in cases where there is no other audio source. This includes call recording and the Wait() family of dialplan applications, among other things. The default for this option is no.[d]
transcode_via_sln	yes	When building a codec translation path, forces signed linear to be one of the steps in the path. The default for this option is yes.
runuser	asterisk	Sets the system user that the Asterisk application should run as. This option is not set by default, meaning that the application will continue to run as the user that executed the application.
rungroup	asterisk	Sets the system group that the Asterisk application should run as. This option is not set by default.
lightbackground	yes	When using colors in the Asterisk console, it will output colors that are compatible with a light-colored background. This option is set to no by default, in which case Asterisk uses colors that look best on a black background.
forceblackbackground	yes	In terminals with light-colored backgrounds, you can force Asterisk to set the background color to black in order for the colors on the console to show up correctly.
defaultlanguage	en	Sets the default language.
documentation_language	en_US	The built-in documentation for Asterisk applications, functions, and other things is included in an external XML document. This option specifies the preferred language for documentation. If it is not available, the default of en_US will be used.
hideconnect	yes	Setting this option to yes causes Asterisk to not display notifications of remote console connections and disconnections at the Asterisk CLI. This is useful on systems where there are scripts that use remote consoles heavily. The default setting is no.
lockconfdir	no	When this option is enabled, the Asterisk configuration directory will be protected with a lock. This helps protect against having more than one application attempting to write to the same file at the same time. The default value is no.
stdexten	gosub	When using users.conf, the hasvoicemail=yes option invokes a stdexten routine. In Asterisk 1.4, this would be done using a macro, but in later versions of Asterisk it uses a GoSub (the preferred method since Asterisk 1.6.0). This option is used for backwards compatibility.
[a] If any of the keys require a passphrase, it will block Asterisk’s startup process. An alternative is to run keys init at the Asterisk command line. [b] This is critical for debugging crashes. However, Asterisk must be compiled with the DONT_OPTIMIZE option enabled in menuselect for the core dump to be useful. [c] In order to determine what the current value is, you can run:$ sudo cat /proc/`pidof asterisk`/limitsIt will show you the various system set limits, including maximum number of open files. A good value for max open files is somewhere around “peak calls” multiplied by 5 (assuming 2 RTP and RTCP ports per channel, plus overhead). So if you were going to have 300 simultaneous calls, you would want at least 1,500 max open files. You can either set this with the asterisk.conf file using the maxfiles option, or you can set it with in the /etc/security/limits.conf file for your operating system. [d] It’s important to note that when this option is enabled, the silence is generated in uncompressed signed linear format, so it will have to be transcoded into the format that the caller’s channel expects. The result may be that transcoding is required for a call that would not normally require it.

The [files] Section

This section of asterisk.conf includes options related to the Asterisk control socket. It is primarily used by remote consoles (asterisk -r). The available options are listed in Table 4-3.

Table 4-3. asterisk.conf [files] section

Option	Value/Example	Notes
astctlpermissions	0660	Sets the permissions for the Asterisk control socket.
astctlowner	root	Sets the owner for the Asterisk control socket.
astctlgroup	apache	Sets the group for the Asterisk control socket.
astctl	asterisk.ctl	Sets the filename for the Asterisk control socket. The default is asterisk.ctl.

The [compat] Section

Occasionally, the Asterisk development team decides that the best way forward involves making a change that is not backward-compatible. This section contains some options (listed in Table 4-4) that allow reverting behavior of certain modules back to previous behavior.

Table 4-4. asterisk.conf [compat] section

Option	Value/Example	Notes
pbx_realtime	1.6	In versions earlier than Asterisk 1.6.x, the pbx_realtime module would automatically convert pipe characters into commas for arguments to Asterisk applications. This is no longer done by default. To enable this previous behavior, set this option to 1.4.
res_agi	1.6	In versions earlier than Asterisk 1.6.x, the EXEC AGI command would automatically convert pipe characters into commas for arguments to Asterisk applications. This is no longer done by default. To enable this previous behavior, set this option to 1.4.
app_set	1.6	Starting with the Asterisk 1.6.x releases, the Set() application only allows setting the value of a single variable. Previously, Set() would allow setting more than one variable by separating them with a &. This was done to allow any characters in the value of a variable, including the & character, which was previously used as a separator. MSet() is a new application that behaves like Set() used to. However, setting this option to 1.4 makes Set() behave like MSet().

modules.conf

This file is not strictly required in an Asterisk installation; however, without any modules Asterisk won’t really be able to do anything, so for all practical purposes, you need a modules.conf file in your /etc/asterisk folder. If you simply define autoload=yes in your modules.conf file, Asterisk will search for all modules in the /usr/lib/asterisk/modules folder and load them at startup.

Although most modules do not use much in the way of resources, and they all load very quickly, it just seems cleaner to our minds to load only those modules that you are planning on using in your system. Additionally, there are security benefits to not loading modules that accept connections over a network.

In the past we felt that explicitly loading each desired module was the best way to handle this, but we have since found that this practice creates extra work. After every upgrade we found ourselves having to edit the modules.conf file to correct all the module differences between releases, and the whole process ended up being needlessly complicated. What we prefer to do these days is to allow Asterisk to automatically load the modules that it finds, but to explicitly tell Asterisk not to load any modules we do not want loaded by use of the noload directive. A sample modules.conf file can be found in modules.conf.

Using menuselect to Control Which Modules Are Compiled and Installed

One other way that you can control which modules Asterisk loads is to simply not compile and install them in the first place. During the Asterisk installation process, the make menuselect command provides you with a menu interface that allows you to specify many different directives to the compiler, including which modules to compile and install. If you never compile and install a module, the effect of this at load time is that it won’t exist, and therefore won’t be loaded. If you are new to Linux and Asterisk, this may create confusion for you if you later want to use a module and discover that it doesn’t exist on your system.

More information about menuselect is available in make menuselect.

The [modules] Section

The modules.conf file contains a single section. The options available in this section are listed in Table 4-5. With the exception of autoload, all of the options may be specified more than once.

Note

A list of all loadable modules is available in Chapter 2, with notes on our opinions regarding the popularity/status of each of them.

Table 4-5. modules.conf [modules] section

Option	Value/Example	Notes
autoload	yes	Instead of explicitly listing which modules to load, you can use this directive to tell Asterisk to load all modules it finds in the modules directory, with the exception of modules listed as not to be loaded using the noload directive. The default, and our recommendation, is to set this option to yes.
preload	res_odbc.so	Indicates that a module should be loaded at the beginning of the module load order. This directive is much less relevant than it used to be; modules now have a load priority built into them that solves the problems this directive was previously used to solve.
load	chan_sip.so	Defines a module that should be loaded. This directive is only relevant if autoload is set to no.
noload	chan_alsa.so	Defines a module that should not be loaded. This directive is only relevant if autoload is set to yes.
require	chan_sip.so	Does the same thing as load; additionally, Asterisk will exit if this module fails to load for some reason.
preload-require	res_odbc.so	Does the same thing as preload; additionally, Asterisk will exit if this module fails to load for some reason.

indications.conf

The sounds that people expect from the telephone network vary in different parts of the world. Different countries or regions present different sounds for events such as dialtone, busy signal, ringback, congestion, and so forth.

The indications.conf file defines the parameters for the various sounds that a telephone system might be expected to produce, and allows you to customize them. In the early days of Asterisk, this file only contained sounds for a limited number of countries, but it is now quite comprehensive.

To assign the tones common for your region to channels, you can simply assign the tonezone using the CHANNEL() function, and that tonezone will apply for the duration of the call (unless changed later):

Set(CHANNEL(tonezone)=[yourcountry]) ; i.e., uk, de, etc.

However, since signaling from a call could come from various places (from the carrier, from Asterisk, or even from the set itself), you should note that simply setting the tonezone in your dialplan does not guarantee that those tones will be presented in all situations.

Hacking indications.conf for Fun and Profit

If you have too much time on your hands, you can do all sorts of pointless but entertaining things with your indications. For example, fans of Star Wars can make the following change to the end of their indications.conf files:

[starwars](us)
description = Star Wars Theme Song
ring = 262/400,392/500,0/100,349/400,330/400,294/400,524/400,392/500,0/100,
       349/400,330/400,294/400,524/400,392/500,0/100,349/400,330/400,349/400,
       294/500,0/2000

If you then use the country named 'starwars' in your configuration files or dialplan, any ringing you pass back will sound quite different from the standard ring you are used to. Try the following dialplan code to test out your new ringing sound:

exten => 500,1,Answer()
    same => n,Set(CHANNEL(tonezone)=starwars)
    same => n,Dial(SIP/0000FFFF0002) ; or whatever your channel 
                                     ; is named in sip.conf

Note

Depending on the type of device used to call into this example, you may wonder if it will actually work. SIP phones, for example, typically generate their own tones instead of having Asterisk generate them. This example was carefully crafted to ensure that Asterisk will generate a ringback tone to the caller. The key is the Answer() that is executed first. Later, when an outbound call is made to another device, the only method Asterisk has available to pass back a ringing indication to the caller is by generating inband audio, since as far as the caller’s phone is concerned, this call has already been answered.

While Asterisk will run without an indications.conf file, it is strongly recommended that you include one: copy the sample over with sudo cp ~/src/asterisk-complete/11/configs/indications.conf.sample, modify the country parameter in the [general] section to match your region, and restart Asterisk.

chan_dahdi Ignores indications.conf

DAHDI does not use the indications.conf file from Asterisk, but rather has the tones compiled in. For more information, see Chapter 7.

If your system supports multiple countries (for example, if you have a centralized Asterisk system that has users from different regions), you may not be able to simply define the default country. In this case, you have a couple of options:

1. Define the country in the channel definition file for the user.

2. Define the country in the dialplan using the CHANNEL(tonezone) function.

For more information about using Asterisk in different countries, see Chapter 9.

musiconhold.conf

If you plan on selling Asterisk-based telephone systems and you do not change the default music on hold that ships with Asterisk, you are sending the message, loud and clear, that you don’t really know what you are doing.

Tip

Sometimes it’s nearly impossible to find a set of hold music files that can satisfy your customers requirements. Alternatively, you can just play beep tones instead of music. One website that has a free copy of a beep tone is http://www.university-music-on-hold.com/.

Part of the problem with music on hold (MOH) is that while in the past it was common to just plug a radio or CD player into the phone system, the legal reality is that most music licenses do not actually allow you to do this. That’s right: if you want to play music on hold, somebody, somewhere, typically wants you to pay them for the privilege.

So how should you deal with this? There are two legal ways: 1) pay for a music on hold license from the copyright holder, or 2) find a source of music that is released under a license suitable for Asterisk.

We’re not here to give you legal advice; you are responsible for understanding what is required of you in order to use a particular piece of music as your music on hold source. What we will do, however, is show you how to take the music you have and make it work with Asterisk.

Getting Free Music

There are several websites that offer music that has been released under Creative Commons or other licenses. Lately, we’ve been enjoying music from Jamendo. Each song may have its own licensing requirements, and just because you can download a song for free does not mean you have permission to use it as music on hold. Be aware of the licensing terms for the music you are planning to use for your music on hold.

Converting Music to a Format That Works Best with Asterisk

It’s quite common to have music in MP3 format these days. While Asterisk can use MP3s as a music source, this method is not at all ideal. MP3s are heavily compressed, and in order to play them the CPU has to do some serious work to decompress them in real time. This is fine when you are only playing one song and want to save space on your iPod, but for music on hold, the proper thing to do is convert the MP3 to a format that is easier on the CPU.

RHEL Prerequisite

Since RHEL does not have MP3 capability installed with sox, you will have to install mpg123 before you can convert MP3 files for use with Asterisk.

First you will need to install the rpmforge repository. To find out which version you need, open your web browser and go to http://repoforge.org/use/. Select the text for the version/architecture you want to install and paste it into your shell:

$ rpm -Uhv http://pkgs.repoforge.org/rpmforge-release/\
                                     rpmforge-release-....rpm

Once the repository has been added, you can proceed to get mpg123:

$ yum install mpg123

Once that’s done, your RHEL system is ready to convert MP3 files for use with Asterisk.

If you are familiar with the file formats and have some experience working with audio engineering software such as Audacity, you can convert the files on your PC and upload them to Asterisk. We find it is simpler to upload the source MP3 files to the Asterisk server (say, to the /tmp folder), and then convert them from the command line.

To convert your MP3 files to a format that Asterisk understands, you need to run the commands outlined here (in this example we are using a file named SilentCity.mp3).

RHEL

First, convert the MP3 file to a WAV file:

$ mpg123 -w SilentCity.wav SilentCity.mp3

Then, downsample the resulting WAV file to a sampling rate that Asterisk understands:

$ sox SilentCity.wav -t raw -r 8000 -s -2 -c 1 SilentCity.sln

Tip

If you don’t have sox installed yet, you can do so with yum install sox.

Ubuntu

If you have not done so already, install sox, and the libsox-fmt-all package:

$ sudo apt-get install sox libsox-fmt-all

Then, convert your MP3 file directly to the uncompressed SLN format:

$ sox SilentCity.mp3 -t raw -r 8000 -s -2 -c 1 SilentCity.sln

Note

In previous versions of sox (e.g., versions before 14.3.0), the -2 option was previously -w.

Completing file conversion

The resulting file will exist in the /tmp folder (or wherever you uploaded to) and needs to be copied to the /var/lib/asterisk/moh folder:

$ cp *.sln /var/lib/asterisk/moh

You now need to reload musiconhold in Asterisk in order to have it recognize your new files:

$ asterisk -rx "module unload res_musiconhold.so"
$ asterisk -rx "module load res_musiconhold.so"

To test that your music is working correctly, add the following to the [UserServices] context in your dialplan:

exten => 664,1,NoOp()
    same => n,Progress()
    same => n,MusicOnHold()

Dialing 664 from one of your sets should play a random file from your moh directory.

Default musiconhold.conf file

Let’s look at the basic musiconhold.conf file that comes in the sample files with Asterisk. We’ve cleaned it up a bit, but this file can be dropped into your /etc/asterisk directory to enable the basic music on hold functionality.

Note

You’ll need to install some music on hold files, which is enabled in menuselect by default, before you’ll get any music.

This is what the default file contains:

[general]

[default]
mode=files
directory=moh

In the next couple of sections, we’ll review what other options are available in the musiconhold.conf file.

The [general] section

The [general] section only has a single option (as shown in Table 4-6), and it is only useful when loading music on hold from realtime (see Dynamic Realtime for information about the extconfig.conf and dynamic realtime functionality).

Table 4-6. musiconhold.conf [general] section

Option	Value/Example	Notes
cachertclasses	yes	This option is used to tell Asterisk to cache realtime MOH classes into memory when they are loaded. The default value is no. Available values are yes or no.

The music on hold classes sections

Below the [general] section, you define classes of music on hold with a name between square braces; e.g., [jazz]. The following options, listed in Table 4-7, are available.

Table 4-7. musiconhold.conf classes sections

Option	Value/Example	Notes
mode	files	The mode determines how the music on hold class should behave. When the mode is set to files, then files are played from a directory on the filesystem (see the description of the directory option, below). If the mode is set to custom, then an application can be used to stream music rather than play it off the filesystem directly (see the description of the application option, below). Additional values include: quietmp3 Plays back MP3 files; must use the format_mp3 module, which can be enabled in the Add-Ons menu within menuselect mp3 Same as above, but a louder version mp3nb Same as above, but unbuffered quietmp3nb Same as quietmp3, but unbuffered
directory	moh	A directory name that specifies where the files exist. The path is relative to /var/lib/asterisk (or the path defined by astvarlibdir in asterisk.conf).
digit	#	If the digit option is defined for a MOH class, then when a caller is listening to MOH and they press this digit, then the MOH class will switch to the class that defines this digit.
announcement	queue-thankyou	If defined for a MOH class, then prior to music being played this announcement will be presented to the caller. It will also be presented when switching between music files. The most common scenario to use this is likely with queues. See Playing Announcements Between Music on Hold Files for more information.
sort	alpha	Allows sorting of the files to be played alphanumerically. If this option is not set, then the sort order will be undefined.
application	/usr/bin/streamplayer 172.16.0.100 888	When used in conjunction with mode=custom, you can define an application that will supply the audio to the channel when MOH is called.[a]
format	ulaw	If using a stream of audio from a remote location in conjunction with mode=custom and application, you can define what format Asterisk can expect to handle.
[a] This can be quite expensive if the application lives locally and is doing re-encoding of the file for every channel. If that is the case, then you’re best off converting your MOH files to a native format like ulaw and using mode=files.

Additional Configuration Files

Based on the modules that you installed during the installation phase (those that you selected in menuselect, compiled, and subsequently installed), you’ll have additional configuration files that you’ll need to add to the /etc/asterisk directory in order to get a clean start. To determine what files you might be missing, you can start Asterisk in the foreground with the asterisk -c command.

Once you’ve started Asterisk in the foreground, you’ll see output similar to the following:

[ Initializing Custom Configuration Options ]
Unable to load config file 'acl.conf'
Unable to open AMI configuration manager.conf, or configuration is invalid. 
Asterisk management interface (AMI) disabled.
Unable to load config file 'udptl.conf'
Could not reload udptl config
Could not load features.conf
Could not find valid ccss.conf file. Using cc_max_requests default
Could not find valid ccss.conf file. Using cc_[state]_devstate defaults
130 modules will be loaded.
...Unable to load config res_stun_monitor.conf
Unable to load config smdi.conf: SMDI disabled
No SMDI interfaces are available to listen on, not starting SMDI listener.

If we look at our output, we can see we’re missing the following configuration files: acl.conf, manager.conf, udptl.conf, features.conf, ccss.conf, res_stun_monitor.conf, and smdi.conf.

To get started with a full set of configuration files, we’ll often copy in from the sample directory the base set of files, and then go back and modify them as appropriate. This is often the quickest way to get going with a full set of configuration data, but without the bulk of using something like make samples. An example command that we might run in bash could be:

$ cd ~/src/asterisk-complete/asterisk/11
$ for f in acl manager udptl features ccss res_stun_monitor smdi; do
cp configs/$f.conf.sample /etc/asterisk/$f.conf;
done

From here, we can start Asterisk and validate that we’re starting clean.

Conclusion

This chapter helped you complete some initial configuration of Asterisk. From here you can move on to setting up some phones and taking advantage of the many features Asterisk has to offer.