path: root/README

astmanproxy README
(c) 2005-2006 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 stateful proxy written
in c/pthreads.  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

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