Asterisk PBX Complete Guide

1. What is Asterisk?

2. Key Features

3. Architecture & Key Configuration Files

All Asterisk configuration files are typically located in /etc/asterisk/. Below are the most important files:

Important Directories

4. Essential CLI Commands

Connect to the Asterisk console with asterisk -rvvv and use these commands. Prefix with asterisk -rx to run from the Linux shell.

5. Common Issues & Fixes

6. Sample Dialplan Examples (extensions.conf)

Example 1: Basic Internal Calling

[internal]
; Internal extensions 100-199
exten => _1XX,1,NoOp(Calling extension ${EXTEN})
 same => n,Dial(PJSIP/${EXTEN},30,tTrR)
 same => n,GotoIf($[${DIALSTATUS} = BUSY]?busy:unavail)
 same => n(busy),Playback(vm-isonphone)
 same => n,Hangup()
 same => n(unavail),VoiceMail(${EXTEN}@default,u)
 same => n,Hangup()

; Voicemail access
exten => *98,1,VoiceMailMain(${CALLERID(num)}@default)
 same => n,Hangup()

Example 2: IVR Menu (Auto Attendant)

[ivr-main]
exten => s,1,Answer()
 same => n,Wait(1)
 same => n,Set(TIMEOUT(response)=5)
 same => n(menu),Background(custom/welcome-menu)
 same => n,WaitExten(5)
 same => n,Goto(s,menu)

; Press 1 for Sales
exten => 1,1,Goto(queue-sales,s,1)
; Press 2 for Support
exten => 2,1,Goto(queue-support,s,1)
; Press 3 for Directory
exten => 3,1,Directory(default,internal,f)
; Press 0 for Operator
exten => 0,1,Dial(PJSIP/100,30)
 same => n,Hangup()
; Invalid input
exten => i,1,Playback(invalid)
 same => n,Goto(ivr-main,s,menu)
; Timeout
exten => t,1,Goto(ivr-main,s,menu)

Example 3: Outbound Dialing via SIP Trunk

[outbound]
; Local calls (10 digits)
exten => _NXXNXXXXXX,1,NoOp(Local call to ${EXTEN})
 same => n,Set(CALLERID(num)=5551234567)
 same => n,Dial(PJSIP/${EXTEN}@my-sip-trunk,60)
 same => n,Hangup()

; International calls (011 + country code)
exten => _011.,1,NoOp(International call to ${EXTEN})
 same => n,Set(CALLERID(num)=5551234567)
 same => n,Dial(PJSIP/${EXTEN}@my-sip-trunk,120)
 same => n,Hangup()

; Emergency
exten => 911,1,Dial(PJSIP/911@my-sip-trunk,60)
 same => n,Hangup()

Example 4: Time-Based Routing

[incoming]
exten => s,1,Answer()
 same => n,GotoIfTime(09:00-17:00,mon-fri,*,*?open)
 same => n,GotoIfTime(09:00-13:00,sat,*,*?open)
 same => n,Goto(closed)
 same => n(open),Goto(ivr-main,s,1)
 same => n(closed),Playback(custom/office-closed)
 same => n,VoiceMail(100@default,u)
 same => n,Hangup()

; Holiday check (alternative)
; exten => s,1,GotoIf($[${DB(holidays/${STRFTIME(${EPOCH},,%Y%m%d)})} = 1]?holiday)
;  same => n(holiday),Playback(custom/holiday-greeting)
;  same => n,VoiceMail(100@default,u)
;  same => n,Hangup()

7. SIP (chan_sip) vs PJSIP Comparison

chan_sip (sip.conf) is the legacy SIP driver deprecated since Asterisk 17 and removed in Asterisk 21. PJSIP (pjsip.conf) is the modern, recommended SIP stack.

Sample PJSIP Endpoint Configuration

; /etc/asterisk/pjsip.conf

[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060
external_media_address=YOUR_PUBLIC_IP
external_signaling_address=YOUR_PUBLIC_IP
local_net=192.168.1.0/24

; Extension 100
[100]
type=endpoint
context=internal
disallow=all
allow=ulaw,alaw,opus
auth=100-auth
aors=100
callerid="John Doe" <100>
webrtc=no

[100-auth]
type=auth
auth_type=userpass
username=100
password=SecurePass123!

[100-aor]
type=aor
max_contacts=3
remove_existing=yes
qualify_frequency=30

; SIP Trunk
[my-sip-trunk]
type=endpoint
context=from-trunk
disallow=all
allow=ulaw,alaw
outbound_auth=trunk-auth
aors=trunk-aor

[trunk-auth]
type=auth
auth_type=userpass
username=your_trunk_user
password=your_trunk_pass

[trunk-aor]
type=aor
contact=sip:sip.provider.com

[trunk-reg]
type=registration
outbound_auth=trunk-auth
server_uri=sip:sip.provider.com
client_uri=sip:your_trunk_user@sip.provider.com

8. Useful Resources