Skip to main content

Asterisk PJSIP

This guide describes the setup of a sipcall sip trunk or a sipcall virtual pbx phone number with Asterisk (LTS version 22) using PJSIP.

Prerequisites​

  • Asterisk is already installed
  • Root or sudo access to the server
  • Basic Linux knowledge
  • Network and firewall knowledge
  • Credentials from sipcall (SIP server, User id, VoIP password):

    The configuration data can be found in the customer portal under "Phone numbers" -> "Phone number overview". Click on the desired phone number to view the configuration data (within the "SIP-Data" card).

Configuration​

Place the Asterisk configuration files in the /etc/asterisk/ directory.

The system automatically checks and reads these when the Asterisk service starts.

Register phone number​

To register the sipcall phone number with Asterisk, you need the following PJSIP objects in the pjsip.conf file: registration, endpoint, auth and aor.
For completeness, start the configuration with the transport object type.

The following example configuration can be used as a template.

/etc/asterisk/pjsip.conf
; ******* TRANSPORT *******
[transport-udp]
type = transport
protocol = udp
bind = 0.0.0.0:5060

; ******* sipcall RN <User id> https://kb.sipcall.ch/enddevices/phonesystems/asterisk  ******* 
[sipcall]
type = registration
transport = transport-udp
server_uri = sip:<SIP server>:5060
client_uri = sip:<User id>@<SIP server>
contact_user = <User id>
outbound_auth = sipcall
expiration = 60
endpoint = sipcall
line = yes
max_retries = 10000
fatal_retry_interval = 30
forbidden_retry_interval = 30

[sipcall]
type = endpoint
transport = transport-udp
context = from-pstn-toheader
disallow = all
allow = g722,alaw,ulaw
rtp_keepalive = 1
outbound_auth = sipcall
aors = sipcall
rewrite_contact = yes
direct_media = no
force_rport = no

[sipcall]
type = auth
auth_type = digest
username = <User id>
password = <VoIP password>

[sipcall]
type = aor
contact = sip:<SIP server>:5060

  • Replace the placeholders <User id>, <SIP server> and <VoIP password> with the configuration data provided from the sipcall customer portal.
Explanations
  • type = transport: Defines general network parameters that the Asterisk service listens on.
  • type = registration: Registration parameters of the sipcall sip trunk/sipcall phone number (virtual pbx/free/classic/home). Replace the placeholders <SIP server> and <User id> with the configuration data provided from the sipcall customer portal.
  • type = endpoint: Defines the audio settings and logic.
  • type = auth: Defines the authentication. Replace the placeholders <VoIP Password> and <User id> with the configuration data provided from the sipcall customer portal.
  • type = aor: The contact address for outgoing calls (Address of Record). Replace the placeholder <SIP server> with the value from the configuration data provided from the sipcall customer portal.

Restart

Restart Asterisk to load the configuration:

sudo asterisk -rx "core restart now"

Receive calls​

  • Add the following dialplan context to the extensions.conf:
/etc/asterisk/extensions.conf
; ****** sipcall inbound calls  ******
[from-pstn-toheader]
exten = _X.,1,Set(to_user=${CUT(CUT(PJSIP_HEADER(read,To),@,1),:,2)})
same = n,GoTo(<Context-Name>,${to_user},1)
  • Replace the placeholder <Context name> with a valid context.
Explanations

To process calls correctly, a dialplan context is needed, which is defined in the extensions.conf file.

When registering the phone number, context = from-pstn-toheader was defined to execute this dialplan context. It takes the phone number from the "SIP-To" header and forwards it to <Context name>.

In the <Context name> field, a valid context must be set. You can name it freely. In practice, this would be for example from-external or for a test hello-world.

Test incoming external calls with "Hello World"​

  • In the dialplan context from-pstn-toheader, set the value hello-world for the placeholder <Context name>.
  • Add the following dialplan context to the file:
/etc/asterisk/extensions.conf
[hello-world]
exten = <User id>,1,NoOp(sipcall incoming call <User id>)
same = n,Wait(1)
same = n,Playback(hello-world)
same = n,Hangup()
  • Replace the placeholder <User id> with the value from the configuration data provided from the sipcall customer portal.
Explanations

When your phone number is called, Asterisk plays the hello-world file and ends the call.

Forward incoming external calls to an internal user​

  • Add the following dialplan context from-external to the file:
/etc/asterisk/extensions.conf
[from-external]
; sipcall phone number is routed to endpoint 200
exten = <User id>,1,Dial(PJSIP/200)
same = n,Hangup()
  • Replace the placeholder <User id> with the value from the configuration data provided from the sipcall customer portal.
Explanations

This section forwards the incoming call to the internal extension 200. It ensures that only calls to the registered phone number (<User id>) are processed. This prevents the extension from receiving ghost calls.

Further information can be found in the Asterisk documentation.

Register endpoints on Asterisk​

To connect endpoints to Asterisk, create internal "endpoints" in the pjsip.conf file. In our example, this is a SIP extension with the internal number 200.

/etc/asterisk/pjsip.conf
; internal extension 200
[200]
type = endpoint
transport = transport-udp
context = from-internal
callerid = "Max Muster" <200>
disallow = all
allow = g722,alaw,ulaw
aors = 200
auth = 200
force_rport = no
rtp_symmetric = yes
rewrite_contact = yes
direct_media = no

[200]
type = auth
auth_type = userpass
password = secure password ; Password for the internal extension
username = 200

[200]
type = aor
max_contacts = 2
Explanations
  • callerid: Serves as an internal value: The display name is defined with "", the internal callback number with <>. When the call goes external, the caller ID is overwritten with the user id.

Outgoing calls​

In our example, we assigned the context from-internal to the internal extension 200.

For extensions to make outgoing calls, we need this dialplan context in the extensions.conf file.

/etc/asterisk/extensions.conf
; ****** sipcall outbound calls RN <User id> ******
[from-internal]
include = emergency calls

; ***** internal calls *****
exten = _NXX,1,NoOp(Internal Call to User with 3 Digits)
same = n,Dial(${PJSIP_DIAL_CONTACTS(${EXTEN})},30)
same = n,Hangup()


; ***** external calls *****
exten = _0X.,1,NoOp(Internal Call to external Numbers with 0)
same = n,Set(CALLERID(num)=<User id>)
same = n,Dial(PJSIP/${EXTEN}@sipcall)

exten = _+X.,1,NoOp(Internal Call to external Numbers with +)
same = n,Set(CALLERID(num)=<User id>)
same = n,Dial(PJSIP/${EXTEN}@sipcall)
  • Replace the placeholder <User id> with the value from the configuration data provided from the sipcall customer portal.
Explanations
  • include = emergency-calls includes the dialplan context for emergency numbers.
  • In the "internal calls" section, calls matching the pattern _NXX (three digits, numbers, first digit is not 0 or 1) are routed internally.
  • If the pattern does not match, the second section is executed. Here, calls matching the pattern _0X. (number with leading 0) are routed externally via sipcall.
  • If this also does not match, the third section is executed. Here, calls matching the pattern _+X. (number starting with +) are routed externally via sipcall.
  • In the second and third sections, the caller ID of the extension is overwritten with the user id.

Further options can be found in the pattern matching documentation.

Emergency numbers​

For the reachability of emergency numbers, an additional dialplan context is needed. This is already included in the dialplan context [from-internal] with the line include = emergency-calls.

You can copy this dialplan context directly into your dialplan:

/etc/asterisk/extensions.conf
; ****** Emergency calls for RN <User id> ******
[emergency-calls]
; European emergency number
exten = 112,1,GoSub(emergency-handler,${EXTEN},1)

; Police emergency
exten = 117,1,GoSub(emergency-handler,${EXTEN},1)

; Fire department emergency
exten = 118,1,GoSub(emergency-handler,${EXTEN},1)

; Victim assistance hotline
exten = 142,1,GoSub(emergency-handler,${EXTEN},1)

; Helpline (Dargebotene Hand)
exten = 143,1,GoSub(emergency-handler,${EXTEN},1)

; Ambulance, emergency medical services
exten = 144,1,GoSub(emergency-handler,${EXTEN},1)

; Poisoning
exten = 145,1,GoSub(emergency-handler,${EXTEN},1)

; Youth helpline
exten = 147,1,GoSub(emergency-handler,${EXTEN},1)

; Air Zermatt, air rescue
exten = 1410,1,GoSub(emergency-handler,${EXTEN},1)

; Rega air rescue
exten = 1414,1,GoSub(emergency-handler,${EXTEN},1)

; Air-Glaciers, air rescue
exten = 1415,1,GoSub(emergency-handler,${EXTEN},1)

; EU hotline for victims of violence against women
exten = 116016,1,GoSub(emergency-handler,${EXTEN},1)

; EU hotline for children
exten = 116111,1,GoSub(emergency-handler,${EXTEN},1)

; EU hotline for victims of crime
exten = 116006,1,GoSub(emergency-handler,${EXTEN},1)

; EU hotline for missing children
exten = 116000,1,GoSub(emergency-handler,${EXTEN},1)


[emergency-handler]
exten = _X.,1,NoOp(Calling ${EXTEN})
same = n,Set(CALLERID(num)=<User id>)
same = n,Dial(PJSIP/${EXTEN}@sipcall)
same = n,Hangup()
  • Replace the placeholder <User id> with the value from the configuration data provided from the sipcall customer portal.

Notes on CLIP​

sipcall prevents CLIP spoofing. If the set caller ID does not match the criteria, the CLIP is overwritten. Further information can be found under the function description "Caller ID display (CLIP)" in the Outgoing calls section.

Security notes​

Pay attention to the following points during configuration:

  • Password security: Use strong passwords for internal endpoints.
  • Fail2Ban: It is recommended to install Fail2Ban, Crowdsec or similar applications to prevent brute-force attacks.
  • Firewall: Restrict external access to the SIP port to block ghost calls and SIP scanners at the firewall level. The list of our SIP server IP addresses can be found here.
  • Separate contexts: Strictly separate internal and external contexts to prevent unauthorized external calling.

Apply changes​

To apply changes without restarting the entire system, use the following commands within the Asterisk CLI:

  • pjsip reload (reloads the PJSIP configuration)
  • dialplan reload (reloads the dialplan)

Alternatively, restart the service:

  • sudo asterisk -rx "core restart now"

Further resources​

Further information about configuring Asterisk can be found on the project homepage:

Last updated on