|author||David Troy <firstname.lastname@example.org>||2006-04-08 02:40:15 +0000|
|committer||David Troy <email@example.com>||2006-04-08 02:40:15 +0000|
git-svn-id: http://svncommunity.digium.com/svn/astmanproxy/branches/1.20pre@96 f02b47b9-160a-0410-81a6-dc3441afb0ec
1 files changed, 76 insertions, 29 deletions
@@ -1,10 +1,10 @@
-(c) 2005-2006 David C. Troy
+(c) 2005-2006 David C. Troy, firstname.lastname@example.org
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:
+Optionally edit the other config files:
+ vi /etc/asterisk/astmanproxy.users
+ vi /etc/asterisk/ssl.conf
Start the program:
To view debug output, start astmanproxy in debug mode:
+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:
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!
Paypal via email@example.com; beer accepted at Astricon events
- 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.
-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
@@ -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.
+ 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:
@@ -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:
+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