summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Troy <dave@popvox.com>2006-04-08 02:40:15 +0000
committerDavid Troy <dave@popvox.com>2006-04-08 02:40:15 +0000
commit23a4a54c8ffbfa1a6430d926bd88f90234a39812 (patch)
treea5d7b84a74f9d3cab720dd7c880af5061983d7e3
parent2b4352d5ebd67ece2a473e5e3b7f14d6af216dbd (diff)
downloadastmanproxy-23a4a54c8ffbfa1a6430d926bd88f90234a39812.zip
astmanproxy-23a4a54c8ffbfa1a6430d926bd88f90234a39812.tar.gz
astmanproxy-23a4a54c8ffbfa1a6430d926bd88f90234a39812.tar.xz
git-svn-id: http://svncommunity.digium.com/svn/astmanproxy/branches/1.20pre@96 f02b47b9-160a-0410-81a6-dc3441afb0ec
-rw-r--r--README105
1 files changed, 76 insertions, 29 deletions
diff --git a/README b/README
index 4a8b89d..0e8c350 100644
--- a/README
+++ b/README
@@ -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