Server conf file templates explained

If you run more than a couple of phones or carriers, you end up repeating the same handful of Asterisk settings over and over. Conf file templates exist so you can write that shared block once and point many entries at it. Here is how they work and the one rule that trips people up.

What a template is for

A conf file template is a reusable block of parameters that several phones entries and server carrier entries can share. A typical example is a Codec line such as allow=gsm, which says the GSM codec may be used. Instead of typing that line into every SIP peer and every carrier, you put it in one template and reference the template from each entry. Change the template once and every entry that uses it picks up the new setting on the next Conf file rebuild.

flowchart TD
  T[Conf template allow gsm and common lines] --> P1[Phone one]
  T --> P2[Phone two]
  T --> C1[Carrier entry one]
  T --> C2[Carrier entry two]
  P1 --> G[Generated conf files]
  P2 --> G
  C1 --> G
  C2 --> G

Template ID and contents

Each template has a Template ID, which must be at least 2 characters and no more than 15, with no spaces. This ID is how the rest of the system refers to the template, so pick something readable like gsmcommon. The Template Name is just a descriptive label for humans. The Admin User Group field restricts which admin users can view the record, defaulting to all.

Template Contents is the actual block of settings shared by every phone and Carrier that uses the template. You put your common lines here — codec rules, NAT settings, qualify behavior, and similar parameters that genuinely belong to a whole group of entries.

The fields you must never put in a template

This is the part that quietly breaks setups. Some fields are unique to a single entry and must not live in a shared block. Keep these out of Template Contents entirely:

• secret — the password for that one peer.
• accountcode and account — per-entry accounting values.
• username — the per-peer login.
• mailbox — the per-peer voicemail box.

If you drop a secret or a username into a template, every phone and Carrier that shares it inherits the same credential, and registrations start failing in confusing ways. Those values belong in each individual entry. Everything that is genuinely identical across a group goes in the template; everything unique stays out. Once your templates are set, a Conf file rebuild pushes them into the generated Asterisk files.

There is a good reason this restriction exists. A template is meant to describe shared behavior, not identity. The moment you put an identifying value in it, the template stops being safe to reuse, because reuse is exactly what spreads the wrong credential everywhere. Treat the template as the answer to a question like which codecs and NAT rules do these entries all share, and treat the per-entry box as the answer to who is this specific peer.

A practical habit: when you build a new phone or carrier, fill in its secret, username, and account fields directly on that entry first, then point it at a template only for the shared lines. If you ever find yourself wanting to vary a value per entry, that value does not belong in the template at all. Keeping that boundary clean is what makes templates save time instead of causing scattered, hard-to-trace failures.

Templates pair naturally with a Server trunk strategy: shared codec and NAT settings in one template, with each carrier still holding its own credentials and line reservations.

This article is part of our complete guide to installing VICIdial. For the wider picture of which settings live where, see modifying server settings in VICIdial Admin.

If hand-managing templates and carrier conf blocks is more than you want to own, VICIfast stands up a configured VICIdial server in under 40 seconds so the conf-file plumbing is handled for you.