VMware ESXi and vSphere Cluster Management

Asterisk Dialplan Contexts

Learn how Asterisk dialplan contexts isolate call routing, assign channels to entry points, control permissions, and organize extensions.conf safely.

What Is an Asterisk Context?

A context is a named section of the Asterisk dialplan. The dialplan is the call-processing logic that tells Asterisk what to do with a call by using contexts, extensions, priorities, and applications.

When a channel enters Asterisk, its assigned context determines the starting area where Asterisk looks for a matching destination. A channel is a call leg or communications path, such as an internal phone connection, an inbound trunk call, or a test channel.

An extension is a destination or pattern evaluated inside a context. The context contains extension definitions; the extension is not a replacement for the context. For example, extension 1000 in from-internal is different from extension 1000 in from-external.

A priority is the ordered execution step within an extension. A dialplan instruction usually consists of an extension, a priority, and an application such as Answer(), Playback(), or Hangup().

Why Contexts Matter

Extension matching is scoped to the channel's current context. Asterisk does not automatically make every extension in every context available to every channel.

This isolation provides two important benefits:

Organization: Call routes can be grouped by origin, service, or permission level.
Protection: An outside caller or restricted device does not automatically gain access to internal extensions, privileged features, or outbound routes.

For example, if extension 1000 exists only in from-internal, a channel entering through from-external cannot normally dial 1000. The extension is outside the external channel's current lookup scope.

Contexts as Security and Service Boundaries

Contexts can separate callers according to where they come from and what they are allowed to do. Common groups include:

Internal users and trusted phones
External callers arriving through a trunk
Restricted users who may call local extensions but not outside numbers
Test systems and maintenance endpoints
Special services such as an IVR, queue, operator, or emergency route

Context Roles and Typical Call Sources

Context name | Typical channel source | Destinations allowed | Security purpose

from-internal | Authorized internal endpoint | Internal extensions and approved outbound routes | Provides normal staff calling privileges

from-external | Incoming trunk or outside caller | An attendant, queue, IVR, or other intended inbound destination | Prevents unsolicited access to internal and outbound routes

local-only or restricted | Limited device or guest user | Internal extensions and local services only | Removes external dialing privileges

test or maintenance | Test endpoint or maintenance channel | Carefully selected diagnostic destinations | Keeps test behavior separate from production calling

Assigning an untrusted inbound channel to an internal or unrestricted context is dangerous. It may expose internal dialing, privileged applications, or expensive outbound routes. This can contribute to toll fraud and unauthorized feature access.

How a Channel Enters the Dialplan

Channel configuration assigns a context to a device, endpoint, trunk, or other channel source. That assignment connects the incoming channel to its dialplan entry point.

For a phone, the channel configuration commonly assigns the phone to an internal context. For an outside trunk, the configuration should normally assign the trunk to a limited inbound context. Equivalent context assignment exists for different channel technologies, although the configuration file and syntax vary.

Where Context Assignment Occurs

Configuration area | Purpose | Resulting dialplan behavior

extensions.conf context declaration | Defines the named dialplan section | Supplies the extensions and priorities available in that context

Legacy SIP endpoint or peer configuration | Assigns a chan_sip device or peer to a context | Calls from that endpoint begin lookup in the assigned context

Other channel technology endpoint or trunk configuration | Assigns a device or trunk to a context using its technology-specific settings | Calls enter the matching context for that channel technology

Defining Contexts in extensions.conf

The traditional Asterisk dialplan file is /etc/asterisk/extensions.conf, although an installation may use a different location or include additional dialplan files.

A context declaration uses a name in square brackets. Extensions and their priorities are placed beneath that declaration until another context begins.

[from-internal]
exten => 1000,1,Answer()
exten => 1000,n,Playback(hello-world)
exten => 1000,n,Hangup()

[from-external]
exten => s,1,Answer()
exten => s,n,Playback(hello-world)
exten => s,n,Hangup()

In this example, the from-internal context defines extension 1000. The from-external context defines the s start extension, commonly used when a channel arrives without a dialed extension. These are separate contexts, so the two call origins do not automatically share destinations.

Context Naming Rules

Context names may contain uppercase letters, lowercase letters, digits, hyphens, and underscores. Use names that communicate the caller's origin or permission level.

from-internal, from-external, local_only, and staff2 are examples of names using permitted characters.

Context Naming Guidance

Name or character type | Allowed or reserved status | Notes

Letters | Allowed | Uppercase and lowercase letters are permitted; use consistent naming.

Numbers | Allowed | Useful when a name needs a site, tenant, or service identifier.

Hyphen | Allowed | Helpful for readable names such as from-internal.

Underscore | Allowed | Useful for names such as local_only.

general | Reserved or special configuration section name | Do not use it as an ordinary dialplan context name.

default | Reserved or special configuration section name | Avoid using it for a normal calling class.

globals | Reserved or special configuration section name | Used for global variable configuration; do not treat it as a regular service context.

Descriptive names make configuration review easier. A reviewer can usually infer the intended access level from names such as from-external and local-only, while vague names make troubleshooting and security analysis harder.

Practical Organization: Internal and External Call Origins

A common design is to separate internal-originated calls from calls arriving from outside.

[from-internal]
exten => 1000,1,Dial(PJSIP/1000)
exten => 1001,1,Dial(PJSIP/1001)
exten => _9X.,1,NoOp(Approved outbound route)
exten => _9X.,n,Dial(PJSIP/provider/${EXTEN:1})

[from-external]
exten => s,1,Answer()
exten => s,n,Goto(ivr-main,s,1)

[local-only]
exten => 1000,1,Dial(PJSIP/1000)
exten => 1001,1,Dial(PJSIP/1001)

The internal context contains internal extension dialing and an example approved outbound pattern. The external context exposes only an inbound destination, such as an IVR. The local-only context permits internal calls but has no outbound pattern.

A caller entering through from-external cannot directly use the internal or outbound patterns merely because those patterns exist elsewhere. They would become reachable only if the external context explicitly provided a route to them.

Assigning a Legacy SIP Endpoint

sip.conf is the legacy configuration file historically used by chan_sip to configure SIP users and peers. A legacy endpoint can be assigned to the internal context like this:

[1001]
type=friend
context=from-internal

After this assignment, calls from that endpoint start dialplan lookup in from-internal. The context must also exist in the loaded dialplan, for example:

[from-internal]
exten => 1000,1,Dial(PJSIP/1000)
exten => 1001,1,Dial(PJSIP/1001)

Modern deployments may use another channel technology, such as PJSIP. The setting name and configuration location may differ, but the principle remains the same: the endpoint or trunk is assigned a context, and that context determines the channel's initial dialplan scope.

Intentional Movement Between Contexts

Context isolation does not mean contexts can never interact. Dialplan applications such as Goto can explicitly transfer execution to another context.

A cross-context transfer identifies three target components:

Context: The destination dialplan section.
Extension: The destination number or pattern entry.
Priority: The execution step at which processing begins.

[from-external]
exten => s,1,Goto(from-internal,1000,1)

This instruction sends the call to context from-internal, extension 1000, priority 1. It is an intentional route, not automatic visibility of all internal extensions.

Validate every cross-context path. A Goto can bypass the boundary that would otherwise restrict a caller. Confirm that the source is authorized, the target is appropriate, and later changes cannot turn the route into an unintended privilege escalation.

Restricted Calling Permissions

Contexts can implement different calling permission levels. For example:

local-only can contain internal extension destinations but no external dialing patterns.
staff can contain internal dialing and approved outbound routes.
from-external can contain only inbound service destinations.

Assign endpoints according to authorization rather than convenience. A guest phone should not receive the same context as a trusted staff phone, and an external trunk should not be placed in a context designed for internal users.

Verifying and Reloading the Dialplan

After editing the dialplan, inspect the loaded contexts and extensions from the Asterisk command line:

asterisk -rx "dialplan show"

If operational policy permits a dialplan reload, use:

asterisk -rx "dialplan reload"

Always verify that the expected context and extension appear after the reload. A correctly written file has no effect on active call processing until Asterisk loads the change.

Troubleshooting Context Problems

An Extension Cannot Be Found

If a call reports that the requested extension does not exist, likely causes include:

The extension was defined in a different context from the channel's assigned context.
The expected context was not loaded from the dialplan configuration.
The endpoint or trunk has an incorrect context assignment.

Identify the channel's current context in Asterisk CLI output. Then inspect the dialplan listing and confirm that the extension exists beneath that exact context. Finally, review the endpoint or trunk configuration.

An External Caller Reaches Internal or Unauthorized Routes

Check whether the inbound trunk was assigned to from-internal or another privileged context. Also inspect the external context for broad extension patterns and review every Goto or other route that transfers into a privileged context.

Limit the external context to intended inbound destinations and remove unnecessary cross-context jumps.

A Context Change Has No Effect

Possible causes include a syntax error in the bracketed declaration, editing the wrong file, missing configuration includes, failure to reload the dialplan, or use of a reserved name such as globals.

Check dialplan show, verify the exact spelling and bracket syntax, confirm which files are included, reload when appropriate, and rename ambiguous or reserved context names.

Exam-Relevant Notes

A context is a named section of the dialplan, not an individual extension.
A channel starts dialplan processing in its configured context.
Extension matching is normally limited to the current context.
Goto(context,extension,priority) explicitly crosses a context boundary.
Endpoint and trunk context assignment is a major security control.
extensions.conf conventionally contains context declarations and dialplan logic.
Use descriptive names such as from-internal and from-external.
Do not use reserved configuration section names such as general, default, or globals as ordinary contexts.

Summary

Asterisk contexts define the initial set of extensions available to a channel. They organize the dialplan and create boundaries between internal users, external callers, restricted devices, trunks, and test systems. The channel's configuration assigns its starting context, while applications such as Goto provide deliberate movement to another context, extension, and priority.

Clear context names, narrow permissions, careful endpoint assignments, and explicit review of cross-context routes make a dialplan easier to maintain and less likely to expose unintended call paths.