VMware ESXi and vSphere Cluster Management

Using Templates in Asterisk Configuration Files

Learn how to define and apply reusable chan_sip templates in sip.conf to reduce repeated SIP peer settings and simplify maintenance.

Asterisk configuration templates let you define a reusable set of options once and inherit those options in multiple named sections. They are especially useful in the legacy chan_sip configuration model, where SIP peers are commonly configured in sip.conf.

This lesson uses internal SIP phones as an example. You will first see repeated peer definitions, then replace the duplication with an internal-phones template.

What an Asterisk Configuration Template Does

An Asterisk configuration template is a reusable configuration section whose options can be inherited by other named sections. A configuration file section is a named, bracketed block such as [bob].

Templates are useful when multiple devices, endpoints, or SIP peers need the same baseline configuration. Instead of copying the same options into every section, you define the shared settings once and attach that template to each peer.

Less duplication: common options appear in one place.
Easier maintenance: a shared setting can be changed once instead of separately for every peer.
More consistent configuration: peers are less likely to differ because of an accidental omission or spelling error.

Repeated SIP Peer Configuration

A SIP peer is a configured SIP endpoint or remote party represented by a section in the legacy chan_sip channel driver. The following example defines four internal peers with the same baseline options.

[bob]
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

[alice]
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

[jack]
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

[hellen]
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

Here, type=friend is a legacy chan_sip peer type that supports both incoming and outgoing matching behavior. context=local selects the dialplan context used to process calls from the endpoint. The allow option permits the listed codecs, secret supplies the SIP authentication password, host=dynamic indicates that the device registers dynamically, and dtmfmode=rfc2833 selects RFC 2833 telephone-event signaling for DTMF.

Repeating these values independently is error-prone. One peer might accidentally use a different context, omit a codec, contain a mistyped password, or use a different DTMF mode. A later policy change would also require editing every section.

Repeated Configuration Versus Template-Based Configuration

Approach	Where common settings are defined	Maintenance impact	Best use case
Repeated configuration	Inside every peer section	Every shared change requires multiple edits	Small, intentionally different configurations
Template-based configuration	Inside one reusable template section	One shared change can update all inheriting peers	Multiple endpoints with a common baseline

Declaring a Template

A template declaration uses a section name followed by an exclamation mark inside the parentheses:

[template-name](!)

The ! marks the section as a template rather than a normal endpoint or peer definition. The template can contain the options that should be shared by other sections.

For the internal phones, define this template in sip.conf:

[internal-phones](!)
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

Example Shared SIP Peer Settings

Option	Example value	Role in the example
`type`	`friend`	Uses the legacy chan_sip peer type for incoming and outgoing matching behavior.
`context`	`local`	Selects the dialplan context for calls from the endpoint.
`allow`	`ulaw,alaw`	Allows the listed audio codecs.
`secret`	`verysecret1`	Provides the SIP authentication password in this teaching example.
`host`	`dynamic`	Allows the endpoint to register from a changing address.
`dtmfmode`	`rfc2833`	Uses RFC 2833 telephone events for DTMF signaling.

Security note: verysecret1 is an illustrative value. Use a strong, unique credential for each production endpoint, and protect configuration files because they may contain authentication secrets.

Applying a Template to Peer Sections

To apply a template, put the template name in parentheses after the peer name:

[peer-name](template-name)

Each peer below references internal-phones and therefore receives the settings defined in that template.

[bob](internal-phones)
[alice](internal-phones)
[jack](internal-phones)
[hellen](internal-phones)

The complete template-based arrangement is:

[internal-phones](!)
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

[bob](internal-phones)
[alice](internal-phones)
[jack](internal-phones)
[hellen](internal-phones)

Conceptually, the template supplies the common baseline and each named section supplies the identity of an individual peer. The result is shorter and makes the shared policy visible in one place.

Template Syntax Reference

Purpose	Syntax pattern	Meaning
Define a template	`[internal-phones](!)`	The exclamation mark identifies the section as a reusable template.
Apply one template to a peer	`[bob](internal-phones)`	The peer inherits options from the named template.
Add peer-specific options after template application	`[bob](internal-phones)` `mailbox=100`	The section keeps the shared baseline and adds an option for that particular peer.

Inheritance and Local Customization

Template inheritance does not prevent a peer from having its own settings. A peer can inherit the baseline and then include options that are specific to its device or identity.

[internal-phones](!)
type=friend
context=local
allow=ulaw,alaw
secret=verysecret1
host=dynamic
dtmfmode=rfc2833

[bob](internal-phones)
mailbox=100

[alice](internal-phones)
mailbox=101

In this design, the shared options belong in the template, while unique identity, credentials, or device-specific values belong in the individual sections. For example, production configurations commonly give each peer its own username and secret rather than sharing one password across all devices.

When a peer redefines an option that also exists in a template, verify the effective precedence and behavior for the Asterisk version and configuration module in use. Do not assume that every channel driver handles inheritance identically. Test the resulting peer configuration after making local overrides.

Operational Steps After Editing

Back up the relevant configuration file before changing it.
Define the template and check that its name uses the exact [name](!) syntax.
Reference the template using the exact name in parentheses after each peer name.
Check local sections for options that intentionally or accidentally override the baseline.
Reload the appropriate Asterisk configuration or use the service-management procedure for the installed version and deployment.
Verify that the peers register and that the intended context, codecs, and DTMF behavior are active.

For a chan_sip installation, an administrator may use the Asterisk CLI procedure appropriate to that deployment, such as a SIP configuration reload. The exact command and reload process can vary with the Asterisk version, packaging, and service layout.

Troubleshooting Templates

A peer does not receive the expected common settings

Confirm that the template section is marked with (!).
Confirm that the parenthesized template name exactly matches the template section name, including spelling and capitalization where relevant.
Confirm that the edited configuration was reloaded using the procedure appropriate to the installed Asterisk version and deployment.

A peer behaves differently from other peers using the same template

Review the individual peer section for additional local options.
Check whether a locally defined option changes the effective inherited configuration.
Compare the effective peer configuration across endpoints.
Verify registration status and the codec or DTMF behavior negotiated with the device.

The example does not work in a newer SIP deployment

The examples use sip.conf, type=friend, and the legacy chan_sip driver. Modern Asterisk deployments may use PJSIP, which has different configuration objects, files, inheritance concepts, and syntax.

Identify whether the installation uses chan_sip or PJSIP.
Use configuration syntax that matches the active SIP channel driver.
Do not copy chan_sip peer definitions directly into a PJSIP configuration.

Key Points

A template is a reusable section containing shared configuration options.
Declare a template with a section name followed by (!).
Apply it by placing the template name in parentheses after a peer name.
Keep shared baseline settings in the template and unique endpoint settings on individual peers.
Reload configuration and verify registration, context, codecs, and DTMF behavior after changes.
The syntax in this lesson applies to legacy chan_sip configuration, not directly to PJSIP.

For the related lesson path, see Using Templates.