Making these documentation changes in the 1.4 branch upset various people, so

these chanes will only be done in the trunk.


git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.4@58955 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 311 insertions, 0 deletions

diff --git a/doc/manager.txt b/doc/manager.txt
new file mode 100644
index 000000000..a0a832c8d
--- /dev/null
+++ b/doc/manager.txt
@@ -0,0 +1,311 @@
+The Asterisk Manager TCP/IP API - AMI
+=====================================
+
+The manager is a client/server model over TCP. With the manager interface,
+you'll be able to control the PBX, originate calls, check mailbox status,
+monitor channels and queues as well as execute Asterisk commands.
+
+AMI is the standard management interface into your Asterisk server.
+You configure AMI in manager.conf. By default, AMI is available on
+TCP port 5038 if you enable it in manager.conf.
+
+AMI receive commands, called "actions". These generate a "response"
+from Asterisk. Asterisk will also send "Events" containing various
+information messages about changes within Asterisk. Some actions
+generate an initial response and data in the form list of events.
+This format is created to make sure that extensive reports do not
+block the manager interface fully.
+
+Management users are configured in the configuration file manager.conf and are 
+given permissions for read and write, where write represents their ability 
+to perform this class of "action", and read represents their ability to 
+receive this class of "event".
+
+The Asterisk manager interface in version 1.0.x of Asterisk is
+not very well standardized. Work is under way to change this 
+to Asterisk 1.2. If you develop AMI applications, treat the headers
+in Actions, Events and Responses as local to that particular
+message. There is no cross-message standardization of headers.
+
+If you develop applications, please try to reuse existing manager
+headers and their interpretation. If you are unsure, discuss on
+the asterisk-dev mailing list.
+
+Device status reports
+---------------------
+Manager subscribes to extension status reports from all channels,
+to be able to generate events when an extension or device changes
+state. The level of details in these events may depend on the channel
+and device configuration. Please check each channel configuration
+file for more information. (in sip.conf, check the section on
+subscriptions and call limits)
+
+
+Command Syntax
+--------------
+Management communication consists of tags of the form "header: value", 
+terminated with an empty newline (\r\n) in the style of SMTP, HTTP, and
+other headers.
+
+
+The first tag MUST be one of the following:
+
+    * Action: An action requested by the CLIENT to the Asterisk SERVER. Only one "Action" may be outstanding at any time.
+    * Response: A response to an action from the Asterisk SERVER to the CLIENT.
+    * Event: An event reported by the Asterisk SERVER to the CLIENT 
+
+
+Manager commands
+----------------
+Output from the CLI command 'show manager' command:
+
+    * Ping: Ping
+    * Logoff: Logoff Manager
+    * Hangup: Hangup Channel
+    * Status: Status
+    * Redirect: Redirect
+    * Originate: Originate Call
+    * MailboxStatus: Check Mailbox
+    * Command: Execute Command
+    * ExtensionState: Check Extension Status
+    * AbsoluteTimeout: Set Absolute Timeout
+    * MailboxCount: Check Mailbox Message Count
+    * Monitor: Monitor a channel
+    * StopMonitor: Stop monitoring a channel
+    * ChangeMonitor: Change monitoring filename of a channel
+    * IAXpeers: List IAX Peers (Defaults to IAX2)
+    * SIPpeers: List SIP peers
+    * SIPshowpeer: Show data about one SIP peer
+    * Queues: Queues
+    * QueueStatus: Queue Status 
+
+This list depends on the version of Asterisk you are using, as
+well as which modules that are loaded.
+
+Command Summary
+--------------
+
+Command: Command
+Parameters: Command
+
+Command: ExtensionState
+Parameters: Exten, Context, ActionID
+
+Command: Hangup
+Parameters: Channel
+
+Command: Logoff
+Parameters: None
+
+Command: MailboxCount
+Parameters: Mailbox, ActionID
+
+Command: MailboxStatus
+Parameters: Mailbox, ActionID
+
+Command: Originate
+Parameters: Channel, Exten, Context, Priority, Timeout, 
+   CallerID, Variable, Account, Application, Data, Async
+
+Command: Ping
+Parameters: None
+
+Command: PlayDTMF
+Parameters: Channel, Digit
+
+Command: Redirect
+Parameters: Channel, ExtraChannel, Exten, Context, Priority
+
+Command: Timeout
+Parameters: Channel, Timeout
+
+You can always get more information about a manager command
+with the "show manager command <command>" CLI command in Asterisk.
+
+Examples
+--------
+Login - Log a user into the manager interface.
+
+   Action: Login
+   Username: testuser
+   Secret: testsecret
+
+Originate - Originate a call from a channel to an extension.
+
+   Action: Originate
+   Channel: sip/12345
+   Exten: 1234
+   Context: default
+
+Originate - Originate a call from a channel to an extension without waiting
+for call to complete.
+
+   Action: Originate
+   Channel: sip/12345
+   Exten: 1234
+   Context: default
+   Async: yes
+
+
+Redirect with ExtraChannel:
+  Attempted goal:
+  Have a 'robot' program Redirect both ends of an already-connected call
+  to a meetme room using the ExtraChannel feature through the management interface.
+
+  Action: Redirect
+  Channel: Zap/1-1
+  ExtraChannel: SIP/3064-7e00 (varies)
+  Exten: 680
+  Priority: 1
+
+Where 680 is an extension that sends you to a MeetMe room.
+
+There are a number of GUI tools that use the manager interface, please search
+the mailing list archives and the documentation page on the 
+http://www.asterisk.org web site for more information.
+
+
+Some standard AMI headers:
+--------------------------
+
+ Account: 			-- Account Code (Status)
+ AccountCode:			-- Account Code (cdr_manager)
+ ACL: <Y | N>			-- Does ACL exist for object ?
+ Action: <action>		-- request or notification of a particular action
+ Address-IP:			-- IPaddress 
+ Address-Port:			-- IP port number
+ Agent: <string>		-- Agent name
+ AMAflags:			-- AMA flag (cdr_manager, sippeers)
+ AnswerTime:			-- Time of answer (cdr_manager)
+ Append: <bool>			-- CDR userfield Append flag
+ Application:			-- Application to use
+ Async:				-- Whether or not to use fast setup
+ AuthType: 			-- Authentication type (for login or challenge)
+					"md5"
+ BillableSeconds:		-- Billable seconds for call (cdr_manager)
+ CallerID:			-- Caller id (name and number in Originate & cdr_manager)
+ CallerID:			-- CallerID number
+				   Number or "<unknown>" or "unknown" 
+					(should change to "<unknown>" in app_queue)
+ CallerID1:                     -- Channel 1 CallerID (Link event)
+ CallerID2:                     -- Channel 2 CallerID (Link event)
+ CallerIDName:			-- CallerID name
+				   Name or "<unknown>" or "unknown" 
+					(should change to "<unknown>" in app_queue)
+ Callgroup:			-- Call group for peer/user
+ CallsTaken: <num>		-- Queue status variable
+ Cause: <value>			-- Event change cause - "Expired"
+ Cause: <value>			-- Hangupcause (channel.c)
+ CID-CallingPres:		-- Caller ID calling presentation
+ Channel: <channel>		-- Channel specifier
+ Channel: <dialstring>		-- Dialstring in Originate
+ Channel: <tech/[peer/username]> -- Channel in Registry events (SIP, IAX2)
+ Channel: <tech>		-- Technology (SIP/IAX2 etc) in Registry events
+ ChannelType:			-- Tech: SIP, IAX2, ZAP, MGCP etc
+ Channel1:			-- Link channel 1
+ Channel2:			-- Link channel 2
+ ChanObjectType:		-- "peer", "user"
+ Codecs:			-- Codec list
+ CodecOrder:			-- Codec order, separated with comma ","
+ Command:			-- Cli command to run
+ Context:			-- Context
+ Count: <num>			-- Number of callers in queue
+ Data:				-- Application data
+ Default-addr-IP:		-- IP address to use before registration
+ Default-Username:		-- Username part of URI to use before registration
+ Destination:			-- Destination for call (Dialstring ) (dial, cdr_manager)
+ DestinationContext:		-- Destination context (cdr_manager)
+ DestinationChannel:		-- Destination channel (cdr_manager)
+ DestUniqueID:			-- UniqueID of destination (dial event)
+ Disposition:			-- Call disposition (CDR manager)
+ Domain: <domain>		-- DNS domain
+ Duration: <secs>		-- Duration of call (cdr_manager)
+ Dynamic: <Y |  N>		-- Device registration supported?
+ Endtime:			-- End time stamp of call (cdr_manager)
+ EventList: <flag>		-- Flag being "Start", "End", "Cancelled" or "ListObject"
+ Events: <eventmask>		-- Eventmask filter ("on", "off", "system", "call", "log")
+ Exten:				-- Extension (Redirect command)
+ Extension:			-- Extension (Status)
+ Family: <string>		-- ASTdb key family
+ File: <filename>		-- Filename (monitor)
+ Format: <format>		-- Format of sound file (monitor)
+ From: <time>			--  Parking time (ParkedCall event)
+ Hint:				-- Extension hint
+ Incominglimit:			-- SIP Peer incoming limit
+ Key:
+ Key:				-- ASTdb Database key
+ LastApplication:		-- Last application executed (cdr_manager)
+ LastCall: <num>		-- Last call in queue
+ LastData:			-- Data for last application (cdr_manager)
+ Link:				-- (Status)
+ ListItems: <number>		-- Number of items in Eventlist (Optionally sent in "end" packet)
+ Location:			-- Interface (whatever that is -maybe tech/name in app_queue )
+ Loginchan:			-- Login channel for agent
+ Logintime: <number>		-- Login time for agent
+ Mailbox:			-- VM Mailbox (id@vmcontext) (mailboxstatus, mailboxcount)
+ MD5SecretExist: <Y | N>	-- Whether secret exists in MD5 format 
+ Membership: <string>		-- "Dynamic" or "static" member in queue
+ Message: <text>		-- Text message in ACKs, errors (explanation)
+ Mix: <bool> 			-- Boolean parameter (monitor) 
+ NewMessages: <count>	 	-- Count of new Mailbox messages (mailboxcount)
+ Newname:		
+ ObjectName:			-- Name of object in list
+ OldName:			-- Something in Rename (channel.c)
+ OldMessages: <count>		-- Count of old mailbox messages (mailboxcount)	
+ Outgoinglimit:			-- SIP Peer outgoing limit
+ Paused: <num>			-- Queue member paused status
+ Peer: <tech/name>		-- "channel" specifier :-)
+ PeerStatus: <tech/name>	-- Peer status code 
+					"Unregistered", "Registered", "Lagged", "Reachable"
+ Penalty: <num>			-- Queue penalty
+ Priority:			-- Extension priority
+ Privilege: <privilege>		-- AMI authorization class (system, call, log, verbose, command, agent, user)
+ Pickupgroup:			-- Pickup group for peer
+ Position: <num>		-- Position in Queue
+ Queue:				-- Queue name
+ Reason:			-- "Autologoff"
+ Reason:			-- "Chanunavail"
+ Response: <response>		-- response code, like "200 OK"
+					"Success", "Error", "Follows"
+ Restart:			-- "True", "False"
+ RegExpire:			-- SIP registry expire
+ RegExpiry:			-- SIP registry expiry
+ Reason:			-- Originate reason code
+ Seconds:			-- Seconds (Status)
+ Secret: <password>		-- Authentication secret (for login)
+ SecretExist: <Y | N>		-- Whether secret exists 
+ Shutdown:			-- "Uncleanly", "Cleanly" 
+ SIP-AuthInsecure:
+ SIP-FromDomain:		-- Peer FromDomain
+ SIP-FromUser:			-- Peer FromUser
+ SIP-NatSupport:
+ SIPLastMsg:
+ Source:			-- Source of call (dial event, cdr_manager)
+ SrcUniqueID:			-- UniqueID of source (dial event)
+ StartTime: 			-- Start time of call (cdr_manager)
+ State:				-- Channel state
+ Status:			-- Registration status (Registry events SIP)
+ Status:			-- Extension status (Extensionstate)
+ Status:			-- Peer status (if monitored)  ** Will change name **
+					"unknown", "lagged", "ok"
+ Status: <num>			-- Queue Status
+ Status:			-- DND status (DNDState)
+ Time: <sec>			-- Roundtrip time (latency)
+ Timeout:			-- Parking timeout time
+ Timeout:			-- Timeout for call setup (Originate)
+ Timeout: <seconds>		-- Timeout for call
+ Uniqueid:			-- Channel Unique ID
+ Uniqueid1:			-- Channel 1 Unique ID (Link event)
+ Uniqueid2:			-- Channel 2 Unique ID (Link event)
+ User:				-- Username (SIP registry)
+ UserField:			-- CDR userfield (cdr_manager)
+ Val:				-- Value to set/read in ASTdb
+ Variable:			-- Variable AND value to set (multiple separated with | in Originate)
+ Variable: <name>		-- For channel variables
+ Value: <value>			-- Value to set
+ VoiceMailbox:			-- VM Mailbox in SIPpeers
+ Waiting:			-- Count of mailbox messages (mailboxstatus)
+
+ ** Please try to re-use existing headers to simplify manager message parsing in clients.
+
+Read the CODING-GUIDELINES if you develop new manager commands or events.