amiws - AMI (Asterisk Manager Interface) to web-socket proxy

This article is about simple networking utility that allows to connect multiple Asterisk PBX servers via AMI (Asterisk Management Interface), listen to Asterisk events and other message and convert them to JSON. Users can connect to the utility with HTTP protocol and get JSON messages via WebSocket.


The utility's name is "amiws" and it can be found on github:
https://github.com/staskobzar/amiws

"amiws" works as a proxy between Asterisk and Web client:

Proxy get events from Asterisks and sends them users via WebSocket. Also "amiws" accepts JSON messages, converts them to AMI Actions and sends them back to Asterisk PBXs.

The github repository has fully functional example of the dashboard that looks like this:

The repo has enough basic documentation and configuration file example with even more information.

Here I will describe how to configure SSL/TLS connections.

HTTP and WebSocket over SSL/TLS

Note, that amiws should be configured with SSL support (see github repo). When it is done, it is simple to configure amiws to use SSL/TLS for HTTP/WebSocket connection.

It should be enabled in configuration file:

 Certificate and key files can be generated with "openssl" utility. There are tones of articles on how to generate self-signed certificates for HTTPs.

Probably the simplest way would be this:

$ openssl req -nodes -x509 -newkey rsa:4096 -keyout /tmp/server.key -out /tmp/server.pem

This will generate both certificate and key. Note parameter "-nodes", which will skip using passphrase for the certificate. If you want to protect you certificate with passphrase, do not use this parameter. But "amiws" will prompt for the passphrase when starting.

AMI over TLS/SSL

Asterisk support TLS transport for AMI connection. To configure AMI over TLS the following parameters should be set in "manager.conf" file of Asterisk configuration:

tlsenable=yes
tlsbindaddr=0.0.0.0:5039
tlscertfile=/etc/asterisk/keys/asterisk.pem
tlsprivatekey=/etc/asterisk/keys/asterisk.key

Fortunately, Asterisk provides script to generate self-signed certificates. Asterisk wiki has tutorial that explains it very well. Actually, it is for SIP/RTP encryption but it works well for AMI as well.

First thing is to create directory on Asterisk server to store certificates:

$ mkdir /etc/asterisk/keys

Asterisk utility for certificates generation can be found in Asterisk source directory "contrib/scripts/".
Following command will generate CA (certificate authority)


the necessary certificates and keys:

$ ./ast_tls_cert -C pbx.example.com -O "The Company" -d /etc/asterisk/keys

"pbx.example.com" is the DNS hostname of the Asterisk machine. Also, IP address can be used instead.
Next command will generate certificates for client:

$ ./ast_tls_cert -m client -c /etc/asterisk/keys/ca.crt -k /etc/asterisk/keys/ca.key \
  -C 192.168.1.122 -O "The Company" -d /etc/asterisk/keys -o amiws

"192.168.1.122" is the IP of the machine with "amiws".
If you run Asterisk with different user then you shell, do not forget to change owner of /etc/asterisk/keys.

Files "amiws.pem" and "amiws.key" should be copied to the machine with amiws proxy.

Last step is to configure connection with following parameters:

port: 5039
ssl_cert: /etc/amiws/ssl/amiws.pem
ssl_key: /etc/amiws/ssl/amiws.key


The AMI connection is now secure.