Latest revision as of 21:11, 12 March 2025

IPv6 Works!

Asterisk is extremely flexible and covering different uses for it is outside the scope of this example as the setup used here was very basic. You should read through the included documentation, especially the security documentation, before configuring Asterisk for the first time.

Configuration

Asterisk has two methods to configure SIP connections. The legacy "sip.conf" (SIP) and the more modern "pjsip.conf" (PJSIP).

Newer installations of Asterisk should be configured to use PJSIP as it will be more supported as Asterisk development continues, however it's been reported that PJSIP doesn't support in-band DTMF detection properly. You may need to switch back to legacy sip.conf if this affects you. The official recommendation on the PJSIP FAQ seems to be to write your own plugin if you need it. In-band DTMF support seems like an important thing to have, so we suggest raising a bug to report a missing feature in PJSIP if this affects you!

It isn't a good idea to have an installation that mixes sip.conf with pjsip.conf.

When reading the instructions below be aware which are for sip.conf and which are for pjsip.conf.

pjsip.conf (PJSIP)

PJSIP: Trunk registration

Here is an example of a working pjsip.conf setup where Asterisk will register with A&A to receive calls.
It is recommended you read the "PJSIP: NAT Issues: Keep-Alive / Anti-Idle" section below as you may wish to comment out or drastically increase the qualify_frequency line(s) if your Asterisk is not behind NAT.

In pjsip.conf:

   [reg_442082881111]
   type = registration
   retry_interval = 20
   fatal_retry_interval = 20
   forbidden_retry_interval = 20
   max_retries = 9999
   auth_rejection_permanent = no
   contact_user = maininbound
   expiration = 120
   outbound_auth = auth_reg_442082881111
   client_uri = sip:+442082881111@voiceless.aa.net.uk
   server_uri = sip:voiceless.aa.net.uk
   
   [auth_reg_442082881111]
   type = auth
   password = BusinessPaidGrewCome
   username = +442082881111
   
   [aaisptrunk]
   type = aor
   contact = sip:+442082881111@voiceless.aa.net.uk
   qualify_frequency=20

   [aaisptrunk_servera]
   type = aor
   contact = sip:+442082881111@a.voiceless.aa.net.uk
   qualify_frequency=20

   [aaisptrunk_serverb]
   type = aor
   contact = sip:+442082881111@b.voiceless.aa.net.uk
   qualify_frequency=20
   
   [aaisptrunk]
   type = identify
   endpoint = aaisptrunk
   match = voiceless.aa.net.uk
   
   [aaisptrunk]
   type = endpoint
   context = maininbound
   dtmf_mode = rfc4733
   disallow = all
   allow = alaw
   allow = ulaw
   direct_media = no
   rtp_symmetric = yes
   aors = aaisptrunk,aaisptrunk_servera,aaisptrunk_serverb
   outbound_auth=auth_reg_442082881111

Calls come into the context "maininbound" in extensions.conf - in this example calls get sent onto extension 222 and 205 for 20 seconds and then go to voicemail.

[maininbound]
exten = maininbound,1,Dial(PJSIP/222&PJSIP/205,20)
exten = maininbound,n,Voicemail(222@default,us)

In extensions.conf you can dial out via the trunk with:

exten => _X.,1,Dial(PJSIP/${EXTEN}@aaisptrunk,,)

exten => s-BUSY,1,Playtones(busy)
exten => s-CONGESTION,1,Playtones(congestion)
exten => s-CHANUNAVAIL,1,Playtones(unobtainable)
exten => s-NOANSWER,1,Playtones(congestion)

PJSIP: Trunk without registration

Use the above example but do not include the top section for "[reg_442082881111]".

Then set the AAISP control panel to point to your server by hostname or IP address:

PJSIP: NAT Issues: Keep-Alive / Anti-Idle

If you are using a firewall or NAT router with short timeouts on UDP sessions the example registration configuration above enables OPTIONS packets to be sent over the connection to keep it alive. A symptom of NAT issues can be inbound call delivery working for a bit after startup, then not working (with the code "183" in the CDR in the control panel) then calls working again a number of minutes later without you doing anything (or possibly reloading or restarting asterisk will solve it for a bit).

As Andrews & Arnold have multiple call servers it is possible for call signalling to come from multiple IP addresses. Your NAT session or SIP helper/ALG may only be allowing SIP traffic from the IP address your Asterisk registered to.

In the PJSIP registration example on this page the problem is solved by having three AOR (Address of Record) sections. All three have qualify_frequency set (this makes asterisk send keepalive packets). The endpoint section then references the 3 aor entries.
Your Asterisk server will send outbound packets to the shared hostname, and the two call servers specifically. This has the effect of keeping the NAT session on your router alive for all the call servers meaning it doesn't matter which call server delivers the INVITE (call), it should always reach your Asterisk server.

PJSIP: IPv6

By default PJSIP does not listen on IPv6.
At the top of pjsip.conf you will need to add another transport to go along with your IPv4 transport (usually a section with bind set to 0.0.0.0 or your IP address):

[transport-udp6]
type=transport
protocol=udp
bind=[::]

You may need to force the endpoint to use this transport (a small section of the endpoint section above but with the "transport = " line inserted):

[aaisptrunk]
type = endpoint
transport = transport-udp6

Status and Commands

A good command within the asterisk software is the show registration command:

asterisk*CLI> pjsip show registrations

 <Registration/ServerURI..............................>  <Auth..........>  <Status.......>
==========================================================================================

 reg_442082881111/sip:voiceless.aa.net.uk                auth_reg_442082881111  Registered

Objects found: 1

In this example it shows that the Asterisk server is successfully registered with the Andrews & Arnold SIP server.

sip.conf (SIP)

Incoming Calls

User Section

Accept authenticated calls and route them to a context.

sip.conf:

[aaisp-incoming-username]
type=user
context=aaisp-incoming-context
secret=aaisp-incoming-password
transport=udp
disallow=all
allow=alaw
trustrpid=yes
directmedia=no

We send Remote-Party-Id with the privacy and screen settings, setting trustrpid=yes in the incoming SIP config will allow Asterisk to pass withheld/unknown on.

Authentication

Voiceless must authenticate so that calls are recognised as the above peer section.
You need to use the match_auth_username=yes setting otherwise Asterisk will not recognise Voiceless' initial requests.

sip.conf:

[general]
match_auth_username=yes

We initially send an Authorization header with only a username, allowing Asterisk to identify Voiceless by username instead of by IP. By default Asterisk ignores the username when identifying peers.

Outgoing Calls

Either use a separate type=peer section or combine incoming and outgoing in one type=friend section

Separate Section

sip.conf:

[aaisp-outgoing-account]
type=peer
host=voiceless.aa.net.uk
defaultip=81.187.30.111
defaultuser=aaisp-phone-number
remotesecret=aaisp-outgoing-password
transport=udp
disallow=all
allow=alaw
directmedia=no

Combined Section

sip.conf:

[aaisp-incoming-username]
type=friend
transport=udp
disallow=all
allow=alaw
directmedia=no
; incoming
context=aaisp-incoming-context
secret=aaisp-incoming-password
trustrpid=yes
; outgoing
host=voiceless.aa.net.uk
defaultip=81.187.30.111
defaultuser=aaisp-phone-number
remotesecret=aaisp-outgoing-password

Note: Order of sip.conf is important

In sip.conf, ensure that your incoming config is before the config for the outgoing.

Note: Asterisk and IPv6 SLAAC addresses

Asterisk will bind to all IPv6 addresses if it is set to use IPv6. This means that if you have a static IP and a SLAAC IP, Asterisk sometimes replies to invites sent to the static IP from the SLAAC IP instead which breaks things. We recommend using static IP addresses and disabling SLAAC (and privacy extensions) on the box running Asterisk until its IPv6 support is more mature.

Registration

If you're behind NAT it is helpful to make Asterisk register. It re-registers every 120 seconds by default anyway so should keep NAT sessions open. You can register (and tell Asterisk that it's behind NAT) with these settings under the [general] section:

localnet=10.0.0.0/8
register => +441234567980:outgoingpass@voiceless.aa.net.uk/extn

In this example, extn is the extension that Asterisk will pass the call to. Localnet should of course be set to whatever RFC1918 range you are using on your LAN.

Dialplan

To make this work in a real dialplan you will want something like the following examples in extensions.conf. See Asterisk's included example sip.conf for examples of how to send the call to different contexts etc. For outbound calls:

exten => _X.,1,Dial(SIP/voiceless-out/${EXTEN})

For inbound calls (assuming you're routing call to a registered Snom):

[voiceless-in]
exten => _X.,1,Dial(SIP/snom)

Firewall & Security

You will also want to set up firewall rules, as per the VoIP Firewall page.
Also see the VoIP Security page for information about securing your VoIP service.