Matt G. Watson

HowTo: Install and Configure AstManProxy

Synopsis

This HowTo will guide you through the process of installing and configuring AstManProxy.  AstManProxy is a proxy server for Asterisk’s Asterisk Manager Interface (AMI).  The reason we want to use a proxy server infront of AMI is that AMI was not really designed to handle alot of simultanous connections and can cause extreme performance problems on the PBX.  A proxy server like AstManProxy can help this problem by acting as a hub for all of those connections and aggregating them into a single connection to AMI.  Using a proxy server also allows us to have a little more control over the input and output formats.  Asterisk uses a rather unique protocol for AMI, one which some developers find rather difficult to interface with.  AstManProxy can help by allowing you to interface using a REST/XML-RPC like interface, as well as getting plain text or XML responses.  Something that developers would much rather deal with. AstManProxy also has an ‘autofilter’ function which also helps developers interface by automatically filtering out un-wanted messages from Asterisk.

Requirements

There are not too many requirements for AstManProxy:

1. OpenSSL (including development files), in debian-based distros these packages will be “openssl” and “openssl-devel”
2. Asterisk server

Installing AstManProxy

First we need to download and extract the AstManProxy source code:

iridium src # wget http://www.popvox.com/astmanproxy-latest.tgz
iridium src # tar -zxvf astmanproxy-latest.tgz
iridium src # cd astmanproxy-1.21/

Then we compile AstManProxy

iridium astmanproxy-1.21 # make

Last but not least, install the software

iridium astmanproxy-1.21 # make install

This will install AstManProxy into a basedir of /usr/local.  You can install this to another location by editing the PREFIX= line in the Makefile file.

Configuring Asterisk Manager Interface (AMI)

The first thing we need to do is edit /etc/asterisk/manager.conf and create a user account that AstManProxy will use to connect to Asterisk.

[astmanproxy]
secret = mysupersecretpassword
permit=127.0.0.1/255.255.255.255
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

If you will be running AstManProxy on a different machine than Asterisk, make sure you set the permit= line accordingly.  My setup only permits this account to be logged into from localhost.

Configuring AstManProxy

the ‘make install’ step also created two new files for us in /etc/asterisk.  They are astmanproxy.conf and astmanproxy.users.

We first need to configure astmanproxy.conf so AstManProxy knows what Asterisk machine to connect to, open up astmanproxy.conf in your favorite text editor and edit the host = line to use the same values you put into manager.conf earlier:

host = localhost, 5038, astmanproxy, mysupersecretpassword, on, off

You will probably also want to turn authentication on, otherwise anybody with access to your AstManProxy in theory could have total control over your PBX!

authrequired = yes

However for the time being I’m going to keep my authrequired= line to “no” because I’ve been having trouble getting it to work with “inputformat=http”.

I also opted to have AstManProxy run under the same UNIX user account as my Asterisk server:

proc_user = asterisk
proc_group = asterisk

For the purpose of this How-To I’m also going to set my input and output formats as follows:

inputformat = http
outputformat = xml

This will allow me to use HTTP GET or POST actions to communicate with AstManProxy and get text/xml responses back.

Creating AstManProxy users

The last thing we need to do is create user accounts in AstManProxy, this is done by editing /etc/asterisk/astmanproxy.users

The format for this file is pretty simple and its syntax is commented near the top of the default file:

matt=password,SIP/mattgw,local,

Testing AstManProxy

Startup AstManProxy by typing:

iridium ~ # astmanproxy -d

This will startup AstManProxy with minimal debugging and keep it running in the foreground for our testing purposes.

Last but not least, lets send a HTTP GET request to our new AstManProxy server to make sure its working.  I’ve chosen to do this using curl from another machine:

zirconium # curl http://10.1.0.20:1234/?Action=ListCommands\&ActionID=123456

Where 10.1.0.20 is the IP of the machine running AstManProxy.  You could also opt for typing the address “http://10.1.0.20:1234/?Action=ListCommands&ActionID=123456″ into your favorite browser, but remember, the output is XML and your browser may try and interpret it as HTML instead of displaying the XML to you.
If all goes to plan, you should see output as follows:

<AsteriskManagerOutput>
<Response Value=”Success”/>
<ActionID Value=”123456″/>
<UnparsedText Value=”ZapTransfer: Transfer Zap Channel (Priv: <none>)”/>
<UnparsedText Value=”SIPshowregistry: Show SIP registrations (text format) (Priv: system,reporting,all)”/>
<snip> …. </snip>
<Server Value=”localhost”/>
</AsteriskManagerOutput>

Congratulations, you now have AstManProxy up and running!  Make sure you see the README file for AstManProxy for a list of all the special AstManProxy commands, and the output of the ‘ListCommands’ Action that we tested with above should give you a list of all the Asterisk commands available.