asterisk.conf

asterisk.conf
Prev	Chapter 4. Initial Configuration Tasks	Next

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

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, “asterisk.conf [directories] section”. For additional information about the usage of these directories, see the File Structure section of Chapter 2, Asterisk Architecture.

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 log files.

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, “asterisk.conf [options] section”. 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 `DONT_OPTIMIZE` option enabled in menuselect for the core dump to be useful. ^[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.

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, “asterisk.conf [files] section”.

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, “asterisk.conf [compat] section”) 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()`.