FOREWORD & QUICK START
The need for a proxy to Asterisk's manager interface has been clear; almost all GUIs and other interfaces to asterisk implement a proxy of some kind. Why? A proxy offers:
It can serve as the basis for an extensible application framework for communication with multiple Asterisk servers.
Features include:
You can use Astmanproxy as the basis for a web-based application: send it data using HTTP POST or HTTP GET, and receive XML output. Or use HTTP POST and get Standard (text/plain) output back! Astmanproxy speaks HTTP internally, so no web server is required!
You can use Astmanproxy as an XML feed for a .NET program that keeps track of Asterisk's state. Or as an interface for injecting quick commands into multiple Asterisk boxes from your Python scripts. The possibilities are limited only by your imagination.
To get started quickly, simply: make make install
Edit the configuration file: vi /etc/asterisk/astmanproxy.conf
Optionally edit the other config files: vi /etc/asterisk/astmanproxy.users vi /etc/asterisk/ssl.conf
Start the program: astmanproxy
To view debug output, start astmanproxy in debug mode: astmanproxy -d
For more debug output, add more -d's: astmanproxy -ddddddd
You may want to start astmanproxy at boot. In that case, you might place it in /etc/rc.d/rc.local: /usr/local/sbin/astmanproxy
Please send your feedback! We are looking for contributors to add support for new I/O formats and add new features!
Contributions: Paypal via dave@popvox.com; beer accepted at Astricon events
=================================================================== Additional Proxy Features
In addition to exposing the entire Asterisk Manager API as a pass-through, non-interpreting proxy, 'astmanproxy' can parse client input where desired; this could be used in the future to add new features that should exist in a proxy but that don't necessarily need to be in Asterisk proper.
There are some proxy-specific headers that you can specify in your applications now:
Server: (x.x.x.x|hostname) Specify a server to which to send your commands. This should match the server name specified in your config file's "host" entry. If you do not specify a server, the proxy will pick the first one it finds -- fine in single-server configurations.
Some "ProxyActions" have been implemented which the Proxy responds to but does not pass on to Asterisk itself:
ProxyAction: ListSessions Outputs a list of all active client and server sessions
ProxyAction: SetOutputFormat OutputFormat: (standard|xml) Sets the output format on a per-client basis
ProxyAction: SetAutoFilter AutoFilter: (on|off|unique) Sets the AutoFilter property on a per-client basis (See autofiltering section below)
ProxyAction: Logoff Logs client out of Proxy and leaves Asterisk alone.
ProxyAction: ListIOHandlers Lists all available Input/Output Handlers Examples include Standard, XML, and CSV; more I/O formats may be added by creating new handler modules.
ProxyAction: AddServer Server: (x.x.x.x|hostname) Port: (5038|other) Username: (username) Secret: (secret) Events: (on|off) Initiates a proxy connection to a new Asterisk Server; this has the same effect of including a host entry in your host= section of the configuration file.
ProxyAction: DropServer Server: (x.x.x.x|hostname) Disconnects a proxy<->server session. Hostname specified should exactly match the entry in your config host= section, or whatever name you used with ProxyAction: AddServer.
ProxyKey: secret Action: Originate ... ActionID: ... You can use this as a simple authentication mechanism. Rather than have to login with a username & password, you can specify a ProxyKey that must be passed from a client before requests are processed. This is helpful in situations where you would like to authenticate and execute an action in a single step. See the sample config file for more information.
The proxy also intercepts the following Actions:
Action: Login You can login to astmanproxy just as you would the Asterisk Manager Interface. The user credentials are stored in astmanproxy.users.
Action: Challenge Astmanproxy now supports the MD5 challenge authentication mechanism. See section below for more information on this authentication mechanism and how you can use it in your applications to avoid having to send a password over the internet, and instead use a MD5 challenge to hash your password before sending. Note that this is somewhat less of an issue with SSL support now enabled, however, some apps require this mechanism, and we support it.
Action: Logoff You don't want your applications logging the proxy off of Asterisk. The proxy intercepts "Action: Logoff" and interprets it as "ProxyAction: Logoff". This keeps the proxy from disconnecting from Asterisk.
Blank Commands The proxy does not send commands to Asterisk until you have a fully formed Action block. This keeps unnecessary traffic and load off of Asterisk. The proxy intercepts and ignores blank command blocks.
=================================================================== AstManProxy Autofiltering Functionality
One of the most powerful features of AstManProxy is its ability to automatically filter output on a per-client basis. It can do this with its Autofilter capability, which can be set 'on'/'unique' in the config file or enabled via the ProxyAction: SetAutoFilter function.
With autofiltering 'on', each client only receives output containing the "ActionID" parameter it has set most recently. This is useful for single atomic requests into asterisk from a client, such as when creating a simple UI to inject a command.
For example, if a client sends this packet while autofiltering is enabled:
Action: Ping ActionID: foo
Then the autofilter ActionID for that client is set to foo, and no output besides for responses containing "foo" will be returned to that client, such as:
Response: Pong ActionID: foo
Replace Ping with Originate and Pong with Success and you can see how this same mechanism can be used to quickly query asterisk box(es), initiate calls, etc, without your client having to worry with filtering a lot of unrelated output.
A more advanced verion of this facility is to set autofiltering to 'unique'. This causes astmanproxy to alter the ActionID on the way to Asterisk, and undo that change on the way back.
For example the exchange:
Action: Ping ActionID: foo
< Response: Pong < ActionID: foo <
Might be seen by Asterisk as:
Action: Ping ActionID: amp7-foo
< Response: Pong < ActionID: amp7-foo <
and the "amp7-" prefix is created uniquely for each client connection.
=================================================================== On the astmanproxy.users output filtering functionality
Users may now be defined in your astmanproxy.users configuration file. This enables a traditional user/password based login mechanism for Astmanproxy similar to what is found in Asterisk. Output may be filtered on a per-user basis.
"user" is the username, secret is the password, and the (optional) channel setting causes filtering of events only for the specified channel to be sent to this user.
Following this, an outbound context and an inbound context may be (optionally) specified. This will cause messages to and from Asterisk respectively to be blocked if they contain a Context: header which does not match the specified value. This might be used to prevent a client making calls except in a predefined context.
An account code may be (optionally) specified. This will force the Account: header to be overwritten for all commands to/from this client. If the Action is "Originate", then a missing Account: header will be added.
A "server" option will cause the proxy to behave as if the client has included a "Server:" header in each request packet.
Any non-empty string provided in "more_events" will allow the passing of non-filterable events to all clients. The default behaviour is to block these packets if any form of filtering is requested.
user=secret,channel,out_context (to Asterisk),in_context (From Asterisk),accountcode,server,more_events
e.g.: steve=steve,SIP/snom190,local, dave=securepass,SIP/1002,,,davesaccount,daveserver bill=pass
=================================================================== On the 'Action: Challenge' Authentication Mechanism
John Todd wrote this excellent summary of the Action: Challenge Authentication Mechanism, and it accurately describes the implementation included in astmanproxy:
While the SSL encryption of the AMI is great, it's always a good policy to never send passwords at all if you have an alternative.
After connecting to the AMI port, send this message:
Action: Challenge AuthType: MD5
You should receive a challenge string:
Response: Success Challenge: 125065091
Then, assuming that the manager username is "joebob" and the password is "yoyodyne11", perform this on a shell line of a handy UNIX system (you programmers will figure out how to do this with a library call, I'm sure):
bash-3.00# md5 -s 125065091yoyodyne11 MD5 ("125065091yoyodyne11") = e83a9e59e7c8d1bb6554982275d05016 bash-3.00#
Now use this key to log in, so type this to the AMI:
Action: Login
AuthType: MD5
Username: joebob
Key: e83a9e59e7c8d1bb6554982275d05016...and you'll get:
Response: Success Message: Authentication accepted
=================================================================== On Astmanproxy's SSL Support
Support for SSL on the Asterisk Manager Interface has recently been contributed to the Asterisk project (see Digium #6812).
This SSL implementation has been tested by several people and seems to work fine. While it is not in a mainline Asterisk distribution yet (in SVN Trunk only right now), it is likely that AMI will soon support SSL natively.
I felt that it was important that Astmanproxy support the same SSL mechanism as Asterisk; we have been talking about adding SSL/TLS for some time. So, now it's been incorporated.
This means you can implement scenarios like: client <-> proxy <-> n*asterisk with end-to-end SSL security.
To make Astmanproxy talk to asterisk, turn on the 'usessl' option in the server host specification (see astmanproxy.conf).
To have Astmanproxy talk to clients via SSL, be sure to enable 'allowencryptedconnections' in the astmanproxy.conf file.
To have Astmanproxy accept ONLY SSL connections, you should enable 'allowencryptedconnections' and disable 'allowunencryptedconnections'. We've endeavored to use the same configuration setting names as in manager.conf with the SSL implementation in #6812.
=================================================================== Now Supports HTTPS Natively!
One really interesting side effect of having both SSL and HTTP support natively is that we in fact now support HTTPS!
With the proxy configured on localhost:1234, you can do things along these lines:
https://localhost:1234/?Action=ShowChannels&ActionID=Foo
This has been tested fairly extensively with good results. The HTTP handler supports both GET and POST and can properly deal with XML or Standard output formats. With Autofilter=on, this paradigm is ideal for creating a simple REST-like interface into Asterisk (even multiple boxes!) with no web servers needed.
=================================================================== Software Updates, Author Info, and How to Contribute
Current development on AstManProxy is happening here: http://github.com/davetroy/astmanproxy/tree/master
Please feel free to fork and contribute!
Also, there is a new mailing list / group available here: http://groups.google.com/group/astmanproxy?hl=en
Developing web-based realtime applications for the asterisk open-source PBX often requires interacting with asterisk's Manager interface. The Asterisk Manager runs on port 5038 by default and provides a simple TCP interface into several common asterisk functions, including call origination, redirection, hangup, and many other functions.
Each interaction from a web-based application requires a separate connection to the manager interface. Asterisk, being a real time application, shouldn't have to deal with the load of constant connections, disconnections, and authentications from a single trusted client, namely your web app.
In the same way that web developers have solved this problem for other similar services (imapproxy for IMAP web mail clients, database connection caches, etc), 'astmanproxy' sets out to solve this problem for asterisk.
This project started out as a simple proof-of-concept script called "simpleproxy.pl" which was made available in September 2004, following a discussion at the Astricon conference regarding the need for such a proxy. That code was based on Nicolas Gudino's manager proxy for his excellent Flash Operator Panel. Written in perl and as a single-threaded select-based "dumb" proxy, simpleproxy.pl has been widely used as a basis for experimentation, but I wanted something more robust and that could act as a basis for additional features.
Asterisk Manager Proxy is a multithreaded proxy server for Asterisk Manager written in c, and based on several of the same data structures and routines found in the asterisk manager itself. This insures a very high degree of compatibility with Asterisk; it should also be very robust and scalable.
Asterisk Manager Proxy gives the ability to support multiple input and output format -- implemented as abstracted I/O handlers -- and these are configurable on a per-client basis.
=================================================================== (C) 2005-2008 David C. Troy, dave@popvox.com