Asterisk course

Using Configuration Templates in Asterisk

Learn how to declare Asterisk configuration templates, inherit shared settings, override values, use multiple templates, and validate changes safely.

Asterisk configuration templates let you define shared settings once and reuse them in multiple configuration sections. This reduces copy-and-paste work for endpoints, users, trunks, and other module-specific objects.

A template is a feature of an Asterisk configuration file. It is not a dialplan subroutine and it is not a runtime object that handles calls. Asterisk uses the template while reading configuration, then applies the inherited options to each child section.

Why use Asterisk configuration templates?

Many configuration sections differ in only a few values. For example, several internal phones may use the same dialplan context, codec policy, and feature permissions while having different extension numbers, passwords, caller IDs, and mailboxes.

Without templates, those common settings must be repeated in every section. A template moves the common settings into one reusable definition. Each normal section then inherits the definition and contains only its identity-specific values.

• Consistency: related endpoints receive the same shared defaults.
• Easier maintenance: one edit can update a policy used by many sections.
• Lower configuration risk: there are fewer opportunities for two supposedly similar sections to drift apart.
• Clearer configuration: a child section shows which values are unique rather than repeating every default.

Templates do not replace dialplan organization. Dialplan contexts and extensions still define call behavior; templates organize configuration data used by Asterisk modules. For background on dialplans, see what a dialplan is and Asterisk contexts.

Template terminology

Declaring a template

A template is declared by placing (!) after its section name in the section header:

[common-endpoint](!)
context=internal
allow=ulaw
allow=alaw

The exclamation mark tells Asterisk that common-endpoint is a template. Its contents use ordinary option=value settings. The section is intended to supply inherited settings rather than represent one independently usable endpoint or account.

The option names must be valid for the configuration file and module being used. A setting valid in a chan_sip file may not be valid in a PJSIP configuration, and an option from one module should not be copied into an unrelated module's section.

Creating a child section

A normal section inherits a template by naming the template in parentheses after the child section name:

[common-endpoint](!)
context=internal
allow=ulaw
allow=alaw

[1001](common-endpoint)
callerid=Example User <1001>
secret=replace-with-unique-secret

Here, 1001 is the child section and common-endpoint is its template. The effective configuration for 1001 includes the inherited context and codec settings, plus its own caller ID and secret.

A child can override an inherited option by assigning that option again:

[common-endpoint](!)
context=internal
allow=ulaw

[1002](common-endpoint)
callerid=Remote User <1002>
secret=replace-with-unique-secret
context=remote-users

The explicit context=remote-users in the child takes precedence over the inherited context=internal. Overrides are useful, but they should be intentional and documented when they create an exception to a shared policy.

Template syntax reference

Inheriting from multiple templates

A child section can inherit several templates by listing their names, separated by commas:

[base-policy](!)
context=internal

[support-policy](!)
; Add module-valid support-team settings here

[2001](base-policy,support-policy)
; Add unique endpoint settings here

Multiple inheritance is useful when each template has a focused purpose. For example, one template can contain common endpoint behavior, another can contain authentication defaults, and a third can contain transport-related defaults when those settings are valid for the selected module and object type.

Inheritance order matters if two templates assign the same option. In the usual comma-separated form, a later template takes precedence over an earlier template for a conflicting setting; an explicit value in the child should be treated as the clearest final override. Because precedence can be easy to misunderstand, avoid overlapping defaults unless the precedence is intentional.

• Keep one template responsible for general endpoint behavior.
• Put authentication defaults in a separate template only when the module supports that arrangement.
• Keep transport, NAT, or contact behavior in a device-class template when appropriate.
• Document which template supplies each class of setting.
• Inspect the effective loaded configuration instead of relying only on visual inspection of the source files.

Template design patterns

Build a base template for a device class

Start by identifying values shared by an entire class of devices or accounts. A base template might contain the internal context, permitted codecs, and common call features. The child section should contain values that identify one device.

[internal-phone](!)
context=internal
allow=ulaw
allow=alaw

[1001](internal-phone)
callerid=Alice <1001>
secret=unique-secret-for-1001
mailbox=1001@default

[1002](internal-phone)
callerid=Bob <1002>
secret=unique-secret-for-1002
mailbox=1002@default

Extend a broader template with a specialized template

Office phones and remote phones may share codec and dialplan policy while needing different transport, NAT, or contact defaults. Separate focused templates avoid duplicating the entire configuration:

[phone-policy](!)
context=internal
allow=ulaw
allow=alaw

[office-phone](!)
; Add office-device options valid for the selected module

[remote-phone](!)
; Add remote-device options valid for the selected module

[1003](phone-policy,office-phone)
callerid=Office User <1003>
secret=unique-secret-for-1003

[1004](phone-policy,remote-phone)
callerid=Remote User <1004>
secret=unique-secret-for-1004

This design keeps per-device identity values in the child sections while allowing office and remote policies to evolve independently.

Use multiple inheritance for a special-purpose endpoint

A support-desk phone might need the normal phone policy plus a support-team policy:

[phone-policy](!)
context=internal

[support-policy](!)
; Add module-valid support-team settings here

[2001](phone-policy,support-policy)
callerid=Support Desk <2001>
secret=unique-secret-for-2001
; Add a child override only when this endpoint is intentionally different

Keep the templates narrow enough that their ownership is obvious. If both templates define the same option, decide whether the order is the intended precedence or move that option to one template.

What belongs in a template versus a child section?

Applying templates to module configuration

The exact options available for a template and its child sections depend on the Asterisk module and configuration file. Templates may be useful in representative channel-driver configurations, but an option is not automatically valid merely because it appears in another module's example.

For example, the first endpoint examples use a chan_sip-style set of option names to demonstrate the inheritance mechanism. PJSIP endpoint, authentication, address-of-record, and transport objects use their own configuration structure and supported options. Voicemail, queues, and other modules likewise have module-specific files and section types.

• Check the documentation for the exact Asterisk version in production.
• Read the sample configuration shipped with the installed module.
• Confirm that the option belongs to the object type being configured.
• Do not combine chan_sip and PJSIP options in one design without verifying their meanings and syntax.
• For voicemail-specific settings, consult the voicemail configuration file documentation.
• For queue settings, consult material on defining queues.

Validating and applying changes

Configuration files are read by Asterisk when the relevant module loads or reloads. Editing a file does not necessarily change the running system immediately.

1. Back up the current configuration and record the intended change.
2. Convert or create one test child section.
3. Check the template marker and the child section's inheritance syntax.
4. Reload the affected module, using the command appropriate for that module.
5. Inspect the loaded object through the Asterisk CLI where the module provides inspection commands.
6. Register a test phone or place controlled test calls before migrating more sections.

asterisk -rvvv

From the Asterisk CLI, use the module's supported reload and inspection commands. A generic reload form is:

module reload <module-name>

The exact reload command and inspection command vary by module and Asterisk version. For a production PBX, make incremental changes and keep a rollback copy. If configuration is generated by a provisioning or management system, confirm that manual edits will not be overwritten.

Safely converting repeated configuration

Suppose several existing endpoint sections are nearly identical. Do not immediately replace all of them. Use this migration process:

1. Compare the working sections line by line.
2. List settings that are identical and settings that differ.
3. Classify identical values as safe shared defaults only after checking their operational meaning.
4. Put the shared values in a clearly named template.
5. Leave credentials, identifiers, caller IDs, mailbox assignments, and network addresses in child sections unless they are deliberately shared.
6. Convert one endpoint to inherit the template.
7. Reload the correct module and test registration, inbound calls, outbound calls, voicemail, and any relevant feature permissions.
8. Convert the remaining sections in small groups, retaining the previous configuration until validation is complete.

This approach makes it easier to identify whether a failure came from inheritance syntax, an incorrect shared assumption, an invalid module option, or an incomplete reload.

Common mistakes

• Incorrect template name: The child header must name the template exactly, including spelling and punctuation.
• Missing (!) marker: A source section without the template declaration marker is not being used as the intended template.
• Unexpected override: A value explicitly assigned in the child replaces the inherited value.
• Shared secrets or identifiers: Unique credentials, endpoint names, mailbox numbers, caller IDs, and addresses should not be placed in a broad template.
• Mixed module options: Options from different channel drivers, object types, or Asterisk versions may be invalid together.
• Wrong reload: Reloading an unrelated module does not apply changes to the module that owns the edited file.
• No reload or restart: Depending on the module and setting, changes may require a module reload, a broader configuration reload, or a restart.
• Overlapping defaults: Two templates assigning the same option can produce surprising results if inheritance order is not understood.

Template troubleshooting checklist

Exam-relevant notes

• A template is identified by the special (!) marker in its section header.
• A child section inherits one template with [child](template).
• Multiple templates use a comma-separated list such as [child](base,policy).
• A child option can override an inherited option.
• Inheritance order matters when templates contain conflicting options; verify the effective result.
• Templates are configuration-file constructs, not dialplan subroutines or runtime call objects.
• Always validate options against the module and Asterisk version that actually load the file.

Summary

Asterisk templates provide reusable section definitions for configuration files. Declare a template with [name](!), inherit it with [child](name), and place child-specific settings in the normal section. Use multiple focused templates when their responsibilities are clear, but avoid conflicting defaults and verify precedence. Keep unique credentials and identities out of shared templates, reload the correct module, and test one migrated section before changing a production-wide configuration.