Populating trunk

git-svn-id: http://svncommunity.digium.com/svn/astmanproxy/trunk@18 f02b47b9-160a-0410-81a6-dc3441afb0ec

1 files changed, 224 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..7369dd2
--- /dev/null
+++ b/README
@@ -0,0 +1,224 @@
+astmanproxy README (c) 2005 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 quasi-stateful proxy 
+based in c/pthreads.  It is now capable of serving as the basis for 
+an extensible application framework for multiple Asterisk servers.
+
+New features in version 1.1 include:
+
+ - Multiple Input/Output formats: HTTP, XML, CSV, and Standard
+ - 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