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.
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.
asterisk -C /custom/path/to/asterisk.conf
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.
[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
[directories] take effect,
(!). See sip.conf for a tip on using
|The location where the Asterisk configuration files are stored.|
|The location where loadable modules are stored.|
|The base location for variable state information used by various parts of Asterisk. This includes items that are written out by Asterisk at runtime.|
|Asterisk will store its internal database in this directory as a file called astdb.|
|Asterisk will use a subdirectory called keys in this directory as the default location for loading keys for encryption.|
|This is the base directory for system-provided data, such as the sound files that come with Asterisk.|
|Asterisk will use a subdirectory called agi-bin in this directory as the default location for loading AGI scripts.|
|The Asterisk spool directory, where voicemail, call recordings, and the call origination spool are stored.|
|The location where Asterisk will write out its Unix control socket as well as its process ID (PID) file.|
|The directory where Asterisk will store its logfiles.|
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:
|Sets the default verbose setting for the Asterisk logger.
This value is also set by the -v command-line
option. The verbose level is |
|Sets the default debug setting for the Asterisk logger.
This value is also set by the -d command-line
option. The debug level is |
|Forking forces Asterisk to always run in the background.
This option is set to |
|Forces Asterisk to always run in the foreground. This
option is set to |
|Quiet mode reduces the amount of output seen at the
console when Asterisk is run in the foreground. This option is
set to |
|Adds timestamps to all output except output from a CLI
command. This option is set to |
|Enables the use of |
|Runs Asterisk in console mode. Asterisk will run in the
foreground and will present a prompt for CLI commands. This
option is set to |
|Runs the Asterisk application with realtime priority.
This option is set to |
|Loads keys from the |
|Suppresses color output from the Asterisk console. This
is useful when saving console output to a file. This option is
set to |
|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 |
|Tells Asterisk to generate a core dump in the case of a
crash. This option is set to |
|Configures how the prompt language is used in building
the path for a sound file. By default, this is |
|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 |
|Gives this instance of Asterisk a unique name. When this
has been set, the system name will be used as part of the
|Automatically sets the system name by using the hostname
of the system. This option is set to |
|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.|
|Sets a maximum number of simultaneous inbound channels. No limit is set by default.|
|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.|
|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]|
|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.|
|When doing recording, stores the file in the |
|/tmp||Sets the directory to be used when |
|Transmits silence to the caller in cases where there is
no other audio source. This includes call recording and the
|When building a codec translation path, forces signed
linear to be one of the steps in the path. The default for this
option is |
|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.|
|Sets the system group that the Asterisk application should run as. This option is not set by default.|
|When using colors in the Asterisk console, it will output
colors that are compatible with a light-colored background. This
option is set to |
|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.|
|Sets the default language.|
|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 |
|Setting this option to |
|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 |
|When using users.conf, the
[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
[c] In order to determine what the current value is, you
You can either set this with the asterisk.conf file using the
[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.
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.
|Sets the permissions for the Asterisk control socket.|
|Sets the owner for the Asterisk control socket.|
|Sets the group for the Asterisk control socket.|
|asterisk.ctl||Sets the filename for the Asterisk control socket. The default is asterisk.ctl.|
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.
|In versions earlier than Asterisk
1.6.x, the |
|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
|Starting with the Asterisk 1.6.x
releases, the |
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
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
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.
A list of all loadable modules is available in Chapter 2, with notes on our opinions regarding the popularity/status of each of them.
|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 |
|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.|
|Defines a module that should be loaded. This directive is
only relevant if |
|Defines a module that should not be loaded. This
directive is only relevant if |
|Does the same thing as |
|Does the same thing as |
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.
While Asterisk will run without an
indications.conf file, it is strongly
recommended that you include one: copy the sample over with
country parameter in the
[general] section to match your region,
and restart Asterisk.
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:
For more information about using Asterisk in different countries, see Chapter 9.
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.
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.
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.
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.
mpg123 -w SilentCity.wav SilentCity.mp3
sox SilentCity.wav -t raw -r 8000 -s -2 -c 1 SilentCity.sln
sudo apt-get install sox libsox-fmt-all
sox SilentCity.mp3 -t raw -r 8000 -s -2 -c 1 SilentCity.sln
cp *.sln /var/lib/asterisk/moh
asterisk -rx "module unload res_musiconhold.so"
asterisk -rx "module load res_musiconhold.so"
exten => 664,1,NoOp() same => n,Progress() same => n,MusicOnHold()
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.
This is what the default file contains:
[general] [default] mode=files directory=moh
[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
section, you define classes of music on hold with a name between
square braces; e.g.,
following options, listed in Table 4-7, are
|A directory name that specifies where the files exist.
The path is relative to /var/lib/asterisk
(or the path defined by |
|If the |
|If defined for a MOH class, then prior to music being
played this |
|Allows sorting of the files to be played alphanumerically. If this option is not set, then the sort order will be undefined.|
|When used in conjunction with |
|If using a stream of audio from a remote location in
conjunction with |
[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
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.