It is hard to design a tutorial that applies to every environment, so remember the following:
This tutorial written using Debian Squeeze 6.0.5, Asterisk 11.8.0-rc1 and Asterisk's chan_sip channel driver.
We assume you are a little familiar with Asterisk, and have an Asterisk installation available via a public IP address, and control of the firewall in front of it. (you do have it fire-walled right?)
The SIPML5 client will be accessed via Chrome and is assumed to be behind NAT.
In newer versions of Chrome and Firefox (and others) DTLS-SRTP is mandatory. This means you must generate certificates for Asterisk to be able to use. See: Secure Calling Tutorial
Install a variety of essential dependencies to make sure we get them. Plus install the uuid-dev package that isn't included in the Asterisk 11 install_prereq script.
sudo apt-get install build-essential libncurses5-dev libxml2-dev libsqlite3-dev libssl-dev libsrtp0-dev uuid-dev
Then go to your Asterisk source /config/scripts/ directory and run the install_prereq script to get everything else that is needed.
sudo ./install_prereq install sudo ./install_prereq install-unpackaged
Build Asterisk with support for WebRTC
Using menuselect make sure Asterisk will build with res_http_websocket, res_crypto and chan_sip.
In the Asterisk source directory:
./configure && make menuselect
After verifying things are as needed in menuselect, then build and install Asterisk
make && make install && make samples
Now we need to configure the various Asterisk components necessary for WebRTC support.
I always recommend backing up your current .conf files and using clean, blank text files for trying out a tutorial like this. Especially if you are new to Asterisk.
[general] enabled=yes bindaddr=0.0.0.0 bindport=8088
You need to configure Asterisk's builtin HTTP server. You could use whatever bindport or bindaddr you want, but make sure you adjust the other configurations to match. This is the port and address that res_http_websocket and chan_sip will talk over when using a WebSocket transport.
[general] rtpstart=10000 rtpend=20000 icesupport=yes stunaddr=stun.l.google.com:19302
Configure the range of ports to use for RTP media, and we can set icesupport=yes (although the default in recent versions of 11 is now "yes") to enable support for the ICE protocol in general. We also set the address of the STUN server to use here. We use Google's STUN server which should work for just about everyone.
[general] udpbindaddr=0.0.0.0:5060 realm=220.127.116.11 ;replace with your Asterisk server public IP address or host transport=udp,ws  host=dynamic secret=DONT_USE_THIS_INSECURE_PASSWORD context=from-internal type=friend encryption=yes avpf=yes force_avp=yes icesupport=yes directmedia=no disallow=all allow=ulaw dtlsenable=yes dtlsverify=fingerprint dtlscertfile=/etc/asterisk/keys/asterisk.pem dtlscafile=/etc/asterisk/keys/ca.crt dtlssetup=actpass
There is already a lot of content on the wiki and in the sip.conf sample file that explain the options here. The key options for WebRTC support and ICE support are explained at this link for WebRTC and this one for ICE.
Though this page is written to Asterisk 11 and chan_sip, an example for setting up a PJSIP endpoint in Asterisk 12 is below.
Follow the instructions at Configuring Asterisk for WebRTC Clients before proceeding, The rest of this tutorial assumes that your PBX is reachable at
pbx.example.com and that the client is known as
Configure Asterisk Dialplan
We'll make a simple dialplan for receiving a test call from the
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-congrats"
Configure the firewall in front of Asterisk
(included in Asterisk's core sound file packages), and to hang up. To make the extension active, either restart Asterisk or issue a "dialplan reload" command from the Asterisk CLI.
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
To Action From -- ------ ---- 5060 ALLOW IN Anywhere 8088/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 port configured in sip.conf
8088: This is the port configured in http.conf
10000:20000: This is the port range configured in rtp.conf
Goto http://sipml5.org/ in your Chrome browser and use the live demo.
On the registration page use the following configuration, replacing the IP addresses with your public IP for the Asterisk server.
Open the "Expert mode" settings page and use the following details, still replacing the IP of course:
Be sure to hit save! Just leave that tab open, or close it and go back to the main tab to make a test call.
Make a test call
Restart Asterisk, or start Asterisk if you haven't already.
Click "Login" with the SIPML5 client. On the Asterisk CLI you should see:
Or, for Firefox and Chrome, you can open a separate browser tab and point it to Asterisk's HTTPs server's TLS port and WS path, e.g.
https://pbx.example.com:8089/ws, and you can manually confirm the security exception.
SIPML5 is a useful client for testing Asterisk. Many real-world users explore other options that may include rolling your own client.
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 '
49976' for protocol 'sip' accepted using version '13'
Dial extension 1000 from your SIPML5 client and you should see CLI output:
== Using SIP RTP CoS mark 5 -- Executing [1000@from-internal:1] Answer("SIP/6001-00000000", "") in new stack > 0x28057f0 -- Probation passed - setting RTP source address to X.X.X.X:9177 -- Executing [1000@from-internal:2] Playback("SIP/6001-00000000", "demo-congrats") in new stack -- <SIP/6001-00000000> Playing 'demo-congrats.gsm' (language 'en')
If you don't have VERBOSE messages going to the console, and verbosity turned up at least to 3 then you may not see these messages.
When you attempt the call, Chrome may ask you for access to your microphone or camera. Be sure to say yes!
sips:firstname.lastname@example.org:49976;transport=ws;rtcweb-breaker=no' to AOR 'webrtc_client' with expiration of 200 seconds == Endpoint webrtc_client 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:
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!
|Table of Contents|