Asterisk course

Required Asterisk Configuration Files for a First Startup

Learn how to create the minimum Asterisk configuration files, set permissions, enable modules, configure regional tones and music on hold, and verify the Asterisk CLI.

What a Minimal Asterisk Configuration Does

Asterisk is open-source communications software that provides PBX, telephony, and real-time communications functions. Before it can start reliably, it needs core configuration files and access to the directories referenced by those files.

A manually created configuration is useful when you want to understand the installation, reduce unnecessary defaults, or build only the components needed for a particular deployment. The alternative is to install the complete sample configuration set. Sample files can include settings, features, and module references that are useful for demonstrations but unnecessary for a minimal installation.

This lesson creates enough configuration for an initial foreground launch and CLI test. It does not create a usable calling system. Endpoints, channel drivers, trunks, dialplan routing, voicemail, and other call-handling features require additional modules and configuration.

Prepare the Configuration Directory

The standard Asterisk configuration directory is /etc/asterisk. It contains Asterisk's text configuration files. Create it if the installation has not already done so:

mkdir -p /etc/asterisk

Asterisk should run under a dedicated non-root service account: an operating-system user and group created specifically for the Asterisk process. Assign ownership using the actual account names on your host:

chown asteriskuser:asteriskuser /etc/asterisk

The service account needs to traverse the directory and read the configuration files. It also needs access to other paths used at runtime, such as the module, data, log, and spool directories. Ownership and permissions must agree with the runuser and rungroup settings in asterisk.conf.

For a complete account-creation procedure, see Add a System User For Asterisk and Change File Owner.

Minimum Files for an Initial Asterisk Startup

Configure indications.conf

indications.conf selects regional definitions for telephony signals such as dial tone, busy tone, ring cadence, and related indications. These expectations differ between countries and regions.

When the source tree provides the sample, copy it into the configuration directory:

cp /path/to/asterisk-source/configs/samples/indications.conf.sample /etc/asterisk/indications.conf

In the [general] section, set country to an appropriate two-letter country code. For example, Austria uses at:

[general]
country=at

The complete list of supported country codes and their tone definitions is documented in the indications configuration content, including the supplied sample. Select the code that matches the deployment location rather than copying the example unchanged.

Configure asterisk.conf

asterisk.conf is the core configuration file for important directory locations and global runtime behavior. Its path settings tell Asterisk where to find configuration files, loadable modules, data, logs, spool files, and related resources.

Start with the supplied sample when it is available:

cp /path/to/asterisk-source/configs/samples/asterisk.conf.sample /etc/asterisk/asterisk.conf

Set the runtime identity to the dedicated account and group:

runuser = asteriskuser
rungroup = asteriskuser

Sample configuration files often place optional settings behind a semicolon. A semicolon-prefixed line is a comment; it has no effect until the semicolon is removed. Therefore, uncomment the runuser and rungroup settings before expecting them to apply.

Use the same names in all three places: the operating-system account, the ownership of relevant files and directories, and the runuser/rungroup values. A mismatch can allow an initial root test to work while causing failures when Asterisk drops privileges or runs as a service.

Configure modules.conf

Most Asterisk capabilities are implemented as modules. A module is a loadable component that supplies a feature, protocol, channel driver, application, or other resource. The Asterisk core process alone does not provide every capability.

modules.conf controls which installed modules load at startup. Create the file:

touch /etc/asterisk/modules.conf

Then add a minimal module-loading policy:

[modules]
autoload=yes

autoload=yes tells Asterisk to attempt to load available installed modules from its configured module directory. It cannot load a module that was not selected, built, or installed. If a required channel driver or feature is missing, return to the build and module-selection process, such as installing modules with Menuselect.

A production system may later replace broad automatic loading with explicit load, noload, and preload directives. That approach can reduce the module set and make startup behavior more predictable, but automatic loading is a practical starting point for a first launch.

Configure musiconhold.conf

A music-on-hold class is a named set of settings and audio content used when a caller is placed on hold. A class can later be assigned to different call flows so that different callers hear different audio or playback behavior.

Create the configuration file:

touch /etc/asterisk/musiconhold.conf

Add a default class that plays files:

[general]

[default]
mode=files
directory=moh

mode=files selects file-based audio playback. The value directory=moh is relative to Asterisk's configured data directory unless an absolute path is supplied. With the conventional data directory, its effective path is:

/var/lib/asterisk/moh

The directory and compatible audio files must exist before callers can hear music. The Asterisk service account must also be able to read them. Additional classes can later provide different music or behavior for different queues, extensions, or other call flows.

Important Filesystem Locations

Start Asterisk in the Foreground

Test the installation interactively rather than immediately starting it as a background service:

asterisk -cvvvvv

A successful first test reaches the Asterisk CLI, the interactive command-line interface used to observe and administer a running process, without fatal startup errors. Foreground mode keeps Asterisk attached to the current terminal. Ending the terminal session or interrupting the process ends this test run; press Ctrl+C to stop it.

Troubleshoot the First Startup

Shared-library loading error

If Asterisk reports an error while loading shared libraries, the dynamic linker may not have an updated cache or links for recently installed libraries. ldconfig refreshes that cache and the symbolic links used by the Linux dynamic linker.

ldconfig

Retry the foreground command. If the error remains, inspect the named library and verify that its package or installed file exists.

Configuration or permission error

Verify that the user and group named by runuser and rungroup exist and match filesystem ownership. Check /etc/asterisk and every referenced path. The service account must be able to traverse parent directories and read required files.

Modules are unavailable

Confirm the module directory configured in asterisk.conf and inspect whether the expected module files are installed there. autoload=yes does not build or install missing modules. Revisit module selection and installation, then retry startup.

No music on hold

Check the data directory in asterisk.conf, resolve the relative moh path, and confirm that the directory exists with supported audio files. Make sure the service account can read those files.

Regional tones are incorrect

Review the country definitions in indications.conf and set the [general] country value to the correct supported two-letter code. Reload or restart Asterisk as appropriate for the environment.

What a Successful Start Does Not Provide

Reaching the CLI proves that the core process can start with the supplied configuration. It does not mean that phones can register or calls can be placed. Call capability requires appropriate channel and feature modules, endpoint and transport settings, trunks where needed, and a dialplan that routes calls.

Continue with registering phones to Asterisk, learn what a dialplan is, and configure the required modules before building call flows. Understanding the overall Asterisk architecture also helps explain how the core, modules, channels, and dialplan work together.

Exam-Relevant Notes

• /etc/asterisk is the standard Asterisk configuration directory.
• indications.conf selects regional tone definitions with a two-letter country code such as at for Austria.
• asterisk.conf defines important paths and the runuser/rungroup runtime identity. Semicolon-prefixed settings are comments.
• modules.conf controls module loading; autoload=yes attempts to load installed modules but cannot load modules that were not built or installed.
• In musiconhold.conf, mode=files uses audio files, and relative directory=moh resolves beneath the Asterisk data directory.
• asterisk -cvvvvv runs Asterisk in the foreground with the CLI and high verbosity. Use Ctrl+C to stop the test.
• A successful CLI launch is an installation milestone, not a complete PBX configuration.