astmanproxy README (c) 2005 David C. Troy ------------------------------------------------------------------ FOREWORD & QUICK START The need for a proxy to Asterisk's manager interface has been clear; almost all GUI's and other interfaces to asterisk implement a proxy of some kind. Why? A proxy offers: - A single persistent connection to asterisk - A more secure (non-root) TCP interface - Ability to offer filtered input/output - Less connections and networking load for asterisk This proxy began as the the perl/select based "simpleproxy.pl" and has since evolved into a full multithreaded quasi-stateful proxy based in c/pthreads. It is now capable of serving as the basis for an extensible application framework for multiple Asterisk servers. New features in version 1.1 include: - Multiple Input/Output formats: HTTP, XML, CSV, and Standard - API for addition of new, modular I/O formats - Ability to support communication with multiple Asterisk Servers - I/O Formats selectable on a per-client basis For example, you can use Astmanproxy as a single point of contact to communicate with multiple Asterisk servers. 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. No web server 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 Start the program: astmanproxy To view debug output, start astmanproxy in debug mode: astmanproxy -d 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 to help debug the more complicated HTTP and XML IO Handlers! Contributions: Paypal via dave@toad.net; beer accepted at Astricon events =================================================================== INSTALLATION: make make install The default configuration file location is /etc/asterisk/astmanproxy.conf, and that file will be automatically created upon installation if it does not already exist. TO RUN: Launch from /etc/rc.d/rc.local or startup script. /usr/local/sbin/astmanproxy (or whatever your path is) Launch with no options to run as daemon. To debug, use option "-d", and to display version information, use option "-v". =================================================================== 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 make sense to be 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) Sets the AutoFilter property on a per-client basis 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. The proxy also intercepts the following Actions: Action: Login Since the proxy logs in on behalf of your clients, and you are using key-based or network-level security to secure the proxy, logins should not be passed to asterisk. Ideally, your apps will be written not to issue Logins in the first place, but if you do, the proxy will intercept them and NOT pass them to Asterisk. Instead, it will respond with an Authentication Successful message, just as Asterisk would upon successful authentication. Note it will do this regardless of information supplied. 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. =================================================================== Author Contact Info This code is intended primarily as a foundation for others to add new features and capabilities going forward. While I will attempt to keep up with it and add to it, I make no guarantees that I'll be able to do that. My hope is that the wonderful asterisk community will start making changes, and that those changes can be managed through Digium's great CVS process. However, you can concact me at dave@popvox.com, and I will endeavor to post the latest code here: http://www.popvox.com/astmanproxy Donations are accepted via paypal to dave@toad.net. =================================================================== 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. Several other folks have experimented with adding XML output to the standard manager interface, however, Mark Spencer has made it clear that he does not want to add XML interfaces into the Asterisk core. This is an understandable design decision. 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 David C. Troy, dave@popvox.com