VMware ESXi and vSphere Cluster Management

Required Asterisk Configuration Files for Initial Startup

Learn which Asterisk configuration files are required for an initial source-based startup, how to set ownership, load modules, configure tones and music on hold, and fix shared-library errors.

Asterisk is an open-source PBX and communications platform. After compiling or installing it, the executable alone is not a usable telephone system. Asterisk expects a configuration directory containing core settings and feature-specific files.

This lesson creates a small initial configuration set for a dedicated, non-root service account. It is enough to start Asterisk, enter the Asterisk CLI, and validate the installation. It does not create endpoints, trunks, dialplan logic, or a complete calling system.

What the Initial Configuration Set Does

A minimal configuration is a set of manually created or copied files containing only the settings needed for an initial launch. This is different from installing the complete sample configuration set.

The complete samples are useful as reference material. They demonstrate many modules, options, and call flows, but they can also contain settings and examples that are unnecessary for a minimal deployment. Extra sample settings may make troubleshooting harder and can enable features that have not been reviewed.

The conventional Asterisk configuration directory is /etc/asterisk. The initial files in this lesson are:

File	Primary purpose	Minimum settings to cover	Dependencies or related paths
`asterisk.conf`	Defines important paths and global runtime behavior.	Runtime identity and path settings from the supplied sample.	Configuration, modules, data, spool, log, and runtime directories.
`indications.conf`	Defines regional telephony tones and cadences.	A `[general]` section with the correct country code.	Supported country definitions and local telephony expectations.
`modules.conf`	Controls loadable module behavior.	`[modules]` and `autoload=yes`.	Installed modules and their dependencies.
`musiconhold.conf`	Defines music-on-hold classes and sources.	A default class using local files.	The Asterisk data directory and its `moh` subdirectory.

Create the Configuration Directory and Set Ownership

Replace asteriskuser below with the actual dedicated account and group created on your host. The account name must match everywhere: shell commands, asterisk.conf, and any service-manager configuration.

mkdir -p /etc/asterisk
chown asteriskuser:asteriskuser /etc/asterisk

If the group has a different name, use that group instead. Ownership of the configuration directory is only one part of the permission model. Asterisk must also be able to read its configuration and access the runtime, spool, log, module, and data directories selected by asterisk.conf.

Path	Purpose	Configured by or related to	Ownership considerations
`/etc/asterisk`	Active configuration files.	`asterisk.conf` and feature-specific files.	The runtime account needs appropriate read access and any required write access.
Module directory	Loadable Asterisk modules.	The module path in `asterisk.conf`.	Modules must be readable by the runtime process.
`/var/lib/asterisk`	Persistent data, including the default music-on-hold location.	The data path in `asterisk.conf`.	The runtime account needs access to required subdirectories.
Spool directory	Queues, outgoing call files, and other temporary or persistent work data.	The spool path in `asterisk.conf`.	Write access may be required for enabled features.
Log directory	Asterisk log files.	The log path in `asterisk.conf`.	Grant write access without making unrelated files writable.
Runtime directory	PID files, sockets, and other runtime state.	The runtime path in `asterisk.conf`.	The account running Asterisk must be able to create required state.

Configure indications.conf

indications.conf defines regional telephony signaling tones. These include dial tone, busy tone, ringback, congestion, and related cadence definitions. The correct tone pattern depends on the country or region where the system operates.

Copy the distributed sample from the source tree or from the installed documentation and sample location. The exact sample path can vary by installation layout:

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

Open the file and locate its [general] section. Select the supported two-letter country or regional code that matches the deployment. For Austria:

[general]
country=at

Do not select a code merely because it is convenient. If the configured region does not match the deployment region, dial, busy, ringback, or congestion tones may sound incorrect to users or may not match connected telephone equipment.

Configure asterisk.conf

asterisk.conf is the core configuration file. It establishes important Asterisk paths and global runtime settings. Its directory settings identify where Asterisk finds configuration files, modules, spool files, logs, runtime files, data files, and other resources.

Start with the supplied sample rather than inventing all path settings from scratch:

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

Review the sample and set the runtime identity to the dedicated account. For an account named asteriskuser:

runuser = asteriskuser
rungroup = asteriskuser

runuser is the operating-system account under which Asterisk runs. rungroup is the operating-system group used by the process. Running with a dedicated unprivileged identity limits the damage that a compromised process or misconfigured feature could cause.

Align three things: ownership of Asterisk's directories, the runuser and rungroup values, and the user and group configured in the service manager. If one says asteriskuser and another says a different account, startup may succeed but file access can fail later.

Configure modules.conf

Asterisk capabilities are delivered by loadable modules located outside the core executable. Examples include channel drivers, protocol support, applications, codecs, and resource modules. modules.conf controls how these modules are loaded.

Create a minimal file:

touch /etc/asterisk/modules.conf

Add a [modules] section with automatic loading enabled:

[modules]
autoload=yes

autoload=yes tells Asterisk to attempt to load available modules from the configured module directory. It does not guarantee that every module will load. A module must have been built and installed, its dependencies must be present, and its supporting configuration must be valid.

Automatic loading is convenient during initial setup. A hardened or minimal production system may instead load only explicitly selected modules, reducing unnecessary code and startup noise. That approach requires knowing which modules the deployment actually needs and maintaining the explicit load list carefully.

Configure musiconhold.conf

musiconhold.conf defines music-on-hold classes. A music-on-hold class is a named selection of hold-media behavior. Different classes allow different call flows, departments, or customers to use different audio sources.

Create the file:

touch /etc/asterisk/musiconhold.conf

Then define a general section and a default class that reads local files:

[general]

[default]
mode=files
directory=moh

The [general] section holds global music-on-hold settings. The [default] section creates a class named default. mode=files selects a filesystem-based audio source. directory=moh identifies a directory named moh relative to Asterisk's configured data directory.

With the usual default path settings, this resolves to:

/var/lib/asterisk/moh

Create the referenced directory and place compatible audio files there. The directory must exist, files must be present, and the Asterisk runtime account must be able to read them before callers can hear music.

mkdir -p /var/lib/asterisk/moh
chown -R asteriskuser:asteriskuser /var/lib/asterisk/moh

Start Asterisk in the Foreground

For the first launch, run Asterisk attached to the current terminal:

asterisk -cvvvvv

The -c option starts foreground or console operation and enters the Asterisk CLI. The -v option increases console verbosity, which controls how much operational output is displayed. Repeated v characters increase verbosity within the range supported by the installed Asterisk version.

Option	Effect	When to use it
`-c`	Run in the foreground and enter the CLI.	First startup, interactive testing, and troubleshooting.
`-v`	Increase displayed operational output.	When startup messages need more detail.
`-vvvvv`	Requests a high console verbosity level by repeating `v`.	Initial validation when detailed output is useful.

Watch for fatal errors and confirm that the CLI prompt appears. Stop this foreground process with Ctrl+C. Do not use a foreground test as a substitute for configuring a supervised service; once testing is complete, apply the equivalent identity and paths in the service manager.

Validate the Initial Installation

Reaching the Asterisk CLI without fatal startup errors confirms that the core process and the basic configuration are functioning. It does not prove that every requested module loaded successfully.

Inspect module status from the CLI after startup. A useful first check is:

module show

Review the startup output and module listing for load failures. If a needed module is absent, investigate whether it was built, installed in the configured module directory, and provided with all required dependencies and configuration.

An initially running Asterisk core still needs, at minimum, a channel driver, endpoint configuration, dialplan configuration, and appropriate media and network settings before it can place or receive useful calls. For example, a PJSIP endpoint requires protocol and endpoint settings, while call behavior requires dialplan logic.

Shared-Library Startup Failure

A common operating-system error has a pattern similar to:

asterisk: error while loading shared libraries: libexample.so: cannot open shared object file: No such file or directory

This means the dynamic linker cannot locate a shared library required by the Asterisk executable. The dynamic linker is the operating-system component that finds shared libraries at program startup.

If a required library was installed into a system library location, refresh the linker cache:

sudo ldconfig

ldconfig updates shared-library links and the dynamic linker cache. Retry the foreground startup after it completes.

If the error persists, verify that the library is actually installed, that its directory is included in the system linker configuration, and that the library and its parent directories have suitable permissions. Also check whether the executable and library architectures match. Installing a missing library is different from refreshing the cache: ldconfig cannot create a library that is absent.

Common First-Startup Problems

Symptom	Likely cause	Validation step	Resolution
A shared library cannot be loaded.	Stale linker cache, missing library, or unknown library path.	Read the library name in the error and inspect installed linker paths.	Run `ldconfig` with administrative privileges; if necessary, install the library and correct linker configuration.
Configuration or runtime data cannot be read or written.	Incorrect ownership, mismatched runtime account, or missing directory.	Compare `runuser` and `rungroup` with directory ownership and service settings.	Create missing directories and grant the dedicated account only the required permissions.
Tones do not match local expectations.	Incorrect or unset country setting.	Inspect the `[general]` section of `indications.conf`.	Set the correct supported country code, such as `country=at` for Austria, then reload or restart as appropriate.
Music on hold is silent.	Missing `moh` directory, no playable files, unreadable files, or an unassigned class.	Confirm the resolved data path, media files, permissions, and class used by call handling.	Create the directory, add compatible files, correct read permissions, and assign the intended class.
Asterisk starts but cannot make calls.	No channel or endpoint configuration, no dialplan, or missing modules.	Use `module show` and inspect the configured call path.	Add the required channel driver, endpoints, dialplan, and media/network settings.
Expected modules do not load.	Module not built or installed, missing dependency, or invalid supporting configuration.	Review startup messages and module status in the CLI.	Build or install the component, resolve dependencies, and correct module-specific configuration.

Startup Checklist

Confirm that the dedicated account and group exist.
Create /etc/asterisk and assign appropriate ownership.
Copy the samples for asterisk.conf and indications.conf.
Set the correct regional code in the [general] section of indications.conf.
Set runuser and rungroup in asterisk.conf, and align them with the service manager.
Create modules.conf with autoload=yes, unless an explicit hardened module list is intentional.
Create musiconhold.conf and the referenced media directory if music on hold is required.
Start with asterisk -cvvvvv, confirm the CLI appears, and inspect module loading.
Resolve any shared-library error with ldconfig and library-path checks before investigating Asterisk configuration.

These files establish a clean starting point. The next configuration stages are separate: install or verify the required channel modules, configure endpoints and transports, create dialplan logic, prepare media, and set appropriate network and security controls.

See the required Asterisk configuration files reference while applying this setup.