Manager, i.e. AMI (Asterisk Manager Interface), is an interface that enables remote management of the Asterisk telephone system. This is a very important element that allows for automation and remote control of the system. One could even go so far as to say that it is a kind of CTI (Computer Telephony Integration), i.e. a service enabling the integration of the telephone system with other external services and systems.
The Manager interface in Asterisk is available via TCP port 5038 (default) and supports the AMI (Asterisk Manager Interface) protocol. Thanks to this, the API can be operated from various programming languages such as PHP, Python, Java, Ruby, Perl and many others.
In the post below, we will show you how to use this tool in practice, also on various popular telecommunications platforms such as FreePBX
Table of Contents
1) Manager Configuration
The manager does not need to be installed separately after the standard Asterisk installation. AMI is an embedded programming interface available with the main Asterisk suite. This means it is available with the standard Asterisk installation and configuration.
AMI is supported by appropriate configuration of the
manager.conf file, which defines access parameters, permissions and behavior for remote connections to the AMI interface. In this file you can configure users, passwords, access to various commands and operations.
After proper configuration, the AMI will be ready for use, and you will be able to use its interface with external applications that can connect to Asterisk via the appropriate protocol and port.
Let’s now configure our manager.conf file using our favorite nano notebook. Full documentation can be found at github repository
nano /etc/asterisk/manager.conf
Here are the most important parameters in the
manager.conf file and their meaning:
- enabled: Specifies whether the AMI should be enabled (
yes) or disabled (no). If disabled, external applications will not be able to connect to the AMI. - webenabled: Specifies whether the AMI is accessible via HTTP. Setting to
yesallows communication via HTTP. - port: Specifies the port number on which the AMI will listen.
- bindaddr: Specifies the IP address on which the AMI will listen. You can set it to
0.0.0.0to listen on all available network interfaces. - displayconnects: Specifies whether connection information will be displayed in the Asterisk system console. Setting it to
yeswill display AMI connection notifications in the console. - secret: This is the password that external applications use to authenticate to the AMI. Each application must know this password to connect.
- deny: Specifies IP addresses that are prohibited for connecting to the AMI.
- permit: Specifies the IP addresses that are allowed to connect to the AMI. You can use
permitanddenyto define access policies. - read: Specifies a list of permissions for read operations on the AMI. The value can be
all,system,call,log,verbose,agent,user,config,command,dtmf,report,originate,cdr,accounting. - write: Specifies a list of permissions for AMI write operations. Like
read, values can be different types of operations. - writetimeout: Specifies the time to wait for confirmation of a write operation. After this time, the save operation will be canceled.
1a) Basic options – [general] section
In the example below, we have a
[general] section in which we will define global settings for all Manager users. They may be overwritten in individual user sections.
[general]
enabled = yes
webenabled = no
bindaddr = 0.0.0.0
port = 5038
displayconnects = yes
tlsenable = no
The
enabled = yes option make the AMI interface to be enabled. The bindaddr = 0.0.0.0 option tells us that it will be available to all IP addresses on the default port 5038 (port = 5038 option). Additionally, we want connection information to be displayed in Asterisk system console (option displayconnects = yes), but we do not want the interface to be available via the www (option webenabled = no) and we decide that the Manager will not support connections using TLS and all connections will be unencrypted. (option tlsenable = no). It's worth noting that setting "bindaddr = 0.0.0.0" may be unsafe if the Manager interface is not properly secured with a password or IP addresses that have access. In this case, malicious actors can gain unauthorized access to the interface and make changes to the system.
1b) Encryption connection with TLS – [general] section
[general]
tlsenable = yes
tlsbindaddr=0.0.0.0:5039
tlscertfile=/tmp/asterisk.pem
tlsprivatekey=/tmp/private.pem
Setting
"tlsenable = yes" means that the Manager interface will support encrypted connections. This requires setting a few additional parameters.
The "tlsbindaddr=0.0.0.0:5039" setting indicates that the Manager interface will listen for encrypted connections on port 5039 on all IP addresses where the server it is running is accessible Asterisk system.
The tlscertfile option indicates where the system should look for the certificate, and the tlsprivatekey option indicates where to look for the private key. If the second option is not available, the system will look for the private key in the certificate file. For more information on how to create certificates, see this post.
1c) Additional options – [general] section
[general]
allowmultiplelogin = no
debug = on
The
allowmultiplelogin = no option will not allow multiple connections to the Manager using the same login (the default setting is enabled – yes).
The debug = on option enables debugging mode for the Manager API. Asterisk then prints additional diagnostic information about the interface’s activities. This option may be helpful if you experience any connection or operation problems with the Manager API. (default is off – off) 2) Manager configuration – user sections
The next sections in the
manager.conf file will define the users. Here are two examples:
[user]
secret = StrongPa$$w0rd1
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
read = all
write = all
writetimeout = 1000
displayconnects = no
[remote_user]
secret = StrongPa$$w0rd2
read = system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan
write = system,call,agent,user,config,command,reporting,originate,message
We have two users defined:
user and remote_user with passwords provided in the secret option.
For the user user, we overwrite the permissions to connect from any IP address that we have allowed in the general section. The deny = 0.0.0.0/0.0.0.0 option blocks connection from any IP address, then the permit = 127.0.0.1/255.255.255.255 option allows the user to only connect from the local IP address, which is the address where asterisk is currently running (localhost). The writetimeout = 1000 option allows us to extend the inactivity time on a connected Asterisk session with a user. We give it in milliseconds. This prevents disconnection on slower connections. The displayconnects = no option overrides the default yes value defined in the general section. The read = all and write = all options allow this user to receive all system events and send all available commands to the Asterisk system.
The remote_user user has global permissions of the general section and additionally has specific rights to write and read information. We will explain their meaning in the next section. In the Asterisk console we can check the status of connected users. If we have only made changes now, we explain how to reload the configuration later in the post. Let’s show existing users first:
manager show users
Next, let’s look at the configuration of one of our users
manager show user remote_user
3) List of Manager permissions
For the AMI read and write options, we have the following options:
read = all,system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan,agi,cc,aoc,test,security
write = all, system,call,agent,user,config,command,reporting,originate,message,agi,aoc,test,message
The meaning of each information class is as follows:
all - all events described below and even those not listed here are available.
system - general system information and the ability to run system management commands such as Shutdown, Restart and Reload. This class also includes the ability to manipulate the dialplan using commands such as DialplanExtensionAdd and DialplanExtensionRemove.
call - Information about channels and the ability to set information in the current channel.
log - logging information. (Defined but not yet used).
verbose - full information. (Defined but not yet used).
agent - Information about queues and agents and the ability to add queues and agents to queues
user - permission to send and receive UserEvents.
config - ability to save and read configuration files.
command - ability to send commands available in the Asterisk console
dtmf - receiving DTMF events
reporting - ability to receive information about the system status
cdr - reading events related to CDRs
dialplan - receiving NewExten and VarSet events.
originate - permission to create new connections
agi - execution of AGI commands
cc - receiving Call Completion events
aoc - sending and receiving AOC (Advice Of Charge) messages.
test - Ability to receive and send TestEvent type notifications to the Asterisk Test Suite module. Will only work if the TEST_FRAMEWORK compiler flag is defined
security - reading security events
message - permission to send text messages
4) Managing the Manager service
Each change to the
manager.conf configuration file requires reloading the module from the Asterisk console.
asterisk -rx "manager reload"
We can also display the current Manager configuration.
asterisk -rx "manager show settings"
Global Settings:
----------------
Manager (AMI): Yes
Web Manager (AMI/HTTP): No
TCP Bindaddress: 0.0.0.0:5038
HTTP Timeout (seconds): 60
TLS Enable: No
TLS Bindaddress: Disabled
TLS Certfile: asterisk.pem
TLS Privatekey:
TLS Cipher:
Allow multiple login: Yes
Display connects: Yes
Timestamp events: No
Channel vars:
Debug: No
The list of available commands is as follows. (for convenience, we will enter the Asterisk console)
asterisk -r
manager show commands
pbx*CLI> manager show commands
Action Synopsis
------ --------
AbsoluteTimeout Set absolute timeout.
AgentLogoff Sets an agent as no longer logged
Agents Lists agents and their status.
AGI Add an AGI command to execute by
AOCMessage Generate an Advice of Charge mess
Atxfer Attended transfer.
BlindTransfer Blind transfer channel(s) to the
Bridge Bridge two channels already in th
BridgeDestroy Destroy a bridge.
BridgeInfo Get information about a bridge.
BridgeKick Kick a channel from a bridge.
BridgeList Get a list of bridges in the syst
BridgeTechnologyList List available bridging technolog
BridgeTechnologySuspend Suspend a bridging technology.
BridgeTechnologyUnsuspend Unsuspend a bridging technology.
CancelAtxfer Cancel an attended transfer.
Challenge Generate Challenge for MD5 Auth.
ChangeMonitor Change monitoring filename of a c
Command Execute Asterisk CLI Command.
ConfbridgeKick Kick a Confbridge user.
ConfbridgeList List participants in a conference
ConfbridgeListRooms List active conferences.
ConfbridgeLock Lock a Confbridge conference.
ConfbridgeMute Mute a Confbridge user.
ConfbridgeSetSingleVideoSrc Set a conference user as the sing
ConfbridgeStartRecord Start recording a Confbridge conf
ConfbridgeStopRecord Stop recording a Confbridge confe
ConfbridgeUnlock Unlock a Confbridge conference.
ConfbridgeUnmute Unmute a Confbridge user.
ControlPlayback Control the playback of a file be
CoreSettings Show PBX core settings (version e
CoreShowChannels List currently active channels.
CoreStatus Show PBX core status variables.
CreateConfig Creates an empty file in the conf
DBDel Delete DB entry.
DBDelTree Delete DB Tree.
DBGet Get DB Entry.
DBGetTree Get DB entries, optionally at a p
DBPut Put DB entry.
DeviceStateList List the current known device sta
DialplanExtensionAdd Add an extension to the dialplan
DialplanExtensionRemove Remove an extension from the dial
Events Control Event Flow.
ExtensionState Check Extension Status.
ExtensionStateList List the current known extension
FAXSession Responds with a detailed descript
FAXSessions Lists active FAX sessions
FAXStats Responds with fax statistics
Filter Dynamically add filters for the c
GetConfig Retrieve configuration.
GetConfigJSON Retrieve configuration (JSON form
Getvar Gets a channel variable or functi
Hangup Hangup channel.
IAXnetstats Show IAX Netstats.
IAXpeerlist List IAX Peers.
IAXpeers List IAX peers.
IAXregistry Show IAX registrations.
ListCategories List categories in configuration
ListCommands List available manager commands.
LocalOptimizeAway Optimize away a local channel whe
LoggerRotate Reload and rotate the Asterisk lo
Login Login Manager.
Logoff Logoff Manager.
MailboxCount Check Mailbox Message Count.
MailboxStatus Check mailbox.
MessageSend Send an out of call message to an
MixMonitor Record a call and mix the audio d
MixMonitorMute Mute / unMute a Mixmonitor record
ModuleCheck Check if module is loaded.
ModuleLoad Module management.
Monitor Monitor a channel.
MuteAudio Mute an audio stream.
Originate Originate a call.
Park Park a channel.
ParkedCalls List parked calls.
Parkinglots Get a list of parking lots
PauseMonitor Pause monitoring of a channel.
Ping Keepalive command.
PJSIPNotify Send a NOTIFY to either an endpoi
PJSIPQualify Qualify a chan_pjsip endpoint.
PJSIPRegister Register an outbound registration
PJSIPShowAors Lists PJSIP AORs.
PJSIPShowAuths Lists PJSIP Auths.
PJSIPShowContacts Lists PJSIP Contacts.
PJSIPShowEndpoint Detail listing of an endpoint and
PJSIPShowEndpoints Lists PJSIP endpoints.
PJSIPShowRegistrationInboundContactStatuses Lists ContactStatuses for PJSIP i
PJSIPShowRegistrationsInbound Lists PJSIP inbound registrations
PJSIPShowRegistrationsOutbound Lists PJSIP outbound registration
PJSIPShowResourceLists Displays settings for configured
PJSIPShowSubscriptionsInbound Lists subscriptions.
PJSIPShowSubscriptionsOutbound Lists subscriptions.
PJSIPUnregister Unregister an outbound registrati
PlayDTMF Play DTMF signal on a specific ch
PlayMF Play MF digit on a specific chann
PresenceState Check Presence State
PresenceStateList List the current known presence s
QueueAdd Add interface to queue.
QueueChangePriorityCaller Change priority of a caller on qu
QueueLog Adds custom entry in queue_log.
QueueMemberRingInUse Set the ringinuse value for a que
QueuePause Makes a queue member temporarily
QueuePenalty Set the penalty for a queue membe
QueueReload Reload a queue, queues, or any su
QueueRemove Remove interface from queue.
QueueReset Reset queue statistics.
QueueRule Queue Rules.
QueueStatus Show queue status.
QueueSummary Show queue summary.
QueueWithdrawCaller Request to withdraw a caller from
Redirect Redirect (transfer) a call.
Reload Send a reload event.
SendText Sends a text message to channel.
Setvar Sets a channel variable or functi
ShowDialPlan Show dialplan contexts and extens
SIPnotify Send a SIP notify.
SIPpeers List SIP peers (text format).
SIPpeerstatus Show the status of one or all of
SIPqualifypeer Qualify SIP peers.
SIPshowpeer show SIP peer (text format).
SIPshowregistry Show SIP registrations (text form
SKINNYdevices List SKINNY devices (text format)
SKINNYlines List SKINNY lines (text format).
SKINNYshowdevice Show SKINNY device (text format).
SKINNYshowline Show SKINNY line (text format).
SorceryMemoryCacheExpire Expire (remove) ALL objects from
SorceryMemoryCacheExpireObject Expire (remove) an object from a
SorceryMemoryCachePopulate Expire all objects from a memory
SorceryMemoryCacheStale Marks ALL objects in a sorcery me
SorceryMemoryCacheStaleObject Mark an object in a sorcery memor
Status List channel status.
StopMixMonitor Stop recording a call through Mix
StopMonitor Stop monitoring a channel.
UnpauseMonitor Unpause monitoring of a channel.
UpdateConfig Update basic configuration.
UserEvent Send an arbitrary event.
VoicemailRefresh Tell Asterisk to poll mailboxes f
VoicemailUsersList List All Voicemail User Informati
VoicemailUserStatus Show the status of given voicemai
WaitEvent Wait for an event to occur.
We will receive dozens of commands that we can use in practice. The syntax of a specific command, for example
ping, can be obtained by running the example command below:
manager show command ping
[Syntax]
Action: Ping
[ActionID:] <value>
[Synopsis]
Keepalive command.
[Description]
A 'Ping' action will ellicit a 'Pong' response. Used to keep the manager
connection open.
[Arguments]
ActionID
ActionID for this transaction. Will be returned.
[See Also]
Not available
[Privilege]
<none>
[List Responses]
None
[Final Response]
None
After configuring the entire service, we will be able to see AMI queries in the console.
If you establish a connection to listen to PBX events, it is worth considering adding additional filters in
manager.conf to slightly limit the amount of information received.
;eventfilter=Event: Newchannel
;eventfilter=Channel: (PJ)?SIP/(james|jim|john)-
;eventfilter=!Channel: DAHDI/
You can apply the above filters globally or to selected users. For more information, please refer to the documentation cited at the beginning.
5) Manager configuration in FreePBX
FreePBX does not give us direct access to the headquarters, but in the control panel on the website there are options for configuring and managing the Manager. Log in to the freePBX management console and select Settings -> AsteriskManagerUsers
Here we can edit existing users and their permissions or add a new one. We will do this by clicking + Add Manager. We will get a screen as below, where we can set the parameters that we previously defined in the manager.conf file
In the Permissions tab, we will set read and write permissions for a given user.
Of course, after setting all the parameters, we click the Apply Config button and our manager is configured in FreePBX
In the following posts we will discuss how to compile and execute AMI queries using PHP, Node.JS and similar…
If you would like tomonitor everything that is happening on your PBX, try our proprietary software VOIPERO
Installation and configuration takes a few minutes and the system is currently availabletotally free
Read what our VOIPERO system can do in terms of live monitoring and reporting of Asterisk-based VoIP systems.
The AMI manager interface just described above is mainly used in Voipero.
