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.
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 in order 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:
$
sudo 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.
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 the File Structure section of Chapter 2.
Table 4-1. asterisk.conf [directories] 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 real-time 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. |
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 | Set 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. The default system-imposed limit is used by default. |
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 .[c] |
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. |
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 . |
[a] If any of the keys require a passphrase, this will block the startup process of Asterisk. 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 [c] There is an important caveat to note when this option is enabled. The silence is generated in uncompressed signed linear format, which means that 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.
Table 4-3. asterisk.conf [files] 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
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.
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 opinion regarding the popularity/status of each of them.
Table 4-5. modules.conf [modules] section
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 from
~/src/asterisk-complete/1.8/configs/indications.conf.sample,
modify the 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.[41]
Part of the problem with music on hold 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 to 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.
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).
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 -w -c 1 SilentCity.sln
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 -w -c 1 SilentCity.sln
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.
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.
[41] Note that Leif uses the default music, but his excuse is that he’s lazy and wants to go and play Forza on his Xbox. The cobbler’s kids have no shoes.
Get Asterisk: The Definitive Guide, 3rd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.