VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk configuration preprocessor: include, tryinclude, exec and effective order

Trace configuration input across astetcdir, required and optional includes, wildcard expansion, generated command output, duplicate sections, templates, reload and loaded state.

Reviewed 2026-10-26Current Asterisk configuration-file, directory, template, section-extension, GetConfig, UpdateConfig, Reload, AMI-permission and network-security documentation plus the Sangoma FreePBX Configuration File Editor guide were reviewed October 26, 2026; installed branch, astetcdir, include expansion, file order, generator ownership, filesystem permissions, command environment, module parser, reload support, loaded objects and service outcome remain deployment-specific; no PBX, FreePBX system, manager session, file, include graph, external command, generated output, reload, channel, packet, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Start with the real configuration root and owner

Record the responding Asterisk node and build, effective astetcdir, entry filename, filesystem owner and mode, configuration-management owner, target module and approved reload path. /etc/asterisk is the documented default, not proof of the deployed directory. asterisk.conf can relocate the configuration tree.

Classify each input as administrator-owned, package-owned, generated by FreePBX or another controller, or produced at load time. A readable file, the authoritative model, the file Asterisk opened and the state a module loaded are separate evidence.

Model include and tryinclude as source insertion

#include makes Asterisk read another file as though its contents appeared at that location. A missing required include prevents the affected module configuration from loading. #tryinclude has the same insertion role but does not stop module loading when its target is absent.

Retain the literal directive, resolved path, existence result, file hash and observed expansion set. The documented * wildcard can include a directory of files, but a wildcard declaration alone does not prove which files were present or what effective order the deployment consumed.

Treat exec as code execution, not a data shortcut

#exec runs an external program and places its output into the current configuration. Asterisk documents it as disabled by default because of security and performance risk; execincludes=yes in asterisk.conf enables it. #exec, #include and #tryinclude are not supported in asterisk.conf or modules.conf.

Record the exact executable path, immutable arguments, execution identity, environment, exit status, timeout, output hash and redaction policy. Do not embed credentials in command lines or logs, fetch unpinned remote content during a reload, or represent successful execution as valid module configuration.

Resolve sections, templates and duplicate names after insertion

Once text is inserted, section order and parser semantics still matter. Templates contribute inherited values and locally defined settings override matching template settings. The (+) form extends an existing section; when a section name appears more than once, a qualifier such as type=aor or type=endpoint may be necessary to select the intended object.

Preserve literal source and effective values separately. An inherited setting can be absent from the local section while still affecting the loaded object, and an unqualified extension can modify the first same-named category rather than the one an operator intended.

Keep file evidence, reload and runtime proof separate

Use a bounded file read or approved filesystem evidence to confirm the resolved source graph, then validate syntax with the target module’s supported path. Requesting a general or module-specific reload is a distinct operation; it does not prove reload support, parse success, replacement of every object or preservation of active calls.

After the change, inspect the exact loaded endpoint, transport, queue, logger, dialplan context or other object. Test only the first approved behavior. A correct source hash, successful reload response, loaded object and completed call remain four different observations.

Respect FreePBX and other configuration generators

Sangoma describes the FreePBX Configuration File Editor as a way to edit custom files and requires Save followed by Apply Config; it also notes that some files are not writable. Use the supported custom-file or GUI boundary for the installed FreePBX release instead of editing generated output as a durable fix.

Retain a backup and rollback through the true owner, restrict AMI and filesystem authority, and remove temporary tracing. Documentation does not establish the installed include graph, command safety, reload result, compatibility or service outcome, and no live system was tested for this guide.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Guide · Asterisk 22 LTS and current Asterisk configuration, CLI, dialplan, module-loader, PJSIP transport and restart documentation reviewed October 5, 2026; exact packaged builds, managed platforms and installed modules require runtime verification

Asterisk configuration lifecycle: source, reload, restart and proof

Trace one change from its supported configuration owner through generated input, loaded runtime state, activation scope, call evidence and rollback.

Read guide →
Guide · Asterisk branch-23-generated and branch-22-generated GetConfig, GetConfigJSON, ListCategories, CreateConfig and UpdateConfig action references plus official configuration-file, template, include, AMI-permission and network-security documentation reviewed October 16, 2026; installed branch, configuration directory, file ownership, generated-file owner, include graph, template inheritance, module parser, reload support, manager privileges and runtime outcome remain deployment specific; no PBX, module, manager session, configuration file, filesystem, reload, channel, packet, media stream or live call was inspected or tested

Asterisk AMI configuration-file inspection and controlled update

Use GetConfig, ListCategories, CreateConfig and UpdateConfig without confusing file content, inherited effective values, a write response, a reload or loaded runtime state.

Read guide →
Guide · Asterisk 22 LTS

Asterisk dialplan: contexts, patterns and loaded-call evidence

Build a restricted Asterisk 22 call path, then prove its context, match, priorities and runtime behavior separately.

Read guide →
Guide · Asterisk 22 LTS

Asterisk PJSIP: understand the configuration objects

Connect endpoint behavior, authentication, contacts and transport without collapsing them into one account setting.

Read guide →
Guide · FreePBX 17 installation guidance, current release/17.0 framework documentation and Sangoma custom-extension guidance, together with current Asterisk architecture, module, channel and dialplan documentation, were reviewed October 24, 2026. FreePBX is treated as a management and generation layer for Asterisk, not as a competing signaling engine. Repository support ranges, installer defaults, documentation examples and feature availability do not prove the installed framework, Asterisk branch, module set, license, platform health, custom-code compatibility or accepted call behavior. No host, installer, PBX, module, database, generated file, custom dialplan, endpoint, trunk, packet, media stream, backup, restore, upgrade, price, availability, compatibility, support entitlement or call was inspected or tested

FreePBX vs Asterisk: choose the management and configuration boundary

Compare a FreePBX-managed Asterisk system with direct Asterisk administration by ownership, generated configuration, custom logic, lifecycle, recovery and acceptance evidence.

Read guide →
Guide · Sangoma Custom Destinations, Misc Applications and Misc Destinations guidance; FreePBX Custom Applications 17.0.1 and Misc Applications 17.0.3 release/17.0 metadata and current dialplan sources; and current Asterisk Goto, Gosub, Return and dialplan documentation reviewed October 11, 2026; older screen guides establish concepts rather than an exact FreePBX 17 field map, and no installed module, code, application, destination, generated or loaded dialplan, caller path or call was inspected or tested

FreePBX Custom Destinations: publish custom dialplan without losing ownership

Register a reviewed context, extension and priority as a managed destination, choose transfer or subroutine behavior deliberately, and keep source, generated state and call results separate.

Read guide →
Guide · Sangoma FreePBX 17 migration and platform guidance plus Asterisk 20 Macro semantics and current branch-23 Gosub, Return, LOCAL, LOCAL_PEEK and StackPop documentation reviewed October 14, 2026; Sangoma says the supported FreePBX 17 install defaults to Asterisk 22, where Macro is unavailable and custom dialplan or AGI macro calls require manual conversion, but installed FreePBX, Asterisk, modules, custom files, includes, generated dialplan, subroutine stack, variables, channels, routes and calls remain deployment specific, and no PBX, backup, restore, file, dialplan, AGI script, channel, route or call was inspected or tested

FreePBX 17 macro-to-Gosub migration for custom dialplan

Inventory every custom Macro dependency before a FreePBX 17 restore, translate its call and return semantics into explicit Gosub frames, and prove the loaded route without editing generated dialplan.

Read guide →
Guide · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →
Troubleshooting · Current Asterisk configuration-file, directory, template, section-extension, GetConfig, UpdateConfig, Reload, AMI-permission and network-security documentation plus the Sangoma FreePBX Configuration File Editor guide were reviewed October 26, 2026; installed branch, astetcdir, include expansion, file order, generator ownership, filesystem permissions, command environment, module parser, reload support, loaded objects and service outcome remain deployment-specific; no PBX, FreePBX system, manager session, file, include graph, external command, generated output, reload, channel, packet, media stream or live call was inspected or tested

Asterisk include is missing, uses the wrong order or exec output fails

Find the first divergence across configuration root, resolved include set, optional files, wildcard membership, generated command output, section inheritance, parser result, reload and loaded state.

Read guide →