Tutorial Overview

This tutorial demonstrates basic WebRTC support and functionality within Asterisk.  Asterisk will be configured to support a remote WebRTC client, the sipml5 client, for the purposes of making calls to/from Asterisk within the Firefox web browser.

For this tutorial, it is assumed that you are logged in as the root user.  It is also assumed that you are running a version of Asterisk that is at least 13.15.0 or 14.4.0 and have a recent version of Firefox, e.g. 54.0.

Check Asterisk Dependencies

To connect the sipml5 client to Asterisk, Asterisk must have been built with support for the res_crypto, res_http_websocket, and res_pjsip_transport_websocket resource modules.  To optionally enable high-quality calls between Asterisk and the sipml5 client, Asterisk's Opus codec module is required.  If Opus is not installed into Asterisk, lower-quality calls will still be possible.  To check for the presence of these modules you can perform:

# ls -w 1 /usr/lib/asterisk/modules/{*crypto*,*websocket*,*opus*}

And you should see something similar to:

/usr/lib/asterisk/modules/codec_opus.so
/usr/lib/asterisk/modules/res_crypto.so
/usr/lib/asterisk/modules/res_format_attr_opus.so
/usr/lib/asterisk/modules/res_http_websocket.so
/usr/lib/asterisk/modules/res_pjsip_transport_websocket.so

If these modules are not found, please return to your menuselect configuration of Asterisk.

Next, to ensure these modules are loaded by Asterisk, you can perform:

# asterisk -rx "module show like crypto"
# asterisk -rx "module show like websocket"
# asterisk -rx "module show like opus"

You should see something similar to:

# asterisk -rx "module show like crypto"
Module                         Description                              Use Count  Status      Support Level
res_crypto.so                  Cryptographic Digital Signatures         1          Running              core
1 modules loaded

# asterisk -rx "module show like websocket"
Module                         Description                              Use Count  Status      Support Level
res_http_websocket.so          HTTP WebSocket Support                   3          Running          extended
res_pjsip_transport_websocket.so PJSIP WebSocket Transport Support        0          Running              core
2 modules loaded
 
# asterisk -rx "module show like opus"
Module                         Description                              Use Count  Status      Support Level
codec_opus.so                  OPUS Coder/Decoder                       0          Running          extended
res_format_attr_opus.so        Opus Format Attribute Module             1          Running              core
3 modules loaded

If the modules are not loaded, check your /etc/asterisk/modules.conf configuration file to make sure they are not explicitly disabled.

Create Certificates

Modern browsers require use of TLS and DTLS-SRTP for WebRTC signaling and media encryption.  For Asterisk to use TLS and DTLS-SRTP, it is necessary to load certificates.  Within this tutorial, we will create a self-signed certificate authority and server certificate.  Some browsers require the use of publicly-signed certificates.  The acquisition of publicly-signed certificates is outside the scope of this tutorial.

Asterisk provides a utility script, ast_tls_cert in its contrib/scripts source directory.  We will use it to make a self-signed certificate authority and a server certificate for Asterisk, signed by our new authority.

First, let's make a place for our certificates:

# mkdir /etc/asterisk/keys

Next, call the script as such:

# ./ast_tls_cert -C pbx.example.com -O "My Super Company" -d /etc/asterisk/keys

• The "-C" option is used to define our host - DNS name or our IP address.
• The "-O" option defines our organizational name.
• The "-d" option is the output directory of the keys.

1. You'll be asked to enter a pass phrase for /etc/asterisk/keys/ca.key, put in something that you'll remember for later.
2. This will create the /etc/asterisk/keys/ca.crt file.
3. You'll be asked to enter the pass phrase again, and then the /etc/asterisk/keys/asterisk.key file will be created.
4. The /etc/asterisk/keys/asterisk.crt file will be automatically generated.
5. You'll be asked to enter the pass phrase a third time, and the /etc/asterisk/keys/asterisk.pem, a combination of the asterisk.key and asterisk.crt files, will be created.

You can then check your /etc/asterisk/keys directory to verify the new files were created, as such:

# ls -w 1 /etc/asterisk/keys
 

And you should see:

asterisk.crt
asterisk.csr
asterisk.key
asterisk.pem
ca.cfg
ca.crt
ca.key
tmp.cfg

Configure Asterisk's built-in HTTP daemon

The sipml5 client uses Websocket as its transport method.  To communicate with Websocket clients, Asterisk uses its built-in HTTP daemon.  Configure /etc/asterisk/http.conf like:

[general]
enabled=yes
bindaddr=0.0.0.0
bindport=8088
tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/asterisk/keys/asterisk.pem
 

Here, we've enabled the HTTP daemon and set its binding address and port - required for basic operation of the HTTP daemon.  We have also enabled the TLS support, and have set the TLS binding address and port as well as the server key - the one we made in the previous step - to use.

To verify the web server is running, perform:

# netstat -an | grep 8089

And you should see:

tcp        0      0 0.0.0.0:8089            0.0.0.0:*               LISTEN  

Configure PJSIP

Next, we need to configure PJSIP.  The sipml5 client uses Websocket as a transport, and connects to Asterisk's HTTP daemon, but it uses the SIP protocol.  Asterisk's default channel driver for SIP communications is PJSIP.  For more about PJSIP in Asterisk, you can refer to the Configuring res_pjsip pages.  

PJSIP WSS Transport

Like Asterisk's HTTP daemon, which needs to be configured to listen for Websocket transports, PJSIP needs to be configured with Websocket transports.  In this case, we will configure a PJSIP transport for Websocket using the "Secure Websocket" transport identifier wss.  To your /etc/asterisk/pjsip.conf, you should add:

[transport-wss]
type=transport
protocol=wss
bind=0.0.0.0

PJSIP AoR and Auth

Next, we need to configure an entity within PJSIP to accept registration from our browser-based sipml5 client.  To do this, we will create three PJSIP objects in our /etc/asterisk/pjsip.conf configuration file: an aor, an auth, and an endpoint.

Your aor and your auth should look something like:

[199]
type=aor
max_contacts=1
remove_existing=yes
 
[199]
type=auth
auth_type=userpass
username=199
password=199 ; This is a completely insecure password.  Do NOT expose this 
;               system to the Internet without utilizing a better password.

Here, we establish that the thing registering with us will be known internally as "199" and that it will use 199 and 199 as its username and password registration credentials.  Note that this is NOT SECURE and you should choose a MUCH better password if you're following any of these instructions.

PJSIP Endpoint

Next, we need to create an endpoint object that will reference this aor and auth as well as be provided with configuration parameters that are specific to WebRTC clients.  Your endpoint in /etc/asterisk/pjsip.confs should look something like:

[199]
type=endpoint
aors=199
auth=199
use_avpf=yes
media_encryption=dtls
dtls_ca_file=/etc/asterisk/keys/ca.crt
dtls_cert_file=/etc/asterisk/keys/asterisk.pem
dtls_verify=fingerprint
dtls_setup=actpass
ice_support=yes
media_use_received_transport=yes
rtcp_mux=yes
context=default
disallow=all
allow=opus
allow=ulaw

An explanation of each of these settings parameters can be found on the Asterisk 13 Configuration_res_pjsip page.  Briefly:

• Declare an endpoint that references our previously-made aor and auth.  
• Notify Asterisk to expect the AVPF profile (secure RTP)
• Setup the DTLS method of media encryption.
• Specify which certificate files to use for TLS negotiations with this endpoint and our verification and setup methods.
• Enable ICE support
• Tell Asterisk to send media across the same transport that we receive it from.
• Enable mux-ing of RTP and RTCP events onto the same socket.
• Place received calls from this endpoint into an Asterisk Dialplan context called "default"
• And setup codecs by first disabling all and then selectively enabling Opus (presuming that you installed the Opus codec for Asterisk as mentioned at the beginning of this tutorial), then G.711 u-law.

Configure chan_sip

In the event that you still utilize Asterisk's older SIP channel driver, chan_sip, in lieu of the modern PJSIP channel driver, you may use the following as a guide for configuring sip.conf:

[general]
udpbindaddr=0.0.0.0:5060
realm=123.123.123.123 ;replace with your Asterisk server public IP address or host
transport=udp,ws,wss

[199]
host=dynamic
secret=199 ; This is a completely insecure password.  Do NOT expose this 
;             system to the Internet without utilizing a better password.
context=default
type=friend
encryption=yes
avpf=yes
force_avp=yes
icesupport=yes
directmedia=no
disallow=all
allow=opus
allow=ulaw
dtlsenable=yes
dtlsverify=fingerprint
dtlscertfile=/etc/asterisk/keys/asterisk.pem
dtlscafile=/etc/asterisk/keys/ca.crt
dtlssetup=actpass
rtcp_mux=yes

Configure Asterisk Dialplan

We'll make a simple dialplan for receiving a test call from the sipml5 client.

[default]
exten => 200,1,Answer()
same => n,Playback(demo-congrats)
same => n,Hangup()

This instructs Asterisk to Answer a call to "200," to play a file named "demo-contracts" (included in Asterisk's core sound file packages), and to hang up.

Firewall Configuration

Firewall configuration is outside the scope of the tutorial, however here is the output from my Uncomplicated FireWall service to show you what you may need to open:

To                         Action      From
--                         ------      ----
5060                       ALLOW IN    Anywhere
8089/tcp                   ALLOW IN    Anywhere
10000:20000/udp            ALLOW IN    Anywhere

You may wish to reconfigure your services to non-standard ports, or narrow the possible source addresses for additional security.

5060: This is the standard port for SIP communications
8089: This is the standard port for Secure Websockets when used with Asterisk's built-in HTTP sever
10000:20000: This is the port range configured in rtp.conf for audio to flow.

Restart Asterisk

Next, we'll perform a graceful restart of Asterisk, where in-progress calls are allowed to complete before Asterisk is stopped, so that it can pick up the changes that we've made to its configuration.  From the Linux console execute:

# asterisk -rx "core restart when convenient"

And you'll see:

# asterisk -rx "core restart when convenient"
Waiting for inactivity to perform restart
# 

Browsers and WSS

When using WSS as a transport, Chrome and Firefox will not allow you, by default, to connect using WSS to a server with a self-signed certificate.  Rather, you'll have to install a publicly-signed certificate into Asterisk.  Or, you'll have to import the the self-signed certificate we made earlier into your browser's keychain, which is outside the scope of this Wiki.  

Or, for Firefox and Chrome, you can open a separate browser tab and point it to Asterisk's HTTP server's TLS port and WS path, e.g. http://[ ip of asterisk server ]:8089/ws, and you can manually confirm the security exception.

Configure SIPML5

First, go back and read the previous section and make sure that you've opened a new tab in Firefox and visited http://[ ip of asterisk server]:8089/ws and that you've confirmed the security exception.  We're doing testing and development here, not deployment to real production, so this is "okay."

Next, using Firefox, visit https://sipml5.org - you'll be redirected to https://www.doubango.org/sipml5/

Once there, click the "Enjoy our live demo" link to be directed to the sipml5 client.

In the Registration box, use configuration similar to the following:

Here, we have input the following:

• Display Name is a free-form string
• Private Identity is our username from our PJSIP auth object
• Public Identity is in the format: 
  • sip : (name of our PJSIP aor object) @ (IP Address of the Asterisk system)
• Password is our password from our PJSIP auth object
• Realm is "asterisk.org"

Next, click the "Expert mode?" form button.  It will open a new browser tab.  In the Expert settings box, use a configuration similar to the following:

Here, we have made the following changes:

• Checked the "Disable Video" box
• Filled in the WebSocket Server URL using the format:
  
  • wss : // (ip address of asterisk) : 8089 / ws
• Checked the "Disable 3GPP Early IMS" box

Click "Save" and return to the other demo tab with the Registration box.

Next, click "Login" and you should see Connected as such:

You should see a corresponding connection happen on the Asterisk CLI.  You can log into the Asterisk CLI by performing:

# asterisk -vvvr

Then, you can LogOut and Login and see something like:

== WebSocket connection from '10.27.74.22:54984' for protocol 'sip' accepted using version '13'
  -- Added contact 'sips:199@10.27.74.22:54984;transport=ws;rtcweb-breaker=no' to AOR '199' with expiration of 200 seconds
== Contact 199/sips:199@10.27.74.22:54984;transport=ws;rtcweb-breaker=no has been created
== Endpoint 199 is now Reachable

Make a test call

In the sipml5 Call control box input 200.  Then press the Call button.  You'll see a drop-down:

Select "Audio" to continue.  Once you do this, Firefox will display a popup asking permission to use your microphone:

Click "Allow."

Next, the Call control box will indicate that the call is proceeding:

Finally, when the call is connected, you will see In Call:

and you will hear "Congratulations, you have successfully installed and executed the Asterisk open source PBX..."

You've just made your first call via WebRTC using Asterisk!