diff options
| -rw-r--r-- | README | 105 |
1 files changed, 76 insertions, 29 deletions
@@ -1,10 +1,10 @@ astmanproxy README -(c) 2005-2006 David C. Troy +(c) 2005-2006 David C. Troy, dave@popvox.com ------------------------------------------------------------------ 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 +clear; almost all GUIs and other interfaces to asterisk implement a proxy of some kind. Why? A proxy offers: - A single persistent connection to asterisk @@ -32,7 +32,7 @@ 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. Or use HTTP POST and get Standard (text/plain) output back! -No web server required! +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 @@ -46,50 +46,37 @@ To get started quickly, simply: 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 to help debug the more complicated -HTTP and XML IO Handlers! +support for new I/O formats and add new features! 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. +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: @@ -138,6 +125,18 @@ Server: (x.x.x.x|hostname) 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 @@ -168,7 +167,7 @@ Blank Commands blank command blocks. =================================================================== -On the Action: Challenge Authentication Mechanism +On the 'Action: Challenge' Authentication Mechanism John Todd wrote this excellent summary of the Action: Challenge Authentication Mechanism, and it accurately describes the @@ -209,6 +208,54 @@ library call, I'm sure): 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 Digium has graciously agreed to host the development of AstManProxy |