initial 2.0 tree trunk

git-svn-id: svn://192.168.202.10@18 3d104415-ff17-0410-8863-d5cf3c621b8a

docs/ACQS.txt

@@ -0,0 +1,94 @@
++------------------------------------------------------------------------------+
+|      Asterisk GUI client - astguiclient - fourth public release 0.9.2        |
+|             Description of the Asterisk Central Queue System                 |
+|    created by Matt Florell <mattf@vicimarketing.com> <info@eflo.net>         |
+|  project started 2003-10-06   http://sourceforge.net/projects/astguiclient/  |
++------------------------------------------------------------------------------+
+
+This suite of programs is designed to work with the Asterisk Open-source PBX
+(http://www.asterisk.org) as a cross-platform GUI client and the supporting 
+server side applications necessary for the features of the GUI application to 
+work with Asterisk.
+
+Scripts that are involved with the ACQS backend are:
+
+ - AST_SERVER_conf.pl - file where you define your variables for the server apps
+   + Must be present in the /home/cron/ directory
+
+ - AST_manager_listen.pl - listener for the Asterisk Central Queue System (ACQS)
+   + Must be present in the /home/cron/ directory
+   + Requires Net::Telnet, Net::MySQL and Time::HiRes perl Modules
+
+ - AST_manager_send.pl - send-spawn for the ACQS
+   + Must be present in the /home/cron/ directory
+   + Requires Net::Telnet, Net::MySQL and Time::HiRes perl Modules
+
+ - AST_send_action_child.pl - blind-send for the ACQS
+   + Must be present in the /home/cron/ directory
+   + Requires Net::Telnet, Net::MySQL perl Modules
+
+ - ADMIN_keepalive_AST_send_listen.pl - checks to see that ACQS is running
+   + Must put entry for this script in the cron as "* * * * * /path/script"
+
+ - ADMIN_restart_roll_logs.pl - rolls logs over datestamp upon restart
+   + put this script in your machine's startup routine
+
+
+DESCRIPTION:
+This set of programs was created to reduce the risk of deadlocks that occur when 
+the manager interface connection from a remote machine to the Asterisk server 
+becomes severed or backlogged in some way resulting in a buffer-overflow of the 
+manager interface on the Asterisk box and a deadlock of the Asterisk PBX. The 
+probability of this happening is rare on a system where you may have 100 or less 
+action commans being executed a day, but when the action commands rise to the 
+level of 3000+ per server across 30 machines you will have at least 1 deadlock 
+per day if not one per hour. That's why we needed to find a way to still issue 
+manager Actions but not have to maintain a connection with the Asterisk Manager 
+interface. Here is a rundown of how the ACQS works:
+
+There is a simple database table where the action information with unique IDs is 
+stored and where each action's information is updated by the listener. The table 
+I use is called vicidial_manager and is detailed in the CONF_MySQL.txt file in 
+this distribution.
+
+1. First, the GUI client application inserts a record into the table as a NEW 
+action and includes a unique callerID for REDIRECT and ORIGINATE commands(the 
+callerID field is how the listener will update the record in the DB) 
+INSERT INTO vicidial_manager values('','','2004-01-30 
+17:22:53','NEW','N','10.10.11.12','','Originate','DL40130172253cc160','Channel: 
+local/8600011@demo','Context: default','Exten: 917274515135','Priority: 
+1','Callerid: DL40130172253cc160','','','','',''); 
+
+2. Second, there is a constantly running application on the Asterisk box that 
+selects queues from the database to be processed, and launches a new child 
+script to send the action to the database, then marks the action as SENT. 
+
+3. Third, each child process logs into the manager interface and sends the 
+action immediately, then stays open for 10 seconds to not cause any problems, 
+clears it's buffer and then logs out and exits. 
+
+4. Fourth, the listener app is constantly connected on the Asterisk box to the 
+manager interface and parses all output from the manager interface. Every time a 
+"Newstate Ringing" event is seen an update statement is sent to the DB based 
+upon the callerid of the call filling in the channel that the call is on and the 
+uniqueID of the call and sets the record to "UPDATED" 
+
+5. Fifth, the listener also listens for "Hangup" events and sends an update to 
+the DB with a "DEAD" status keyed by the call's uniqueID. 
+
+The above process is executed extremely fast and actually has suprisingly little 
+effect on the load of the Asterisk box. Because each action is sent through it's 
+own child process there is no risk of the system deadlocking because of a single 
+bad action thread. 
+
+
+
+NOTES:
+This started out as a desperate quick fix that evolved into a system that has 
+been up and running reliably on two separate Asterisk servers. Since we 
+implemented ACQS we haven't had a single deadlock on either of these servers.
+If anyone has suggestions/praises/criticisms I would love to hear them.
+
+To use, install the scripts listed above and set the $QUEUE_ACTION_enabled 
+variable in the client's libs/AST_VICI_conf.pl configuration file to 1
+