How SIP Extensions Work in Asterisk

An Asterisk extension is not one thing. In the PJSIP channel driver it is three configuration objects that reference each other: an endpoint (how calls to and from the device behave), an auth (the username and password), and an AOR, or address of record (where the device is currently registered). The endpoint's context option links it to the dialplan, which decides what happens when a number is dialled. Once you see these four pieces, Asterisk front ends such as FreePBX and Issabel become easier to read, because they are just writing these objects for you.

The three PJSIP objects

Here is the smallest useful definition of extension 1001 in pjsip.conf:

[1001]
type=endpoint
context=from-internal
disallow=all
allow=ulaw
allow=alaw
auth=1001
aors=1001

[1001]
type=auth
auth_type=userpass
username=1001
password=long-random-secret

[1001]
type=aor
max_contacts=1

The three sections share the name 1001, which is a convention rather than a requirement. The links that matter are auth=1001 and aors=1001 inside the endpoint.

The endpoint

The endpoint is the device from Asterisk's point of view. It holds:

1. Codecs (disallow, allow). Asterisk offers and accepts only these when negotiating audio with the phone.
2. Context. The dialplan context that incoming calls from this device enter. This is the security boundary: a device in from-internal can reach whatever that context allows, and nothing else.
3. Media behaviour. Options such as direct_media, rtp_symmetric, force_rport and rewrite_contact control where audio flows and how Asterisk deals with NAT.
4. References to one auth (for inbound authentication) and one or more AORs.

An endpoint without an AOR can still be called if you dial a full SIP URI, but it cannot be reached by name, because Asterisk has nowhere to send the call.

The auth

The auth object stores credentials. With auth_type=userpass, Asterisk keeps the plain password and uses it to verify the digest the phone sends. With auth_type=md5, you store a pre-computed hash instead. The username here is what the phone must send in its authentication header. On most systems it equals the extension number, but it can differ, which is why softphones have an Auth username field separate from the username.

The AOR

The AOR is the mailbox for registrations. When a phone registers, Asterisk writes a contact into the AOR: the IP address, port and transport the phone can be reached at. max_contacts limits how many devices can register to the same AOR at once. remove_existing=yes makes a new registration push out the oldest contact instead of being refused. qualify_frequency makes Asterisk send periodic OPTIONS requests to each contact, so it knows whether the phone is still reachable.

You can inspect the AOR at any time:

asterisk -rx "pjsip show aor 1001"
asterisk -rx "pjsip show contacts"

How the dialplan fits in

The dialplan lives in extensions.conf. It is divided into contexts, and each context holds extensions: patterns that match dialled numbers, with a numbered list of applications to run. A minimal internal context:

[from-internal]
exten => _1XXX,1,Dial(PJSIP/${EXTEN},20)
 same => n,Voicemail(${EXTEN}@default,u)
 same => n,Hangup()

exten => 600,1,Answer()
 same => n,Echo()
 same => n,Hangup()

Reading it step by step:

1. _1XXX is a pattern. The underscore makes it a pattern; X matches any digit. It matches 1000 to 1999.
2. Dial(PJSIP/${EXTEN},20) rings the PJSIP endpoint whose name equals the dialled number, for 20 seconds. Asterisk looks up the endpoint, finds its AOR, and sends an INVITE to every registered contact.
3. If nobody answers, Voicemail() plays the unavailable greeting and records a message.
4. 600 is a literal extension that answers and echoes audio back, a classic test.

So a phone's "extension number" is really two things that happen to share a name: an endpoint called 1001, and a dialplan pattern that dials PJSIP/1001. The endpoint's context=from-internal decides which patterns the phone itself can dial.

What happens when a phone registers

Registration is how a phone tells Asterisk where it is. The exchange, defined in RFC 3261, looks like this:

1. The phone sends REGISTER sip:pbx.example.com with a Contact header holding its own address, and From/To headers naming sip:1001@pbx.example.com.
2. Asterisk finds the endpoint. By default it matches the user part of the From header (1001) against endpoint names.
3. The first request carries no credentials, so Asterisk replies 401 Unauthorized with a WWW-Authenticate challenge containing a nonce.
4. The phone computes a digest from the username, realm, nonce and password (RFC 7616), and sends REGISTER again with an Authorization header.
5. Asterisk checks the digest against the auth object. If it matches, it stores the Contact in the AOR and answers 200 OK with an Expires value, typically 60 to 3600 seconds.
6. The phone repeats the registration before the expiry runs out. If it stops, the contact ages out and the endpoint shows Unavailable.

A 401 followed by a 200 OK is therefore normal. A 401 with no 200 OK means the password does not match; see SIP 401 Unauthorized. A 403 Forbidden usually means the endpoint was not found or matching failed. No answer at all means the request never reached Asterisk, which is a port, transport or firewall problem.

Watch the exchange live with:

asterisk -rvvv
pjsip set logger on

What happens when a call is placed

1. The phone sends an INVITE to Asterisk with an SDP body listing its codecs and the IP and port where it wants audio.
2. Asterisk authenticates the INVITE the same way it authenticated the REGISTER, with a 401 challenge and a retry.
3. Asterisk drops the call into the endpoint's context and looks for a matching extension pattern.
4. Dial(PJSIP/1002) sends a new INVITE to each contact stored in the AOR of 1002.
5. When 1002 answers, Asterisk sends 200 OK back to the caller, both sides send ACK, and RTP audio flows. With direct_media=no, the audio passes through Asterisk; otherwise Asterisk may try to connect the two phones directly.

Why NAT options matter

Phones on home networks and mobile data sit behind routers that rewrite addresses. The phone then writes a private IP into its Contact and SDP, and Asterisk would send signalling and audio to an address it cannot reach. Three endpoint options fix this: force_rport=yes (answer to the port the request came from), rewrite_contact=yes (replace the Contact with the observed source address), and rtp_symmetric=yes (send audio to the address the phone's audio arrived from). Softphones such as SIPdia add STUN and ICE on their side. The combination is what makes remote extensions work; the Asterisk NAT documentation describes each option.

Where chan_sip fits

Older guides talk about sip.conf, peers and type=friend. That is chan_sip, the original SIP driver. It bundled the endpoint, auth and AOR into one peer section. chan_sip was deprecated in Asterisk 17 and removed in Asterisk 21, so new work should use PJSIP. The concepts carry over: a peer's secret is an auth, its host=dynamic is an AOR, and its context is the same context.

Next steps

• How to configure SIPdia with Asterisk (PJSIP) turns this into a complete working configuration, with transports and TLS.
• How to connect a softphone to an Asterisk PBX covers the phone side.
• Stuck on registration? Start with SIP 401 Unauthorized.