We have started to discuss the Asterisk software which is the world's most popular open source telephony development tool-kit.

Asterisk Manager Interface (AMI) is a powerful and convenient application program interface (API) of Asterisk for system management from external programs. Another frequently used interface is AGI which is used to manage Asterisk channel within a specific call. Through Asterisk Manager Interface external programs can establish connections to Asterisk by means of TCP protocol, initiate commands execution, read the results, and receive notifications about current events in real-time mode.

These tools can be used whenever you need to:

• Find out the system state;
• Find out the number of active abonents;
• Remotely execute a CLI command;
• Improve CDR storage;
• Perform other actions.

Asterisk Manager Interface is often used for integration with business processes and systems, CRM software. It can be also used for various software, such as automatic dialer applications and click-to-call systems. AMI is a simplest tool that can be turned by a developer to a powerful and flexible means of integration with other software products. It gives a developer a real-time access to information generated by Asterisk.
 
It also should be noted that starting with version 1.6 Asterisk uses the manager interface version 1.1. Mostly the changes have been made with the aim to consolidate one-type commands and regulate replies issued by various modules. The interface version can be found out with the help of CoreSettings command. The interface version can be changed further if AMI loses full compatibility with previous versions. In this article we will describe how to work with version 1.6 and the explanation about existing distinctions will be given in brackets.
 
How AMI operates
 
The connection between Asterisk server and the client program is established with the use of a simple line-by-line protocol, where every string of the message consists of two lines:

• Key is a keyword describing the character of the information contained by the current string. The keyword is not unique and may be used more than once within a packet.
• Value is the parameter value
• The keyword is separated from the parameter value by a colon.

For the sake of discussion below, we will use the term «packet» to describe a set of «key: value» lines that are terminated by an extra CR/LF and concluded by an additional succession of CR/LF.

The interaction protocol between Asterisk and the client has the following characteristics:

• Before sending commands to Asterisk server, it is necessary to establish a connection session of the client with Asterisk server.
• Packets may be transmitted in either direction at any time after authentication.
• The first line of a packet will have a key of "Action" – the only option when sent from the client to Asterisk, and either "Event" or "Response" when sent from Asterisk to the client.
• The order of lines within a packet is insignificant, so you may use your preferred programming language's native unordered dictionary type to efficiently store a single packet.
• CR/LF is used to delimit each line in a packet and two successive CR/LF (or \r\n) to indicate the completion of sending a command to Asterisk.

AMI accepts connections established to a network port (TCP port 5038 by default). When a client program is connected to this port and authenticated, Asterisk will reply to requests, and send notifications on changes in the state of specified subsystems.
 
Types of packets

A packet sent from a client to Asterisk server and back can be identified by the following key characteristics.

• Action packets - packets sent by a client which is connected to AMI. When it is processed by the server, an action takes place. The existing limitations for actions performed by the client are rather flexible. A packet is followed by a single action. Action packet must contain the name of the operation which is to be performed, and all parameters required.
• Response defines the reply sent by Asterisk to the client after the action has taken place.
• Event, the data related to the event generated within Asterisk core or extension module.

Normally the client sends Action packets (which are also called commands) to Asterisk. Asterisk, in turn, executes the request and returns a result (often a result is an action success or a short failure description) received in a Response packet. The order of incoming results (Response packets) is not regulated, which is why a Response packet will contain the same value (as a client’s request) in ActionID field. Thus, the client can easily process Action and Response packets in a desired sequence, as there is no necessity to wait for a Response packet to perform the next action.
 
A next CLI command (Tab-enabled autofill is available) can help you receive a complete list of AMI commands available in your Asterisk version:
 

*CLI> manager show commands

 
Response packets
 
As we mentioned, they serve as responses to transferred commands. A single response is transferred per command and it may have the following values:

• «Success» - the action has been successful and all the information is contained within this packet.
• «Error» - there has been an error; a detailed description can be found in the «Message» header.
• «Follows» the result of the action performed will be transferred in the Event packets to follow.

Event packets (events) are used in two contexts. Firstly, they inform the client of changes in Asterisk subsystem state (for instance, channel state change), on the other hand, the transfer data set returned by Asterisk in response to an Action.

1. When the client sends an Action packet, Asterisk can (when it needs to send a lot of uniform messages), send a Response packet containing just the «Response: Follows» message. Next, Asterisk sends a number of messages containing data and finally, the event informing user that all data has been sent. All generated Event packets contain ActionID of the original Action packet that initiated the request. Thus, they can be easily processed in the same way as Response packets. An example of an event generated by Action is action Status which initiates Status event for each active channel. After all Status events are transferred, a StatusComplete event is sent.
2. Events are created by different structural parts of Asterisk (SIP/IAX2/… channels, CDR, dialplan, various core parts). The primary task performed by events is to allowing the external connected system to receive the information from Asterisk by gathering all the events, analyzing them and taking particular actions depending on the results.

The events are not documented in CLI, so the detailed information can be obtained from the documentation (manager_1_1.txt), at http://www.voip-info.org/. If you get an impression that an event is not described, but it should be, all kinds of events can be found in source code of the corresponding module by the name of the function - manager_event.
 
Security
 
Before we continue with the practical examples, it is worth mentioning that since the system management possibilities granted by AMI interface are virtually unlimited, apart from unsecure password and possibility to limit the access to AMI from specific IPs, the Manager Interface has no other security means so it is highly not recommended to use it at public IPs.

If it is necessary to use it from within a public network, you need to make sure that the access is limited with the use of iptables or is performed via a VPN tunnel of any type. AMI interface can also be accessed via an HTTP(S) server which can be configured in http.conf file. Let us note that AMI interface is disabled by default, and cannot be accessed via HTTP server.
 
Similarly, when using an unsecure network, if one needs to allow end user’s access to AMI (for instance, click-2-call functionality via TAPI) for processing all API connections of Manager Interface, it is recommended to install AstManProxy, which we will discuss at a later time.
 
AMI Configuration
 
To use AMI interface, you need to edit this configuration file: /etc/asterisk/manager.conf
 

[general]
enabled=yes ; ability to work with AMI (no by default);
port=5038 ; at TCP port 5038;
bindaddr=192.168.0.1 ; accept connections in local network (0.0.0.0 – at all interfaces);
timestampevents = yes ; send time stamp as part of packets of events;
displayconnects = yes ; display whether user is connected to AMI;
allowmultiplelogin = yes ; allow several simultaneous connections under the same login.
 
;beginning of the section describing a user;
[admin]; user name defined by Asterisk administrator;
secret=passwd1234 ; AMI user password;
deny=0.0.0.0/0.0.0.0 ; deny all IPs;
permit=192.168.0.2/255.255.255.0 ; allow connections from a single IP only;

read=system, call, log, verbose, command, agent, user; list of event classes transferred to the user;
write=system, call, log, verbose, command, agent, user; list of command classes allowed.

 
The section [general] defines connection settings. AMI is activated by option enabled=yes. Please note: for the settings to take effect, you should reload AMI:
 

*CLI>module reload manager

 or

 *CLI>manager reload

 
With the use of deny and permit options you can specify IP addresses which are allowed to connect to Asterisk. System users can be also added by copying the section starting from square brackets and given permissions:

• read — read permissions;
• write — write permissions.

In the above example the user admin was granted extensive rights, up to stopping the Asterisk service (command option was used for this). Further versions (1.6.1 and later do not allow use of AMI commands that might stop Asterisk).
 
The second part of the article is to be released in a short time. For any specialties or assistance with Asterisk, please, contact us.

Equelli is an offshore outsourcing company providing software development services worldwide. Equelli's team is experienced in the use of Asterisk and other VoIP technologies.

In the area of VoIP software we have:

•    created telephony applications based on Asterisk PBX, project planning;
•    integrated telephony applications into business processes using API for VoIP, built complicated IVR systems;
•    thoroughly tested SIP devices and protocols: sipp, sipsak, PROTOS Test-Suite: c07-sip;
•    sorted out all sorts of problems with SIP protocols;
•    gained an extended knowledge of VoiceXML;
•    created network with QoS and security;
•    solved call problems in IP sphere, such as bad audibility, malfunctioning faxes and modems using  VoIP;
•    expanded existing telephone stations using connection IP PBX by E1/T1;
•    developed and implemented operator's VoIP network;
•    become experts in TCP/IP protocols stack;
•    created infrastructures and automated maintenance systems based of Linksys customer devices.

Igor Goncharovsky
Project Manager, Senior Asterisk Developer