VoIP Phones - Asterisk: Difference between revisions

Back up to the VoIP Configuring page
From AAISP Support Site
No edit summary
 
(36 intermediate revisions by 8 users not shown)
Line 1: Line 1:
<indicator name="VoIPConfiguring">[[File:menu-voip.svg|link=:Category:VoIP Phones|30px|Back up to the VoIP Configuring page]]</indicator>
[[File:Asterisk_logo.png]]
[[File:Asterisk_logo.png]]


*IPv6 Works!
*[[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.
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 =
==Define proxies for inbound calls==
Asterisk has two methods to configure SIP connections. The legacy "sip.conf" (SIP) and the more modern "pjsip.conf" (PJSIP).
Some background first:


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 [https://trac.pjsip.org/repos/wiki/FAQ#dtmf 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!
Asterisk performs a '''forward''' DNS lookup on incoming calls. This means that even where the Asterisk box has registered, if the call comes in from the IP it registered to on a dual stack box but the lookup returns the other IP, Asterisk gets confused about where to route the call. It does not seem to cache the IP address it finds for the duration of the TTL either, so you can register one minute, then have a call from the same IP fail the next.


It isn't a good idea to have an installation that mixes sip.conf with pjsip.conf.
Unfortunately the only way around this seems to be to define a peer for each potential IP address that a call can come from. We only have two live "voiceless" servers at present (and a third test box) but it means that as we expand the service in future Asterisk users would have to keep updating their SIP configs. We therefore created a list of 10 servers (C and onwards are just A records pointing to the A server for now). Sadly this means that we needed to created 20 peers as they will all be dual stack!


When reading the instructions below be aware which are for sip.conf and which are for pjsip.conf.
If your Asterisk box is not dual stack you only need to include the IPv4 '''or''' IPv6 hostnames; whichever you're using.


=pjsip.conf (PJSIP)=
If you are not registering you will need to set up the username, password and host name for the trunk in the "SIP to your server" settings on the control pages. We do not recommend registering unless you're on a dynamic IP or behind NAT.


==PJSIP: Trunk registration==
Here is what the config looks like for a dual stack Asterisk box on static public IPs:
Here is an example of a working pjsip.conf setup where Asterisk will register with A&A to receive calls.


In pjsip.conf:
<syntaxhighlight>
[reg_442082881111]
; Config for inbound calls
type = registration
[voiceless-common](!)
retry_interval = 20
type=peer
fatal_retry_interval = 20
; The following 2 values are set in the "SIP to your server" trunk settings on the control pages.
forbidden_retry_interval = 20
; They should be commented out, and trunk settings removed from the control pages, if using Asterisk to register to the far end.
max_retries = 9999
fromuser=voiceless-in ; Their user for authenticating with us.
auth_rejection_permanent = no
secret=incomingpass ; Their password for authenticating with us
contact_user = maininbound
context=voiceless-in
expiration = 120
insecure=invite
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]
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
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:<br />
[[File:Asterisk pjsip noregistration.png|border]]

==PJSIP: Keep-Alive / Anti-Idle==
If you are using a firewall or NAT router with short timeouts on UDP sessions you can force packets to be sent over the connection to keep it alive.

Set qualify_frequency in the aor section; This triggers an OPTIONS message every X (as set) seconds.
An example of the aor section follows:
[aaisptrunk]
type = aor
contact = sip:+442082881111@voiceless.aa.net.uk
qualify_frequency=20

==PJSIP: IPv6==
By default PJSIP does not listen on IPv6.<br />
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:
<syntaxhighlight lang="ini">
[aaisp-incoming-username]
type=user
context=aaisp-incoming-context
secret=aaisp-incoming-password
transport=udp
transport=udp
disallow=all
disallow=all
allow=alaw
allow=alaw
trustrpid=yes
directmedia=no
</syntaxhighlight>
*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 ===
; IPv4 hostnames
*Voiceless must authenticate so that calls are recognised as the above peer section.
[voiceless-1](voiceless-common)
*You need to use the '''match_auth_username=yes''' setting otherwise Asterisk will not recognise Voiceless' initial requests.
host=a4.voiceless.aa.net.uk
[voiceless-2](voiceless-common)
host=b4.voiceless.aa.net.uk
[voiceless-3](voiceless-common)
host=c4.voiceless.aa.net.uk
[voiceless-4](voiceless-common)
host=d4.voiceless.aa.net.uk
[voiceless-5](voiceless-common)
host=e4.voiceless.aa.net.uk
[voiceless-6](voiceless-common)
host=f4.voiceless.aa.net.uk
[voiceless-7](voiceless-common)
host=g4.voiceless.aa.net.uk
[voiceless-8](voiceless-common)
host=h4.voiceless.aa.net.uk
[voiceless-9](voiceless-common)
host=i4.voiceless.aa.net.uk
[voiceless-10](voiceless-common)
host=j4.voiceless.aa.net.uk


sip.conf:
; IPv6 hostnames
<syntaxhighlight lang="ini">
[voiceless-11](voiceless-common)
[general]
host=a6.voiceless.aa.net.uk
match_auth_username=yes
[voiceless-12](voiceless-common)
host=b6.voiceless.aa.net.uk
[voiceless-13](voiceless-common)
host=c6.voiceless.aa.net.uk
[voiceless-14](voiceless-common)
host=d6.voiceless.aa.net.uk
[voiceless-15](voiceless-common)
host=e6.voiceless.aa.net.uk
[voiceless-16](voiceless-common)
host=f6.voiceless.aa.net.uk
[voiceless-17](voiceless-common)
host=g6.voiceless.aa.net.uk
[voiceless-18](voiceless-common)
host=h6.voiceless.aa.net.uk
[voiceless-19](voiceless-common)
host=i6.voiceless.aa.net.uk
[voiceless-20](voiceless-common)
host=j6.voiceless.aa.net.uk
</syntaxhighlight>
</syntaxhighlight>
*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 ==
==Define a proxy for outbound calls==
*Either use a separate '''type=peer''' section or combine incoming and outgoing in one '''type=friend''' section
Defining us as a SIP proxy for outbound calls:

<syntaxhighlight>
=== Separate Section ===
; Config for outbound calls.
sip.conf:
[voiceless-out]
<syntaxhighlight lang="ini">
[aaisp-outgoing-account]
type=peer
type=peer
remotesecret=outgoingpass ; Our password to their service
defaultuser=+441234567890 ; Authentication user for outbound
host=voiceless.aa.net.uk
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
</syntaxhighlight>
</syntaxhighlight>

=== Combined Section ===
sip.conf:
<syntaxhighlight lang="ini">
[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
</syntaxhighlight>


==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.




Line 93: Line 196:
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.
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:
You can register (and tell Asterisk that it's behind NAT) with these settings under the [general] section:
<syntaxhighlight>
<syntaxhighlight lang="ini">
localnet=10.0.0.0/8
localnet=10.0.0.0/8
register => +441234567980:outgoingpass@voiceless.aa.net.uk/extn
register => +441234567980:outgoingpass@voiceless.aa.net.uk/extn
</syntaxhighlight>
</syntaxhighlight>
In this example, extn is the extension that Asterisk will pass the call to. Asterisk matches the hostname against the peers later on in the config and so the only change you have to make is to remove the fromuser and secret from the [common] template in the inbound proxy example above.
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.
Localnet should of course be set to whatever RFC1918 range you are using on your LAN.



==Dialplan==
==Dialplan==
Line 105: Line 207:
See Asterisk's included example sip.conf for examples of how to send the call to different contexts etc.
See Asterisk's included example sip.conf for examples of how to send the call to different contexts etc.
For outbound calls:
For outbound calls:
<syntaxhighlight>
<syntaxhighlight lang="ini">
exten => _[+X].,1,Dial(SIP/voiceless-out/${EXTEN})
exten => _X.,1,Dial(SIP/voiceless-out/${EXTEN})
</syntaxhighlight>
</syntaxhighlight>
For inbound calls (assuming you're routing call to a registered Snom):
For inbound calls (assuming you're routing call to a registered Snom):
<syntaxhighlight>
<syntaxhighlight lang="ini">
[voiceless-in]
[voiceless-in]
exten => _[+X].,1,Dial(SIP/snom)
exten => _X.,1,Dial(SIP/snom)
</syntaxhighlight>


==Test server==
We have a test server for debugging problems and testing new features.
If you wish to allow our test server to make calls in to you as well, you can include its IPs by defining these peers too:
<syntaxhighlight>
; Test server IPv4 hostname
[voiceless-test4](voiceless-common)
host=z4.voiceless.aa.net.uk

; Test server IPv6 hostname
[voiceless-test6](voiceless-common)
host=z6.voiceless.aa.net.uk
</syntaxhighlight>
</syntaxhighlight>


=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.


=Further Help=
Customers using Asterisk and AAISP have created a website and IRC channel especially for this!
*http://www.aa-asterisk.org.uk/
*irc://z.je/a&a-asterisk


[[Category:VoIP]]
[[Category:VoIP Phones|Asterisk]]
[[Category:VoIP Phones]]
[[Category:VoIP IPv6]]

Latest revision as of 16:02, 10 December 2023

Asterisk logo.png

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.

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]
   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
   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:
Asterisk pjsip noregistration.png

PJSIP: Keep-Alive / Anti-Idle

If you are using a firewall or NAT router with short timeouts on UDP sessions you can force packets to be sent over the connection to keep it alive.

Set qualify_frequency in the aor section; This triggers an OPTIONS message every X (as set) seconds. An example of the aor section follows:

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

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.