The section the section called “Quick Start” showed a very basic set of configuration files to get you started. However, there are many more options available for the AMI.
The main configuration file for the AMI is
/etc/asterisk/manager.conf. The
[general] section contains options (listed in Table 20.1, “Options in the manager.conf [general] section”) that control the overall operation of the
AMI. Any other sections in the manager.conf file
will define accounts for logging in and using the AMI.
Table 20.1. Options in the manager.conf [general] section
| Option | Value/Example | Description |
|---|---|---|
enabled
|
yes
| Enables the AMI. The default is
no. |
webenabled
|
yes
| Allows access to the AMI through the built-in HTTP
server. The default is no.[a] |
port
|
5038
| Sets the port number to listen on for AMI connections.
The default is 5038. |
bindaddr
|
127.0.0.1
| Sets the address to listen on for AMI connections. The
default is to listen on all addresses
(0.0.0.0). However, it is highly recommended
to set this to 127.0.0.1. |
tlsenable
|
yes
| Enables listening for AMI connections using TLS. The
default is no. It is highly recommended to
only expose connectivity via TLS outside of the local machine.[b] |
tlsbindport
|
5039
| Sets the port to listen on for TLS connections to the
AMI. The default is 5039. |
tlsbindaddr
|
0.0.0.0
| Sets the address to listen on for TLS-based AMI
connections. The default is to listen on all addresses
(0.0.0.0). |
tlscertfile
|
/var/lib/asterisk/keys/asterisk.pem
| Sets the path to the server certificate for TLS. This is
required if tlsenable is set to
yes. |
tlsprivatekey
|
/var/lib/asterisk/keys/private.pem
| Sets the path to the private key for TLS. If this is not
specified, the tlscertfile will be checked to
see if it also contains the private key. |
tlscipher
|
<cipher string>
| Specifies a list of ciphers for OpenSSL to use. Setting this is optional. To see a list of available ciphers, run openssl ciphers -v at the command line. |
allowmultiplelogin
|
no
| Allows the same account to make more than one connection
at the same time. The default is yes. |
displayconnects
|
yes
| Reports connections to the AMI as verbose messages
printed to the Asterisk console. This is usually useful, but it
can get in the way on a system that uses scripts that make a lot
of connections to the AMI. The default is
yes. |
timestampevents
|
no
| Adds a Unix epoch-based timestamp to every event reported
to the AMI. The default is no. |
brokeneventsaction
|
no
| Restores previously broken behavior for the
Events AMI action, where a response would not
be sent in some circumstances. This option is there for the sake
of backward-compatibility for applications that worked around a
bug and should not be used unless absolutely necessary. The
default is no. |
channelvars
|
VAR1,VAR2,VAR3[,VAR4[...]]
| Specifies a list of channel variables to include with all manager events that are channel-oriented. The default is to include no channel variables. |
debug
|
no
| Enables some additional debugging in the AMI code. This
is primarily there for developers of the Asterisk C code. The
default is no. |
httptimeout
|
60
| Sets the HTTP timeout, in seconds. This timeout affects
users of the AMI over HTTP: it sets the
Max-Age of the HTTP cookie, sets how long
events are cached to allow retrieval of the events over HTTP
using the WaitEvents action, and the amount
of time that the HTTP server keeps a session alive after
completing an AMI action. The default is 60
seconds. |
[a] To access the AMI over HTTP, the
built-in HTTP server must also be configured in
[b] The OpenSSL development package must
be installed for Asterisk to be able to use encryption. On
Ubuntu, the package is | ||
The manager.conf
configuration file also contains the configuration of AMI user accounts.
An account is created by adding a section with the username inside
square brackets. Within each
[ section there
are options that can be set that will apply only to that account. Table 20.2, “Options for [username] sections” lists the options available in a
username][
section.username]
Table 20.2. Options for [username] sections
| Option | Value/Example | Description |
|---|---|---|
secret
|
password
| Sets the password used for authentication. This must be set. |
deny
|
0.0.0.0/0.0.0.0
| Sets an IP address Access Control List (ACL) for addresses that should be denied the ability to authenticate as this user. By default this option is not set. |
permit
|
192.168.1.0/255.255.255.0
| Sets an IP address ACL for addresses that should be
allowed to authenticate as this user. As with
deny, by default this option is not set.
Without these options set, any IP address that can reach the AMI
will be allowed to authenticate as this user. |
writetimeout
|
100
| Sets the timeout used by Asterisk when writing data to
the AMI connection for this user. This option is specified in
milliseconds. The default value is
100. |
display
connects
| yes | Also available in the [general]
section (refer to Table 20.1, “Options in the manager.conf [general] section”), but can be controlled on a
per-user basis. |
read
|
system,call[,...]
| Defines which manager events this user will receive. By
default, the user will receive no events. Table 20.3, “Available values for AMI user account read/write
options” covers the available permission
types for the read and
write options. |
write
|
system,call[,...]
| Defines which manager actions this user is allowed to
execute. By default, the user will not be able to execute any
actions. Table 20.3, “Available values for AMI user account read/write
options” covers the
available permission types for the read and
write options. |
eventfilter
|
!Channel: DAHDI*
|
Used to provide a whitelist- or blacklist-style filtering of manager events before they are delivered to the AMI client application. Filters are specified using a regular expression. A specified filter is a whitelist filter unless preceded by an exclamation point.[a] |
[a] If no filters are specified, all
events that are allowed based on the | ||
As discussed in Table 20.2, “Options for [username] sections”,
the read and write options set
which manager actions and manager events a particular user has access
to. Table 20.3, “Available values for AMI user account read/write
options” shows the available permission
values that can be specified for these options.
Table 20.3. Available values for AMI user account read/write options
| Permission identifier | read | write |
|---|---|---|
all
| Shorthand way of specifying that this user should have access to all available privilege options. | Grants user all privilege options. |
system
| Allows user to receive general system information, such as notifications of configuration reloads. | Allows user to perform system management commands such as Restart, Reload, or Shutdown. |
call
| Allows user to receive events about channels on the system. | Allows user to set information on channels. |
log
| Gives user access to logging information.[a] | read-only |
verbose
| Gives user access to verbose logging information.[b] | read-only |
agent
| Gives user access to events regarding the status
of agents from the app_queue and
chan_agent modules. | Enables user to perform actions for managing and retrieving the status of queues and agents. |
user
| Grants access to user-defined events, as well as events about Jabber/XMPP users. | Lets user perform the UserEvent
manager action, which
provides the ability to request that Asterisk generate a user-defined
event.[c] |
config
| write-only | Allows user to retrieve, update, and reload configuration files. |
command
| write-only | Allows user to execute Asterisk CLI commands over the AMI. |
dtmf
| Allows user to receive events generated as DTMF passes through the Asterisk core.[d] | read-only |
reporting
| Gives user access to call-quality events, such as jitterbuffer statistics or RTCP reports. | Enables user to execute a range of actions to retrieve statistics and status information from across the system. |
cdr
| Grants user access to CDR records reported by the
cdr_manager module. | read-only |
dialplan
| Allows user to receive events generated when variables are set or new extensions are created. | read-only |
originate
| write-only | Allows user to execute the Originate
action, which allows an AMI client to request that
Asterisk create a new call. |
agi
| Allows user to receive events generated when AGI commands are processed. | Enables user to perform actions for managing channels that are running AGI in its asynchronous mode. AGI is discussed in more detail in Chapter 21, Asterisk Gateway Interface (AGI). |
cc
| Allows user to receive events related to Call Completion Supplementary Services (CCSS). | read-only |
aoc
| Lets user see Advice of Charge events generated as AOC events are received. | Allows user to execute the AOCMessage
manager action, for sending out AOC messages. |
[a] This level has been defined, but it is not currently used anywhere in Asterisk. [b] This level has been defined, but it is not currently used anywhere in Asterisk. [c] The [d] DTMF events will not be generated in a bridged call between two channels unless generic bridging in the Asterisk core is being used. For example, if the DTMF is being transmitted with the media stream and the media stream is flowing directly between the two endpoints, Asterisk will not be able to report the DTMF events. | ||
As we’ve seen, the Asterisk Manager Interface can be
accessed over HTTP as well as TCP. To make that work, a very simple HTTP
server is embedded in Asterisk. All of the options relevant to the AMI
go in the [general] section of
/etc/asterisk/http.conf.
Enabling access to the AMI over HTTP
requires both /etc/asterisk/manager.conf and
/etc/asterisk/http.conf.
The AMI must be enabled in manager.conf, with
the enabled option set to yes,
and the manager.conf option
webenabled must be set to yes
to allow access over HTTP. Finally, the enabled
option in http.conf must be set to
yes to turn on the HTTP server itself.
The available options are listed in Table 20.4, “Options in the http.conf [general] section”:
Table 20.4. Options in the http.conf [general] section
| Option | Value/Example | Description |
|---|---|---|
enabled
|
yes
| Enables the built-in HTTP server. The default is
no. |
bindport
|
8088
| Sets the port number to listen on for HTTP connections.
The default is 8088. |
bindaddr
|
127.0.0.1
| Sets the address to listen on for HTTP connections. The
default is to listen on all addresses
(0.0.0.0). However, it is highly recommended
to set this to 127.0.0.1. |
tlsenable
|
yes
| Enables listening for HTTPS connections. The default is
no. It is highly recommended that you only
use HTTPS if you wish to expose HTTP connectivity outside of the
local machine.[a] |
tlsbindport
|
8089
| Sets the port to listen on for HTTPS connections. The
default is 8089. |
tlsbindaddr
|
0.0.0.0
| Sets the address to listen on for TLS-enabled AMI
connections. The default is to listen on all addresses
(0.0.0.0). |
tlscertfile
|
/var/lib/
asterisk
/keys/
asterisk
.pem
| Sets the path to the HTTPS server certificate. This is
required if tlsenable is set to
yes. |
tlsprivatekey
|
/var/lib/
asterisk
/keys/
private
.pem
| Sets the path to the HTTPS private key. If this is not
specified, the tlscertfile will be checked to
see if it also contains the private key. |
tlscipher
|
<cipher string>
| Specifies a list of ciphers for OpenSSL to use. Setting this is optional. To see a list of available ciphers, run openssl ciphers -v at the command line. |
[a] The OpenSSL development package must
be installed for Asterisk to be able to use encryption. On
Ubuntu, the package is | ||