
===================================================
Welcome to the Asterisk Manager Proxy Daemon (AMP)
===================================================

Installation instructions are in the file INSTALL.
Documentation on the commands available for the server are in the doc/AMP_Protocol.txt file.

This software was created in the hope that it will be useful to any and all who need it. It was initially designed to be an aid to commercial environments where managers need to manage call centers.


Important Notes
---------------
As of version 0.9.3 of ampd you MUST use libami version >= 0.9.2 due to a change in some arguments of specific functions in the library.


Overview
---------
  So wtf is this software anyway? AMP is intended first and foremost to be a proxy to an asterisk PBX server.
Due to some inherent restrictions in Asterisk, multiple sockets connected to Asterisk's manager interface have been reported to make it crash. AMP acts as a middle man, creating (only) two connections to asterisk, one to propegate Events to clients, and one to accept and pass on commands from clients.

  As an added bonus, AMP maintains daily statistics which it collects from Asterisk Events, which AMP can either send along as "Statistic Events" to clients and/or maintain them in a small database file for later report generation. By default AMP does both.

Events and Commands
-------------------
  Events and Commands are the main reason for the existance of the proxy. It allows an arbitrary number of clients to receive events and send commands to the server.

  One goal in the development of the server was to attempt to remain as loyal as possible to the native format of Asterisk. Because of this, most commands and events are identical if not exactly the same as  if you had connected to Asterisk directly. There are some minor changes here or there, but for the most part,
if you had been using Asterisk's manager interface in the past, you should have little to do in order to migrate to the AMP Daemon.

Basic Communication
-------------------
  By default, AMP uses XML for all communications. You can use Asterisk native format for communication and flip flop back and forth at any given time, however, Asterisk native format has not been extensively tested.
The default format for communication can be changed in ampd.conf as well as on a per-user basis in ampd_users.conf.

Users and Permissions
---------------------
  The file ampd_users.conf, by default in /etc, stores all the users that can connect to the AMP Daemon. There are three levels of permissions, which effect which events the user receives from the server as well as what commands they are allowed to send to Asterisk.

  The 'admin' permission allows all events and all commands. I know, I know, that one was obvious, but I put it in here for completeness. Alright! Fine! That's not true, I just wanted to be able to use the word completeness in a sentence. Jeeze! Leave me alone already!

  The 'monitor' permission is intended for managers that are not necessarily technical, yet need to manage people and queues. It allows all events to be sent to the client but restricts certain commands, mostly technical and administrative commands to be sent to asterisk.

  The 'agent' permission is the most restrictive. It allows events that relate to that specific agent (judged by their agent ID) to be sent to that client. It also restricts the user from sending *most* commands to Asterisk.

  For a list of commands and their respective permission levels, check the top of the file client.c in the source tree. There are three constants defined: CLIENT_REG_TYPE_AGENT, CLIENT_REG_TYPE_MONITOR, and CLIENT_REG_TYPE_ADMIN. The higher permission levels inherit the abilities of the permission levels below it.

  Passwords can be disabled globally, or on a per-permission level (i.e. monitors log in trusted, yet agents and admins need a password) in the ampd.conf file, and also on a per-user level in the amp_users.conf file.
Trusted users bypass passwords, but not their permission level as specified in amp_users.conf

Statistics
----------
  Statistics can be both stored and sent as events to manager and admin clients. If they are not stored, then statistics are lost when the server is restarted for any reason. Statistics clear themselves at midnight local time every day as well.

  There are a couple utilities included in the AMP package for dealing with statistics specifically. In the utils directory there are two ampdb* programs: ampdb2xml and ampdb_dump. ampdb_dump is more for debugging purposes, it simply dumps every record in a given stats.db file. ampdb2xml converts a given stats.db file
to xml (duh <grin>).

  Also included are a few perl files and an example Excel template for report generation. Little documentation exists for these because I'm evil and I suck... oh yeah and I hate documenting things, but the examples should get any perl programmer through creating a customized report without to much issue. HINT: Don't try to go through the ExcelTemplateReport.pm!! It's um ... complicated :) Trust me, save your sanity if you still have it.

  The perl utilities are as follows: 
    * prettyXML.pl takes an ugly XML file (as generated by ampdb2xml) where all the xml is on one big long line and makes it pretty human readable XML. It is mostly for debugging purposes.
    * generate_daily_report.pl creates a daily report based off an XML file converted from a database with the ampdb2xml utility. You almost definitely want to mess with it before you try to use it. The script requires the ExcelTemplateReport.pm module as well as other modules indicated at the top of the file and module as well as an Excel template.

  When I get some time I'll clean up and document the report generation perl script.

  I've noticed a small caveot to using DB4 as well, occasionally if there's a catastrophic crash while the DB is open the database will have minor corruption. I've never lost data, but the server hangs while trying to load the DB when starting up. Here is how to fix that problem:
  cd to the directory storing the stats.db file (default /var/lib/ampd/stats/mm-dd-yyyy) and run the following command: 'db_recover -e -v' The db_recover utility should have come with your distribution of Berkely DB.
  If you do not include the '-e' argument, you will LOSE your db environment, rendering the DB useless. Here's a trick to save your data in case you do that by mistake: 
   * move the directory to another name.
   * Start the proxy server and then kill it
   * move the old stats.db file to the new directory.
   * run db_recover -e -v
   * Start the proxy server. 
  After those steps is *should* run fine.

Other Utilities
---------------
  Yeah I know this probably doesn't deserve a section. Shoosh! My text editor has been lonely for the last couple of days ok??
  In the utils directory of the source tree you'll also find ampd.init, a redhat style init script. Try it out, mess with it, hack it to your hearts desire.
  You will also find a safe_ampd bash script. It's cool. It's blatantly ripped off from Asterisk's safe_asterisk script. It runs in a loop and restarts ampd in the event of a crash, and with ampd being in beta, it's a good idea :)

Event Notes
-----------
  There are some specific things to note about events, specifically which events make it to clients and how the proxy server deals with events. All events generated from Asterisk (with a couple exceptions noted below) are delivered to appropriate clients AS IS. If you are using XML as your communication format, the event is still exactly the same, only converted to XML. Here's an example:

  ** Asterisk Format **
  Event: Agentcallbacklogin
  Agent: 12
	Loginchan: SIP/12

  ** XML Format **
  <Event event="Agentcallbacklogin" Agent="12" Loginchan="SIP/12" />
  
  Exceptions:
  * There is an option in ampd.conf to ignore the 'NewExten' event, which is nearly useless to most applications and (depending on your dial plan of course) generates an obnoxious amount of traffic. I'd  keep the option set to ignore this event unless you really know what you're doing or you really hate having
low latency on your network.
  * The AgentConnect event has been modified to include a "ChannelCalling" attribute in *addition* to the attributes it already has. This is very similar to the AgentCalled event which has an attribute of the same name and nature, yet for managing certain events I find it unnecessarily difficult to work with both the
AgentCalled and AgentConnect attributes simply because the AgentConnect event doesn't tell you WHO you're connected WITH... so .. I um .. fixed that :)

  -------------------------------------
  =>Wholly Crap! Status Events: Note!<=
  -------------------------------------
  Was that dramatic enough?
  To monitor Agents and their status on-the-fly, you *must* enable two configuration options in the queues.conf (or in your DB if you use realtime). These two options control status events and are as follows:
  'eventwhencalled' and 'eventmemberstatusoff'. They should be set to 'eventwhencalled = yes' and 'eventmemberstatusoff = no'. Without at least eventwhencalled, you will lose the information of when agents are called, hangup, etc. You may also lose status information if eventmemberstatusoff is not turned off.
  
  There also is a important fact to note about what events are sent to a manager socket connection:
  In manager.conf in your asterisk config directory (usually /etc/asterisk) you must specify on a per login basis. Mine is set to 'system,call,log,verbose,command,agent,user' which should be more than enough events for most purposes.


The Daemon
----------
For a quick reference on options you can always run the daemon with -h or --help.
Usage: ampd [options]
Options are as follows:
         -c or --config         -> Use the config file specified
         -D or --nodaemon       -> Stay in the foreground for debuging purposes
         -h or --help           -> Display version and usage information
         -v or --verbose        -> Print/Log verbose messages
         -d or --debug          -> Print/Log debugging messages
         -V or --version        -> Print version information


Developers
----------
  This is just a Beta release (0.9) as of mid-june 2006. More is definitely to come. If you'd like to help out feel free to email me. j@intuitivecreations.com
  
  There is no interface for agents as this is usually very specific to a given company's needs and is also very small and quick to implement. I've had great success implementing a trivial flash interface in frames for the agents at my current employment.

  The documenation for the commands and events are in the doc directory.
