PJSIP Overview
Unlike the legacy chan_sip which used a single configuration block per peer, PJSIP uses a modular design with multiple object types that work together. This can seem complex at first, but it provides much more flexibility and clarity.
Why PJSIP: chan_sip is deprecated and no longer actively developed. PJSIP supports multiple transports per endpoint, better NAT handling, WebRTC, and improved performance. All new Asterisk installations should use PJSIP.
PJSIP uses six main object types:
Transport
Defines how SIP messages are sent (UDP, TCP, TLS, WebSocket)
Endpoint
Represents a SIP device or trunk - the core configuration object
AOR
Address of Record - where a device can be reached
Auth
Authentication credentials (username/password)
Identify
Matches inbound traffic to an endpoint by IP
Registration
Registers Asterisk to an external SIP server
Transports
Transports define the network protocol and port for SIP communication. You need at least one, and most systems define UDP and optionally TLS:
; UDP transport (standard SIP)
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060
; NAT settings - set to your public IP
external_media_address=YOUR_PUBLIC_IP
external_signaling_address=YOUR_PUBLIC_IP
local_net=10.0.0.0/8
local_net=172.16.0.0/12
local_net=192.168.0.0/16
; TLS transport (encrypted SIP)
[transport-tls]
type=transport
protocol=tls
bind=0.0.0.0:5061
cert_file=/etc/asterisk/keys/asterisk.crt
priv_key_file=/etc/asterisk/keys/asterisk.key
method=tlsv1_2Important: Transports cannot be reloaded without restarting Asterisk. If you change transport settings, you must run core restart now rather than pjsip reload.
Endpoints
Endpoints are the central PJSIP object. Every SIP phone, softphone, or trunk is an endpoint. They reference other objects (AOR, auth) and define media settings:
; SIP phone extension 100
[100]
type=endpoint
context=internal
disallow=all
allow=ulaw
allow=alaw
transport=transport-udp
auth=100
aors=100
callerid="John Smith" <100>
; NAT settings for phones behind NAT
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes
; Voicemail
mailboxes=100@defaultKey endpoint options explained:
- context - The dialplan context for calls from this endpoint
- disallow/allow - Codec negotiation (always disallow=all first, then allow specific codecs)
- direct_media=no - Routes media through Asterisk (required for recording, and for NAT)
- rtp_symmetric=yes - Send RTP to the same address/port from which it was received (NAT fix)
- force_rport=yes - Force use of the port from the received packet (NAT fix)
- rewrite_contact=yes - Rewrite the Contact header with the received address (NAT fix)
AORs (Address of Record)
AORs define where a device can be reached and how many simultaneous registrations are allowed:
; AOR for extension 100 (phone registers to Asterisk)
[100]
type=aor
max_contacts=1
remove_existing=yes
qualify_frequency=60
; AOR for a trunk (static contact, no registration)
[ipcomms]
type=aor
contact=sip:sip.ipcomms.net:5060
qualify_frequency=60- max_contacts - How many devices can register with this AOR simultaneously
- remove_existing - Remove old registrations when max is exceeded (avoids ghost registrations)
- qualify_frequency - Send OPTIONS pings every N seconds to check if the device is reachable
- contact - Static contact URI for trunks that do not register to your system
Authentication
Auth objects store credentials for inbound authentication (phones registering to Asterisk) and outbound authentication (Asterisk registering to a trunk provider):
; Inbound auth - phone authenticates TO Asterisk
[100]
type=auth
auth_type=userpass
username=100
password=xK9mP2vL7nQ4rT8
; Outbound auth - Asterisk authenticates TO provider
[ipcomms-auth]
type=auth
auth_type=userpass
username=your_ipcomms_username
password=your_ipcomms_passwordTip: For inbound auth (phones), the auth object name must match the name referenced by the endpoint's auth= setting. For outbound auth (trunks), reference it in the outbound_auth= endpoint setting.
Identify
Identify objects match inbound SIP traffic to an endpoint based on the source IP address. This is essential for trunks using IP authentication where there is no REGISTER to identify the source:
; Match inbound calls from IPComms to the ipcomms endpoint
[ipcomms-identify]
type=identify
endpoint=ipcomms
match=34.23.59.14Without an identify section, Asterisk will not know which endpoint to associate with inbound INVITE requests from your SIP trunk provider. The call will be rejected.
Registration
Registration objects tell Asterisk to register with an external SIP server. This is needed when your trunk provider uses digest authentication:
[ipcomms-reg]
type=registration
transport=transport-udp
outbound_auth=ipcomms-auth
server_uri=sip:sip.ipcomms.net
client_uri=sip:your_username@sip.ipcomms.net
retry_interval=60
expiration=3600IP Auth vs Registration: If you use IP authentication with IPComms, you do NOT need a registration object. Just use an identify section to match inbound traffic. IP auth is simpler and more secure.
Complete Working Example
Here is a complete pjsip.conf with a transport, one phone extension, and an IPComms trunk using IP authentication:
;=== TRANSPORT ===
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060
external_media_address=203.0.113.10
external_signaling_address=203.0.113.10
local_net=192.168.1.0/24
;=== EXTENSION 100 ===
[100]
type=endpoint
context=internal
disallow=all
allow=ulaw
allow=alaw
transport=transport-udp
auth=100
aors=100
callerid="John Smith" <100>
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes
mailboxes=100@default
[100]
type=auth
auth_type=userpass
username=100
password=xK9mP2vL7nQ4rT8
[100]
type=aor
max_contacts=1
remove_existing=yes
qualify_frequency=60
;=== IPCOMMS TRUNK (IP Auth) ===
[ipcomms]
type=endpoint
context=from-ipcomms
disallow=all
allow=ulaw
allow=alaw
transport=transport-udp
aors=ipcomms
direct_media=no
[ipcomms]
type=aor
contact=sip:sip.ipcomms.net:5060
qualify_frequency=60
[ipcomms-identify]
type=identify
endpoint=ipcomms
match=34.23.59.14Troubleshooting PJSIP
; Show all endpoints and their status
pjsip show endpoints
; Show specific endpoint details
pjsip show endpoint 100
; Show all registrations
pjsip show registrations
; Show AOR contacts (who is registered)
pjsip show aors
; Show transport status
pjsip show transports
; Enable SIP debugging
pjsip set logger on
; Reload PJSIP config (NOT transports)
pjsip reloadRemember: pjsip reload reloads endpoints, AORs, and auth, but NOT transports. Transport changes require core restart now.
Need a SIP Trunk for Your Asterisk System?
IPComms provides reliable SIP trunking optimized for Asterisk PJSIP. IP authentication, no contracts, and VoIP engineers on support.