From 17a840db2aef39bed277578ad12d941416fe3344 Mon Sep 17 00:00:00 2001 From: David Troy Date: Sat, 1 Apr 2006 16:16:58 +0000 Subject: Populating trunk git-svn-id: http://svncommunity.digium.com/svn/astmanproxy/trunk@18 f02b47b9-160a-0410-81a6-dc3441afb0ec --- README | 224 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..7369dd2 --- /dev/null +++ b/README @@ -0,0 +1,224 @@ +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 -- cgit