astmanproxy README
(c) 2005-2008 David C. Troy, dave@popvox.com
------------------------------------------------------------------
FOREWORD & QUICK START

The need for a proxy to Asterisk's manager interface has been 
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
 - A more secure (non-root) TCP interface
 - Ability to offer filtered input/output
 - Less connections and networking load for asterisk

It can serve as the basis for an extensible application framework
for communication with multiple Asterisk servers.

Features include:

 - Multiple Input/Output formats: HTTP, XML, CSV, and Standard
 - SSL Support for clients & servers (including HTTPS clients)
 - 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
 - Written in c/pthreads to be fast and robust

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!
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 
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

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 add new features!

Contributions:
  Paypal via dave@popvox.com; beer accepted at Astricon events

===================================================================
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 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:

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|unique)
   Sets the AutoFilter property on a per-client basis
   (See autofiltering section below)

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.

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
   You can login to astmanproxy just as you would the Asterisk
   Manager Interface.  The user credentials are stored in
   astmanproxy.users.

Action: Challenge
   Astmanproxy now supports the MD5 challenge authentication
   mechanism.  See section below for more information on
   this authentication mechanism and how you can use it
   in your applications to avoid having to send a password
   over the internet, and instead use a MD5 challenge to
   hash your password before sending.  Note that this is
   somewhat less of an issue with SSL support now enabled,
   however, some apps require this mechanism, and we support it.

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.

===================================================================
AstManProxy Autofiltering Functionality

One of the most powerful features of AstManProxy is its ability to
automatically filter output on a per-client basis.  It can do this
with its Autofilter capability, which can be set 'on'/'unique' in
the config file or enabled via the ProxyAction: SetAutoFilter function.

With autofiltering 'on', each client only receives output containing
the "ActionID" parameter it has set most recently.  This is useful
for single atomic requests into asterisk from a client, such as
when creating a simple UI to inject a command.

For example, if a client sends this packet while autofiltering is
enabled:

Action: Ping
ActionID: foo

Then the autofilter ActionID for that client is set to foo, and no
output besides for responses containing "foo" will be returned
to that client, such as:

Response: Pong
ActionID: foo

Replace Ping with Originate and Pong with Success and you can see
how this same mechanism can be used to quickly query asterisk
box(es), initiate calls, etc, without your client having to worry
with filtering a lot of unrelated output.

A more advanced verion of this facility is to set autofiltering to
'unique'. This causes astmanproxy to alter the ActionID on the way
to Asterisk, and undo that change on the way back.

For example the exchange:

> Action: Ping
> ActionID: foo
>

< Response: Pong
< ActionID: foo
<

Might be seen by Asterisk as:

> Action: Ping
> ActionID: amp7-foo
>

< Response: Pong
< ActionID: amp7-foo
<

and the "amp7-" prefix is created uniquely for each client connection.

===================================================================
On the astmanproxy.users output filtering functionality

Users may now be defined in your astmanproxy.users configuration file.
This enables a traditional user/password based login mechanism
for Astmanproxy similar to what is found in Asterisk.  Output may be
filtered on a per-user basis.

"user" is the username, secret is the password, and the (optional)
channel setting causes filtering of events only for the specified
channel to be sent to this user.

Following this, an outbound context and an inbound context may be
(optionally) specified. This will cause messages to and from
Asterisk respectively to be blocked if they contain a Context: header
which does not match the specified value. This might be used to
prevent a client making calls except in a predefined context.

An account code may be (optionally) specified. This will
force the Account: header to be overwritten for all commands to/from
this client. If the Action is "Originate", then a missing Account:
header will be added.

A "server" option will cause the proxy to behave as if the
client has included a "Server:" header in each request packet.

Any non-empty string provided in "more_events" will allow the passing
of non-filterable events to all clients. The default behaviour is to
block these packets if any form of filtering is requested.

user=secret,channel,out_context (to Asterisk),in_context (From Asterisk),accountcode,server,more_events

e.g.:
  steve=steve,SIP/snom190,local,
  dave=securepass,SIP/1002,,,davesaccount,daveserver
  bill=pass

===================================================================
On the 'Action: Challenge' Authentication Mechanism

John Todd wrote this excellent summary of the Action: Challenge
Authentication Mechanism, and it accurately describes the
implementation included in astmanproxy:

While the SSL encryption of the AMI is great, it's always a good
policy to never send passwords at all if you have an alternative.

  After connecting to the AMI port, send this message:

   Action: Challenge
   AuthType: MD5

  You should receive a challenge string:
 
   Response: Success
   Challenge: 125065091

Then, assuming that the manager username is "joebob" and the
password is "yoyodyne11", perform this on a shell line of a handy
UNIX system (you programmers will figure out how to do this with a
library call, I'm sure):

   bash-3.00# md5 -s 125065091yoyodyne11
   MD5 ("125065091yoyodyne11") = e83a9e59e7c8d1bb6554982275d05016
   bash-3.00# 
 
  Now use this key to log in, so type this to the AMI:

    Action: Login
    AuthType: MD5
    Username: joebob
    Key: e83a9e59e7c8d1bb6554982275d05016

  ...and you'll get:

   Response: Success
   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

Current development on AstManProxy is happening here:
http://github.com/davetroy/astmanproxy/tree/master

Please feel free to fork and contribute!

Also, there is a new mailing list / group available here:
http://groups.google.com/group/astmanproxy?hl=en

===================================================================
AstManProxy Background Information
----------------------------------

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.

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-2008 David C. Troy, dave@popvox.com