Asterisk Managment Interface (AMI), Part 1
AMI is Asterisk's powerful and convenient software interface (API) for managing the system from external programs. In addition to AMI, AGI is often used - it is an interface for launching external applications that control the Asterisk channel within a particular call. Thanks to AMI, external programs can make connections with Asterisk via the TCP protocol, initiate command execution, read the result of their execution, as well as receive notifications about events in real time. These mechanisms can be used, for example, in the following cases:
AMI is often used to integrate with business processes and systems, CRM software (Customer Relationship Management). It can also be used for a variety of applications, such as automatic dialing programs and click-to-call systems (click-to-call).
Asterisk is often managed from the CLI console, but when using AMI, you do not need direct access to the server on which Asterisk is running. AMI is the simplest tool that, in the hands of a developer, can be a very powerful and flexible tool for integration with other software products. It allows developers to use the information generated by Asterisk in real time.
It is also worth noting that Asterisk since version 1.6 uses the interface manager version 1.1. Basically, the changes concerned the unification of many teams of the same type and the standardization of answers issued by various modules. You can find out the version of the interfaces using the CoreSettings command. The version may change further if the AMI interface loses full compatibility with previous versions.
')
Between the Asterisk server and the client program, a simple, per-line protocol is used to establish a connection; each line of the message consists of two lines:
In the following, we will use the term “package”, which will describe a series of “key: value” constructions separated by CRLF and completed by the additional sequence CRLF.
The protocol of interaction between Asterisk and the client can be described by the following characteristics:
AMI accepts connections established on a network port (by default, TCP port 5038). The client program connects to the AMI through this port and is authenticated, then the Asterisk will respond to requests and also send notifications about changes in the state of the specified subsystems
Types of packages
The packet transmitted from the client to the Asterisk server and back is determined by the following key characteristics:
As a rule, the client sends Action packets to Asterisk (they are also called commands). The asterisk, in turn, executes the request and returns the result (often the result is the success of the action with a brief description in case of failure) received in the Response package. There is no guarantee regarding the order of arrival of results (response packages), therefore, in a client request, the ActionID parameter is usually included in each Action package, and the corresponding Response package will contain the same value in the ActionID field. Thus, the client can very easily process Action and Response packets, in any desired order, without waiting for Response packets to take the next action.
The following CLI command (Tab completion completes) helps to get a complete list of AMI commands available in your version of Asterisk:
Packets Response. As written above, serve as responses to the transmitted commands. One response is sent to a command and may carry several values:
Event packages (events) are applied in two contexts. On the one hand, they inform the client about changes in the status of the Asterisk subsystems (eg. Channel status changes), on the other hand, they transfer the data set that Asterisk returns in response to Action.
Events are not documented in the CLI, so detailed information can be found in the documentation (file manager_1_1.txt), on voip-info.org. If you still have the impression that some event is not described, but it should be - you can find all sorts of events in the source code of the corresponding module by the function name - manager_event
Before turning to practical examples, it is worth noting that since version 1.6 of Asterisk, the AMI interface has acquired the version number 1.1. This is due to bringing the format of commands to a single format and partial loss of compatibility. The article will cover the work of version 1.6, where differences exist explanations will be given in brackets.
Security
Since the possibilities for managing the operation of the system provided through the AMI interface are almost endless. In addition to an unencrypted password and the ability to restrict access to AMI from certain ip-addresses, the Manager interface (as it is also called) does not have other security tools, so it is not recommended to use it on public IP addresses.
If the use of the public network is necessary, then it is necessary to ensure that access is limited using iptables or made through VPN tunnels of any type. Access to the AMI interface can also be obtained via the built-in HTTP (S) server, access is configured in the http.conf file. It is worth noting that, by default, the AMI interface is prohibited, just like working with it through an HTTP server.
Also on an unreliable network, if you want to provide end-user access to AMI (for example, click-2-call functionality via TAPI), AstManProxy is recommended to handle all connections to the Manager API. About him another time.
In order to use the AMI interface, you must edit the /etc/asterisk/manager.conf file, which is responsible for the configuration.
The [general] section defines general connection settings. Enables AMI enabled = yes. Note: For the settings to take effect, you must do an AMI overload:
or
Using the deny and permit options, you can specify ip-addresses from which it is possible to connect to Asterisk. You can add more system users (by copying the section starting with square brackets) and assign access rights to them:
In the above example, the admin user was given extensive rights, right up to stopping the Asterisk service (the command option is responsible for this). In subsequent versions (1.6.1 and later) it is forbidden to use commands in AMI, which can lead to the asterisk stopping.
- Need to know the state of the system
- Number of active subscribers
- Run CLI commands remotely
- Improve CDR storage
- … and much more
AMI is often used to integrate with business processes and systems, CRM software (Customer Relationship Management). It can also be used for a variety of applications, such as automatic dialing programs and click-to-call systems (click-to-call).
Asterisk is often managed from the CLI console, but when using AMI, you do not need direct access to the server on which Asterisk is running. AMI is the simplest tool that, in the hands of a developer, can be a very powerful and flexible tool for integration with other software products. It allows developers to use the information generated by Asterisk in real time.
It is also worth noting that Asterisk since version 1.6 uses the interface manager version 1.1. Basically, the changes concerned the unification of many teams of the same type and the standardization of answers issued by various modules. You can find out the version of the interfaces using the CoreSettings command. The version may change further if the AMI interface loses full compatibility with previous versions.
How does AMI work
')
Between the Asterisk server and the client program, a simple, per-line protocol is used to establish a connection; each line of the message consists of two lines:
- key is a keyword describing the nature of the information contained in the current line. The keyword is not unique and can occur several times in the same package.
- value - the value of the parameter
- The keyword is separated from the value by a colon.
In the following, we will use the term “package”, which will describe a series of “key: value” constructions separated by CRLF and completed by the additional sequence CRLF.
The protocol of interaction between Asterisk and the client can be described by the following characteristics:
- Before sending commands to the Asterisk server, you must perform a session connecting the client to the Asterisk server;
- Packets can be transmitted in any order and at any time after passing the authentication procedure;
- The first line of the packet must contain one of the following keys: “Action” (the only option when sent by the client), and keys are “Event” (Event) and “Response” (must be sent from Asterisk to the client);
- The order of the lines in the package does not matter; you can use any programming language with which you can form packages on the client side;
- CRLF is used to separate each of the lines in the packet and the two CRLF sequences (also known as \ r \ n) in order to signify the completion of the transfer of the command to Asterisk
AMI accepts connections established on a network port (by default, TCP port 5038). The client program connects to the AMI through this port and is authenticated, then the Asterisk will respond to requests and also send notifications about changes in the state of the specified subsystems
Types of packages
The packet transmitted from the client to the Asterisk server and back is determined by the following key characteristics:
- Action, packets sent by the client connected to AMI. After the server has processed this package, some action will be taken. There are relatively flexible restrictions on the actions taken by the client. One package - one action. The Action package must contain the name of the operation to be performed, as well as all the necessary parameters;
- Response, determines the answer that Asterisk sends to the client upon the completion of the action;
- Event, data related to the event that is generated inside the Asterisk core or expansion module.
As a rule, the client sends Action packets to Asterisk (they are also called commands). The asterisk, in turn, executes the request and returns the result (often the result is the success of the action with a brief description in case of failure) received in the Response package. There is no guarantee regarding the order of arrival of results (response packages), therefore, in a client request, the ActionID parameter is usually included in each Action package, and the corresponding Response package will contain the same value in the ActionID field. Thus, the client can very easily process Action and Response packets, in any desired order, without waiting for Response packets to take the next action.
The following CLI command (Tab completion completes) helps to get a complete list of AMI commands available in your version of Asterisk:
*CLI> manager show commandsPackets Response. As written above, serve as responses to the transmitted commands. One response is sent to a command and may carry several values:
- "Success" - the action is successful and all information is contained in this package.
- “Error” - an error occurred, a detailed description in the header of “Message”
- “Follows” - the result of execution will be transmitted in subsequent Event packages.
Event packages (events) are applied in two contexts. On the one hand, they inform the client about changes in the status of the Asterisk subsystems (eg. Channel status changes), on the other hand, they transfer the data set that Asterisk returns in response to Action.
- When a client sends an Action packet, Asterisk may (in cases where it is necessary to return many homogeneous entries) send a Response packet containing the “Response: Follows” record. Next, the Asterisk sends a number of events containing a data set and, finally, an event that reports that all data has been sent. All Event packets generated by this contain the ActionID of the original Action packet that initiated the request. Thus, you can easily handle them, as well as Response packages. An example of an event generated by an Action is the Action Status, which triggers a Status event for each of the active channels. After all Status events have been transmitted, the StatusComplete event is sent.
- Events are created by various structural parts of Asterisk (SIP / IAX2 / ... channels, CDR, dialplan, different parts of the core). The main task assigned to the events is to allow the external connected system to receive information from the Asterisk, collecting all these events, analyzing them and performing actions depending on the results obtained.
Events are not documented in the CLI, so detailed information can be found in the documentation (file manager_1_1.txt), on voip-info.org. If you still have the impression that some event is not described, but it should be - you can find all sorts of events in the source code of the corresponding module by the function name - manager_event
Before turning to practical examples, it is worth noting that since version 1.6 of Asterisk, the AMI interface has acquired the version number 1.1. This is due to bringing the format of commands to a single format and partial loss of compatibility. The article will cover the work of version 1.6, where differences exist explanations will be given in brackets.
Security
Since the possibilities for managing the operation of the system provided through the AMI interface are almost endless. In addition to an unencrypted password and the ability to restrict access to AMI from certain ip-addresses, the Manager interface (as it is also called) does not have other security tools, so it is not recommended to use it on public IP addresses.
If the use of the public network is necessary, then it is necessary to ensure that access is limited using iptables or made through VPN tunnels of any type. Access to the AMI interface can also be obtained via the built-in HTTP (S) server, access is configured in the http.conf file. It is worth noting that, by default, the AMI interface is prohibited, just like working with it through an HTTP server.
Also on an unreliable network, if you want to provide end-user access to AMI (for example, click-2-call functionality via TAPI), AstManProxy is recommended to handle all connections to the Manager API. About him another time.
AMI Configuration
In order to use the AMI interface, you must edit the /etc/asterisk/manager.conf file, which is responsible for the configuration.
[general]
enabled=yes ; AMI (- no)
port=5038 ; TCP 5038
bindaddr=192.168.0.1 ; (0.0.0.0 - )
timestampevents = yes ;
displayconnects = yes ; AMI
allowmultiplelogin = yes ;
; ,
[admin] ; ,
secret=passwd1234 ; AMI
deny=0.0.0.0/0.0.0.0 ; ip-
permit=192.168.0.2/255.255.255.0 ; ip
read=system, call, log, verbose, command, agent, user ;
write=system, call,log, verbose, command, agent, user ;
The [general] section defines general connection settings. Enables AMI enabled = yes. Note: For the settings to take effect, you must do an AMI overload:
*CLI>module reload manageror
*CLI>manager reloadUsing the deny and permit options, you can specify ip-addresses from which it is possible to connect to Asterisk. You can add more system users (by copying the section starting with square brackets) and assign access rights to them:
- read - read permissions;
- write - write permission.
In the above example, the admin user was given extensive rights, right up to stopping the Asterisk service (the command option is responsible for this). In subsequent versions (1.6.1 and later) it is forbidden to use commands in AMI, which can lead to the asterisk stopping.
Links
Source: https://habr.com/ru/post/64105/
All Articles