From 0c43a5ab3637e311a9232ae77ecd8e7f05c2f8cc Mon Sep 17 00:00:00 2001 From: oej Date: Wed, 1 Feb 2006 17:49:02 +0000 Subject: - Removing the "README." from the name of the README files. git-svn-id: http://svn.digium.com/svn/asterisk/trunk@9047 f38db490-d61c-443f-a65b-d21fe96a405b --- doc/manager.txt | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 doc/manager.txt (limited to 'doc/manager.txt') diff --git a/doc/manager.txt b/doc/manager.txt new file mode 100644 index 000000000..065d70a21 --- /dev/null +++ b/doc/manager.txt @@ -0,0 +1,298 @@ +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. + + +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: 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 " 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: -- Does ACL exist for object ? + Action: -- request or notification of a particular action + Address-IP: -- IPaddress + Address-Port: -- IP port number + Agent: -- Agent name + AMAflags: -- AMA flag (cdr_manager, sippeers) + AnswerTime: -- Time of answer (cdr_manager) + Append: -- 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 "" or "unknown" + (should change to "" in app_queue) + CallerID1: -- Channel 1 CallerID (Link event) + CallerID2: -- Channel 2 CallerID (Link event) + CallerIDName: -- CallerID name + Name or "" or "unknown" + (should change to "" in app_queue) + Callgroup: -- Call group for peer/user + CallsTaken: -- Queue status variable + Cause: -- Event change cause - "Expired" + Cause: -- Hangupcause (channel.c) + CID-CallingPres: -- Caller ID calling presentation + Channel: -- Channel specifier + Channel: -- Dialstring in Originate + Channel: -- Channel in Registry events (SIP, IAX2) + Channel: -- 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: -- 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: -- DNS domain + Duration: -- Duration of call (cdr_manager) + Dynamic: -- Device registration supported? + Endtime: -- End time stamp of call (cdr_manager) + EventList: -- Flag being "Start", "End", "Cancelled" or "ListObject" + Events: -- Eventmask filter ("on", "off", "system", "call", "log") + Exten: -- Extension (Redirect command) + Extension: -- Extension (Status) + Family: -- ASTdb key family + File: -- Filename (monitor) + Format: -- Format of sound file (monitor) + From: