Asterisk

Asterisk
is a complete PBX (private branch exchange) in software. It runs on Linux, BSD, Windows and macOS and provides all of the features you would expect from a PBX and more. Asterisk does voice over IP in four protocols, and can interoperate with almost all standards-based telephony equipment using relatively inexpensive hardware.
Asterisk provides voice-mail services with directory, call conferencing, interactive voice response and call queuing. It has support for three-way calling, caller ID services, ADSI, IAX, SIP, H.323 (as both client and gateway), MGCP (call manager only) and SCCP/Skinny.
This article will show you how to configure a simple in house network enabling us to use a SIP
softphone
to talk to another SIP softphone on your LAN.
Installation
Install the
asterisk
AUR
package.
Alternatively, you can install the
asterisk-lts-18
AUR
or
asterisk-lts-20
AUR
package to have a long-term support release (current latest LTS major version is Asterisk 20). Asterisk LTS releases tend to have fewer features, but will be maintained for much longer. See the
Asterisk Versions
page for complete details about the release cycle for all Asterisk versions.
Enable/start
asterisk.service
.
You will also need a SIP
softphone
and at least two machines. Recommendations for SIP phones are
Blink
(
blink
AUR
) or
Linphone
(
liblinphone-git
AUR
).
To enable ilbc codec support add the following to the very beginning of the
build
section of the PKGBUILD:
cd ${pkgname}-${pkgver}/contrib/scripts
echo | ./get_ilbc_source.sh
Configuration
As of Asterisk 20, the legacy
chan_sip
module is no longer compiled by default. If you would rather use
chan_sip
than
res_pjsip
, please install
asterisk-lts-18
AUR
, which was the last LTS release to build
chan_sip
.
res_pjsip
is the newer, more performant Asterisk channel module that supports the standard SIP (Session Initiation Protocol) protocol, the primary VoIP (Voice over Internet Protocol) protocol in use by many carriers, telcos, Internet telephony service providers (ITSPs), and enterprises. However,
res_pjsip
is considerably more complicated to set up than the older
chan_sip
.
The prevailing wisdom of the wider Asterisk community suggests to only use
chan_sip
if you already have an existing configuration for it, while also planning the upgrade to
res_pjsip
. For any new installations,
res_pjsip
is recommended. As mentioned above,
chan_sip
is no longer maintained, not even for security fixes (except in older LTS releases), so new Asterisk PBX administrators should go with a supported SIP channel driver (i.e.,
res_pjsip
).
If you have an existing
chan_sip
configuration, to build it in Asterisk 20 LTS, you can do the following:  Edit the
asterisk-lts-20
AUR
PKGBUILD, in the
build()
function. Modify the following line:
PKGBUILD
make MENUSELECT_CFLAGS= OPTIMIZE= DEBUG= ASTVARRUNDIR="/run/$pkgname" NOISY_BUILD=1
Prefix it with a call to build the menuselect tool, and enable
chan_sip
:
PKGBUILD
make menuselect.makeoptions && \
menuselect/menuselect --enable chan_sip && \
make MENUSELECT_CFLAGS= OPTIMIZE= DEBUG= ASTVARRUNDIR="/run/$pkgname" NOISY_BUILD=1
Note that this will need to be done with every update of the
asterisk-lts-20
AUR
package.
PJSIP
Once installed, Asterisk has the
res_pjsip
configuration in
/etc/asterisk/pjsip.conf
. The sample file included with Asterisk gives several basic examples, but is not exhaustive for all pjsip options. Readers are encouraged to read the
Asterisk Wiki Security best practices article
, and
Configuring res_pjsip
before continuing.
This article contains a basic single SIP phone, multiple SIP trunk example, using
SIP Station SIP trunks, from Sangoma
. Two SIP trunks with SIP Station are configured for redundancy, as recommended by SIP Station. The following example was tested using a Sangoma/Digium D60 hardware phone, but any SIP 2.0 compliant hard- or softphone should suffice.
This example assumes the Asterisk PBX server and SIP phone are on a private IPv4 LAN, with a NAT router between the server/phone and the WAN/Internet. If you would like to use IPv6, please read the
Configuring res_pjsip for IPv6
article.
modules.conf
First, ensure
res_pjsip.so
is not prefixed with
noload =
. In this example, the
require =
prefix makes Asterisk fail to load if
chan_pjsip.so
fails to load. This is not absolutely necessary, but unless you are using other VoIP protocols it may not make sense for Asterisk to load if
res_pjsip
does not load.
/etc/asterisk/modules.conf
;...
require = chan_pjsip.so
;...
pjsip.conf
Before diving into configuring
pjsip.conf
, review the
PJSIP Configuration Wizard
. It is useful for the simple use case of only one SIP provider/ITSP, and handles many of the pjsip objects for this automatically.
The file
pjsip.conf
is an ini-style configuration file, with
[section-headers-in-square-brackets]
, and either a hash (
#
) or a semicolon (
;
) as the comment character. Each line under a section header is a
key=value
pair, with section-specific keys set to the specified values. Note that section headers can have
(!)
appended after the closing square bracket, which indicates the section is a template, for later use within
pjsip.conf
. To instantiate a section using a previously defined template, suffix the section header with the
(template-name)
.
transport section
In order to define a SIP trunk for use with Asterisk, PJSIP has the concept of a network
transport
. From the Asterisk Wiki, the transport section configures how
res_pjsip
will operate at the transport layer. For example, it supports configuration options for protocols such as TCP, UDP, or WebSockets and encryption methods like TLS/SSL.
Transport sections can be named arbitrarily, but it is recommended to name the section that makes it easy to remember what it signifies. The following example names it
[transport-udp-nat]
for identifying that this transport is using UDP for SIP, and is expected to traverse a NAT device.
/etc/asterisk/pjsip.conf
[transport-udp-nat]
type=transport  ; signifies this is a transport definition
protocol=udp  ; specifies this uses the UDP transport protocol
; this transport binds to all configured network interfaces, 
; replace with the IP address of the desired interface. 0.0.0.0 means all interfaces
bind=0.0.0.0
; =====  NOTE, the following directives are OPTIONAL
local_net=10.20.30.0/24  ; specify the networks that this Asterisk server should consider as local/LAN networks. Change this to the local LAN subnet (in CIDR notation)
local_net=127.0.0.0/8  ; specify the networks that this Asterisk server should consider as local/LAN networks (this one sets it to the IPv4 loopback network)
external_media_address=96.69.199.60  ; specify the external/WAN IP address for RDP media (audio)
external_signaling_address=96.69.199.60  ; specify the external/WAN IP address for SIP (signaling)
Note that only one transport is allowed for each IP address/port or IP address/protocol mapping. If you would like to configure multiple transport protocols (e.g. both TCP and UDP), you will need to bind each protocol to a different IP address. Likewise if you want to define multiple transports using the same protocol, the ports used need to be different for each transport definition.
registration section
Next, define the registrations the SIP trunks will use. Note that the SIP Station registrations are first defined via a template (with
(!)
appended to the section name). Each template defines the settings that are common for each section using the template;  the sections themselves only contain the options that need to be set for that section.
/etc/asterisk/pjsip.conf
[sipstation-reg](!)
type=registration
transport=transport-udp-nat
contact_user=15055551234
retry_interval=60

; ==== ... several other templates and sections will appear here
; ====     including the authentication sections, etc., which are also used by the registration
; ==== ....

[siptsation-reg1](sipstation-reg)
outbound_auth=sipstation-auth1 
server_uri=sip:trunk1.freepbx.com  ; trunk1 provided by SIP Station
client_uri=sip:my_username@trunk1.freepbx.com

[siptsation-reg2](sipstation-reg)
outbound_auth=sipstation-auth2 
server_uri=sip:trunk2.freepbx.com  ;  trunk2 provided by SIP Station
client_uri=sip:my_username@trunk2.freepbx.com
authentication section
Here, define the authentication template, and the specific authentication sections for use with the SIP Station trunks.
/etc/asterisk/pjsip.conf
[sipstation-auth](!)
type=auth
password=Super*Secret@Password!
username=my_username

; ==== ... more templates may appear here

[sipstation-auth1](sipstation-auth)
realm=trunk1.freepbx.com

[sipstation-auth2](sipstation-auth)
realm=trunk2.freepbx.com
endpoint section
An endpoint is essentially a profile for the configuration of a SIP device such as a phone or remote server. This defines the transport, the Asterisk Dialplan context where calls originating from the endpoint gets handled, and the audio codecs allowed for the endpoint. For the SIP station trunks, define the following:
/etc/asterisk/pjsip.conf
[sipstation-endpoint](!)
type=endpoint
transport=transport-udp-nat
context=from-external  ; Dialplan context, defined in extensions.conf or related file
disallow=all   ; disallows all codecs, including default ones, unless explicitly allowed below
allow=ulaw     ; standard G.711, uncompressed PCM codec. Uses the most bandwidth
allow=gsm      ; another standard, compressed codec. Uses less bandwidth than ulaw
; other codecs are available, and have different attributes. Some require paid licenses to use.
aors=sipstation-aors  ; AOR - Address of Record, to be defined later
;direct_media=no  ; setting this may not allow audio to pass through NAT
direct_media=yes
rtp_symmetric=yes

; ==== ... more template definitions

[sipstation-endpoint1](sipstation-endpoint)
outbound_auth=sipstation-auth1
from_domain=trunk1.freepbx.com

[sipstation-endpoint2](sipstation-endpoint)
outbound_auth=sipstation-auth2
from_domain=trunk2.freepbx.com
identify section
Controls how the res_pjsip_endpoint_identifier_ip module determines what endpoint an incoming packet is from. For the SIP Station trunks, the following is defined:
/etc/asterisk/pjsip.conf
[sipstation-identify](!)
type=identify
; this is the LAN IP address of the NAT router, which calls from the SIP Station
; trunks may appear to come from (because of NAT).
match=10.20.30.254/32

[sipstation-id1](sipstation-identify)
endpoint=sipstation-endpoint1
match=192.159.66.3   ;  IP address of trunk1.freepbx.com

[sipstation-id2](sipstation-identify)
endpoint=sipstation-endpoint2
match=162.253.134.142    ;  IP address of trunk2.freepbx.com
aor (Address Of Record) section
A primary feature of AOR objects (Address of Record) is to tell Asterisk where an endpoint can be contacted. Without an associated AOR section, an endpoint cannot be contacted. For the SIP Station trunks, define this:
/etc/asterisk/pjsip.conf
[sipstation-aors]
type=aor
contact=sip:trunk1.freepbx.com
contact=sip:trunk2.freepbx.com
phone sections
Finally, define the necessary sections for the SIP phone that will register to Asterisk. It has several similar sections as with the SIP Station trunks. Expand these with templates if multiple local SIP phones are intended to register to your Asterisk PBX. Remote phones (from the WAN/Internet) can also be configured, but that iss outside the scope of this example.
/etc/asterisk/pjsip.conf
[home-phone]
type=endpoint
transport=transport-udp-nat
context=from-internal  ;  Dialplan context that gets executed when a user dials from this phone
disallow=all
allow=ulaw
allow=gsm
auth=home-phone-auth
aors=home-phone

[home-phone-auth]
type=auth
auth_type=userpass
password=MyPhonePa$$word0
username=home-phone

[home-phone]
type=aor
max_contacts=1
Managing PJSIP
There are several commands regarding
res_pjsip
available in the Asterisk CLI, all prefixed with the
pjsip
command. To get to the Asterisk CLI, enter the following command, as the
asterisk
user:
$ asterisk -rvvv
This assumes Asterisk is already running (e.g., via the systemd service unit). Once in the Asterisk CLI, you will see the prompt
hostname*CLI>
. To see a list of available PJSIP commands, type
help pjsip
.
To see a list of PJSIP registrations, type the following:
hostname*CLI> pjsip show registrations
<Registration/ServerURI..............................>  <Auth....................>  <Status.......>
---------------------------------------------------------------------------------------------

 siptsation-reg1/sip:trunk1.freepbx.com                  sipstation-auth1            Registered        (exp. 2062s)
 siptsation-reg2/sip:trunk2.freepbx.com                  sipstation-auth2            Registered        (exp. 2069s)

Objects found: 2
To see a list of PJSIP endpoints, type the following:
hostname*CLI> pjsip show endpoints
Endpoint:  <Endpoint/CID.....................................>  <State.....>  <Channels.>
    I/OAuth:  <AuthId/UserName...........................................................>
        Aor:  <Aor............................................>  <MaxContact>
      Contact:  <Aor/ContactUri..........................> <Hash....> <Status> <RTT(ms)..>
  Transport:  <TransportId........>  <Type>  <cos>  <tos>  <BindAddress..................>
   Identify:  <Identify/Endpoint.........................................................>
        Match:  <criteria.........................>
    Channel:  <ChannelId......................................>  <State.....>  <Time.....>
        Exten: <DialedExten...........>  CLCID: <ConnectedLineCID.......>
 ----------------------------------------------------------------------------------------------

 Endpoint:  home-phone                                           Not in use    0 of inf
     InAuth:  home-phone-auth/home-phone
        Aor:  home-phone                                         1
      Contact:  home-phone/sip:home-phone@10.20.30.229:506 f91928f561 NonQual         nan
  Transport:  transport-udp-nat         udp      0      0  0.0.0.0:5060

 Endpoint:  sipstation-endpoint1                                 Not in use    0 of inf
    OutAuth:  sipstation-auth1/mw3FSBsPPjQ7
        Aor:  sipstation-aors                                    0
      Contact:  sipstation-aors/sip:trunk1.freepbx.com     256c242e36 NonQual         nan
      Contact:  sipstation-aors/sip:trunk2.freepbx.com     c07c6c7180 NonQual         nan
  Transport:  transport-udp-nat         udp      0      0  0.0.0.0:5060
   Identify:  sipstation-id1/sipstation-endpoint1
        Match: 10.20.30.254/32
        Match: 192.159.66.3/32

 Endpoint:  sipstation-endpoint2                                 Not in use    0 of inf
    OutAuth:  sipstation-auth2/mw3FSBsPPjQ7
        Aor:  sipstation-aors                                    0
      Contact:  sipstation-aors/sip:trunk1.freepbx.com     256c242e36 NonQual         nan
      Contact:  sipstation-aors/sip:trunk2.freepbx.com     c07c6c7180 NonQual         nan
  Transport:  transport-udp-nat         udp      0      0  0.0.0.0:5060
   Identify:  sipstation-id2/sipstation-endpoint2
        Match: 10.20.30.254/32
        Match: 162.253.134.142/32

Objects found: 3
chan_sip
Warning
chan_sip has been completely removed from Asterisk 21 (as available in the
asterisk
AUR
) and the wider Asterisk community is opposed to using it instead of the replacement chan_pjsip.
Note that the following instructions assume that you want to use already obsoleted
chan_sip
module. The
chan_sip
module is no longer maintained, but is easier to configure then the newer
res_pjsip
module. There is a summary of configuration changes between two modules, as well as instructions on how to migrate to the newer module, on the
Asterisk documentation
.
In order to use
chan_sip
, you need to explicitly load the older module, and ensure that the newer
chan_pjsip.so
module is unloaded. In
/etc/asterisk/modules.conf
adjust the following:
noload => chan_pjsip.so
noload => res_pjsip.so
;
noload => chan_sip.so
Add this to the following file:
/etc/asterisk/sip.conf
...
[me1]
type=friend
username=me1
secret=PASSWORD
host=dynamic
context=house

[me2]
type=friend
username=me2
secret=PASSWORD
host=dynamic
context=house
This creates our two SIP users
me1
and
me2
with a password of
PASSWORD
in the
house
context. The context will be defined next.
Add this to the following file:
/etc/asterisk/extensions.conf
[house]
exten => 100,1,Dial(SIP/me1)
exten => 101,1,Dial(SIP/me2)
This creates the context
house
and assigns extension 100 to the SIP user
me1
, and extension 101 to the SIP user
me2
.
Now all that is left is to see if it works.
Music on hold
Music on hold is a really sweet feature. And once again easy to install and configure.
Edit
/etc/asterisk/musiconhold.conf
and add, or make sure it is uncommented:
[default]
mode=files
directory=mohmp3
And that is all there is to it. Just copy your favorite legally obtained MP3 to
/var/lib/asterisk/mohmp3
.
Voicemail
Voicemail is another feature of asterisk. There are many ways to configure it, however this article only covers a simple approach.
Create/edit your
voicemail.conf
:
[general]
format=gsm|wav49|wav
serveremail=asterisk
attach=no
mailcmd=/usr/sbin/sendmail -t
maxmessage=180
maxgreet=60

[default]
100 => 1234,Me,me@mydomain.com
What does this mean? Most of the
[general]
is pretty self-explanatory. However, do note that if you have postfix set up right the PBX will send an email notifying the user of a new voice-mail and if
attach=yes
is defined it will attach the file.
Now for the actual mailbox. The format is:
mailbox => password,user,email
In this case, we gave 'Me' (email me@mydomain.com) mailbox 100, with a password of 1234.
Now we have to have a way to leave messages to this voice-mail, and a way to access it. 
For this, we go back to the
extensions.conf
and modify your existing entry as follows:
exten => 100,1,Dial(SIP/me1,20)
exten => 100,n,Voicemail(u100@default)
The 20 on the end of the first 'exten' tells 'Dial()' to call for 20 seconds. If no one answers it heads to voice-mail box 100 in the default context.
Next is actually accessing your voicemail. For this we add:
exten => 600,1,VoiceMailMain,s100@default
So when we call 600, the application 'VoiceMailMain' goes to 100 in the default context. The
s
allows for automatic login.
Note
The 'VoiceMail' applications have a significant amount of options, so it is suggested reading over some additional documentation. This is just for a basic, home use setup. Also note that it is generally a good idea to use extensions higher then your users extensions for accessing 'VoiceMail'. This way someone dialing 208 does not hit someone's voice-mail at 205.
Connecting to the PSTN
Now that you have the previous setup, it is time to actually connect to the outside world. To do this, you will need a provider such as
OnSIP
. Your provider should have instructions on connecting to asterisk, so this section is very general.
General set-up
sip.conf
[general]
register => username:password@sip.specific.com

[whatever]                   
fromdomain=specific.com     
host=sip.specific.com
insecure=very    ; check with provider
username=usernameduh
secret=passwordduh
type=peer
extensions.conf
[outboundwithCID]  ; this can be whatever
exten => _1NXXNXXXXXX,1,SetCIDNum(15555551234)
exten => _1NXXNXXXXXX,2,Dial(SIP/${EXTEN}@whatever)
exten => _1NXXNXXXXXX,3,Congestion()
exten => _1NXXNXXXXXX,103,Busy()

[default]  ; This should be set in your sip.conf for incoming calls

;These should to be changed to your actual number
; ie     15555555555
exten => 1NXXNXXXXXX,1,Answer()
exten => 1NXXNXXXXXX,2,Playback(ttt-weasels)
exten => 1NXXNXXXXXX,3,HangUp()
In the outbound context, any number dialed will be sent out to your service provider. The 'whatever' in the 2 priority should match what you have in your
sip.conf
.
Of course, the inbound dial-plan can be modified to do what you want. For instance, you can have
Dial(SIP/me1)
so when someone calls your number they are routed to your SIP phone on your computer. Then add in voice-mail and so on.
iax.conf
The first step is to log into FWD and enable their side of IAX. It is under extra features, and keep in mind that the authors claim it takes a little while to activate.
Now edit your
iax.conf
with the following in the 'general' section:
register => FWDNUMBER:PASSWORD@iax2.fwdnet.net 
disallow = all
allow = ulaw
And at the bottom add:
[iaxfwd]
type=user
context=fromiaxfwd
auth=rsa
inkeys=freeworlddialup
This allows calls from FWD.
extensions.conf
Place this at the top under '[globals]':
FWDNUMBER=MYFWDNUMBER ; your calling number
FWDCIDNAME="MyName"; your caller id
FWDPASSWORD=MYFWDPASSWORD ; your password
FWDRINGS=sip/office ; the phone to ring
FWDVMBOX=1000 ; the VM box for this user
Next, add this to a context for outgoing:
exten => _393.,1,SetCallerId,${FWDCIDNAME}
exten => _393.,2,Dial(IAX2/${FWDNUMBER}:${FWDPASSWORD}@iax2.fwdnet.net/${EXTEN:3},60,r)
exten => _393.,3,Congestion
You can change the '393' to whatever you want. This is what you will dial before dialing a 'fwd' number. For instance, to dial '744561' you would dial '393744561'.
And lastly, the incoming calls:
[fromiaxfwd]
exten => ${FWDNUMBER},1,Dial(${FWDRINGS},20,r)
exten => ${FWDNUMBER},2,Voicemail,u${FWDVMBOX}
exten => ${FWDNUMBER},102,Voicemail,b${FWDVMBOX}
Note
If you have problems try removing the variables from
extensions.conf
. These instructions are from FWD's site and I have not been tested by this article's author.
Extensions to try calling are 55555 (a volunteer maned test line) and 514 (conference).
Sounds
Sounds are stored in the folder
/var/lib/asterisk/xx
,
xx
stands for the code of the language for example "en" for English. To add new sounds copy them to the folder. Preserve the following folder structure:
/var/lib/asterisk/sounds/xx
/var/lib/asterisk/sounds/xx/digits
/var/lib/asterisk/sounds/xx/letters
/var/lib/asterisk/sounds/xx/phonetic
Edit the language parameter in the
sip.conf
[general]
...
language=en
...
Possible sources for sounds are:
https://downloads.asterisk.org/pub/telephony/sounds/
https://packages.debian.org/wheezy/all/asterisk-prompt-xx
fr
de
...
voip-info.org
MeetMe
MeetMe is the application that allows you to do conference calling. Same as everything, basic setup is easy.
Edit
meetme.conf
:
conf => 1000
Next is
extensions.conf
:
exten => 999,1,MeetMe(1000|M)
Now dial 999 to get into conference 1000. The
enables music on hold if no one is in there. It will automatically go away when someone joins the conference.
Note
You
must
have the zaptel package in order for MeetMe to work. Install it and run
modprobe ztdummy
before running asterisk. This provides digium timing for us without cards so we can utilize TDM.
Asterisk console and softphones
Now lets get Asterisk going:
# asterisk -vvvvvvc
This will give us the Asterisk CLI with verbose output. If Asterisk is already running you will need to use:
# asterisk -r
Now fire up your SIP clients and set them up with the information in the sip.conf. Switch back to your Asterisk CLI and you should see:
Registered SIP 'me1' at 192.168.0.142 port 5061 expires 60
Now you should be able to dial
101
from
me1
and talk to
me2
.
Troubleshooting
If you receive a 404 Not Found error check your
extensions.conf
and the number you dialed.