Search

AMI (Asterisk Manager Interface) configuration

AMI (Asterisk Manager Interface) configuration

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

Spis treści

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:
  1. 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.
  2. webenabled: Specifies whether the AMI is accessible via HTTP. Setting to yes allows communication via HTTP.
  3. port: Specifies the port number on which the AMI will listen.
  4. bindaddr: Specifies the IP address on which the AMI will listen. You can set it to 0.0.0.0 to listen on all available network interfaces.
  5. displayconnects: Specifies whether connection information will be displayed in the Asterisk system console. Setting it to yes will display AMI connection notifications in the console.
  6. secret: This is the password that external applications use to authenticate to the AMI. Each application must know this password to connect.
  7. deny: Specifies IP addresses that are prohibited for connecting to the AMI.
  8. permit: Specifies the IP addresses that are allowed to connect to the AMI. You can use permit and deny to define access policies.
  9. 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.
  10. write: Specifies a list of permissions for AMI write operations. Like read, values can be different types of operations.
  11. writetimeout: Specifies the time to wait for confirmation of a write operation. After this time, the save operation will be canceled.
Let’s analyze an example configuration for two different Manager users

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) Szyfrowanie połączenie z TLS – sekcja [general]

				
					[general]
tlsenable = yes
tlsbindaddr=0.0.0.0:5039
tlscertfile=/tmp/asterisk.pem
tlsprivatekey=/tmp/private.pem
				
			

Ustawienie "tlsenable = yes" oznacza, że interfejs Manager będzie obsługiwał połączenia szyfrowane. Wymaga to ustawienia kilku dodatkowych parametrów.

Ustawienie "tlsbindaddr=0.0.0.0:5039" wskazuje, że interfejs Manager będzie nasłuchiwał połączeń szyfrowanych na porcie 5039 na wszystkich adresach IP, na których jest dostępny serwer, na którym działa system Asterisk.

Opcja tlscertfile wskazuje, gdzie system ma szukać certyfikatu, a opcja tlsprivatekey, gdzie szukać klucza prywatnego. Jeżeli nie będzie tej drugiej opcji to system będzie szukał klucza prywatnego w pliku z certyfikatem.

Więcej informacji o tym, jak utworzyć certyfikaty, znajdziesz m.in. w tym poście.​

1c) Opcje dodatkowe – sekcja [general]

				
					[general]
allowmultiplelogin = no
debug = on
				
			

Opcja allowmultiplelogin = no nie zezwoli na wielokrotne połączenia z Managerem na tym samym loginie (domyślnie ustawiona jest włączona –  yes).

Opcja debug = on włącza tryb debugowania dla Manager API. Asterisk wypisuje wtedy dodatkowe informacje diagnostyczne na temat działań interfejsu. Opcja ta może być pomocna w przypadku, gdy występują jakieś problemy z połączeniem lub operacjami na Manager API. (domyślnie jest wyłączona – off)

2) Konfiguracja Managera – sekcje uzytkowników

Kolejne sekcje w pliku manager.conf zdefiniują nam użytkowników. Oto dwa przykłady:

				
					[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

				
			

Mamy zdefiniowanych dwóch użytkowników: user i remote_user z hasłami podanymi w opcji secret

Dla użytkownika user nadpisujemy uprawnienia do połączenia z dowolnego adresu IP jakie dopuściliśmy w sekcji general. Opcja deny = 0.0.0.0/0.0.0.0 blokuje połączenie z każdego adresu IP, a następnie opcja permit = 127.0.0.1/255.255.255.255 umożliwia użytkownikowi połączenie się tylko z lokalnego adresu IP, który jest adresem na którym działa aktualnie asterisk (localhost). Opcja writetimeout = 1000 pozwala nam wydłużyć czas nieaktywności na podłączonej sesji Asteriska z użytkownikiem. Podajemy go milisekundach. Zapobiega to rozłączeniu w przypadku wolniejszych połączeń. Opcja displayconnects = no nadpisuje domyślną wartość yes zdefiniowaną w sekcji general. Opcje read = all i write = all  zezwalaja temu użytkownikowi na  odbieranie wszystkich zdarzeń systemowych i wysyłanie wszystkich dostępnych poleceń  do systemu Asterisk.

Użytkownik remote_user korzysta z globalnych uprawnień sekecji general a dodatkowo ma wyszczególniono prawa do zapisu i odczytu informacji. Ich znaczenie wyjaśnimy w kolejnej sekcji. W konsoli asteriska możemy sprawdzić status podłączonych użytkowników. Jeżeli zmian dokonaliśmy dopiero teraz to w dalszej części posta wyjaśniamy jak przeładować konfigurację. Pokażmy najpierw istniejących uzytkowników:

				
					manager show users

				
			

Następnie obejrzyjmy konfigurację jednego z naszych użytkowników

				
					manager show user remote_user

				
			

3) Lista uprawnień Managera

Dla opcji do odczytu i zapisu interfejsu AMI mamy następujące możliwości:

				
					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
				
			
Znaczenie poszczególnych klas informacji jest następujące:
				
					all      - dostępne sa   wszystkie zdarzenia opisane poniżej a nawet takie, których tutaj nie wyszczególniono.
system    - ogólne informacje o systemie i możliwość uruchamiania poleceń zarządzania systemem, takich jak Shutdown, Restart i Reload. Ta klasa obejmuje również możliwość manipulowania dialplanem za pomoca poleceń takixh jak DialplanExtensionAdd i DialplanExtensionRemove.
call      - Informacje o kanałach i możliwość ustawienia informacji w bieżącym kanale.
log       - informacje logowania. (Zdefiniowane, ale jeszcze nie używane).
verbose   - pełne informacje. (Zdefiniowane, ale jeszcze nie używane).
agent     - Informacje o kolejkach i agentach i możliwośc dodawania kolejek oraz agentów do kolejek
user      - zezwolenie na wysyłanie i otrzymywanie  UserEvent-ów.
config    - możliwośc zapisywania i odczytywania plików konfiguracyjnych.
command   - możliwośc wysyłania poleceń dostępnych w konsoli Asterisk
dtmf      - otrzymywanie zdarzeń DTMF 
reporting - możliwośc otrzymywania informacji o stanie systemu
cdr       - odczytywanie zdarzeń związanych z CDR-ami
dialplan  - odbieranie zdarzeń typu NewExten i VarSet events.
originate - zezwolenie na tworzenie nowych połączeń
agi       - wykonywanie poleceń AGI
cc        - obieranie zdarzeń typu Call Completion 
aoc       - wysyłanie i odbieranie wiadomości typu AOC (Advice Of Charge).
test      - Możliwośc odbierania i wysyłania powiadomień typu TestEvent do modułu Asterisk Test Suite.  Będzie działać tylko wtedy gdy zdefiniowana jest flaga kompilatora TEST_FRAMEWORK
security  - odczytywanie zdarzeń typu security
message   - zezwolenie na wysyłanie wiadomości tekstowych
				
			

4) Zarządzanie usługą Managera

Każda zmiana w pliku konfiguracyjnym manager.conf wymaga przeładowania modułu z poziomu konsoli Asteriska.

				
					asterisk -rx "manager reload"
				
			

Możemy też wyświetlić aktualną konfigurację Managera.

				
					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

				
			
Listę dostępnych poleceń uzyskamy następująco. (dla wygody wejdziemy w konsolę Asteriska)
				
					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.
				
			

Otrzymamy kilkadziesiąt poleceń, które możemy wykorzystać w praktyce. Składnię konkretnego polecenia, na przykład ping,  uzyskamy wywołując przykładowe polecenie poniżej:

				
					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

				
			

Po skonfigurowaniu całej usługi, będziemy mogli w konsoli zobaczyć zapytania AMI.

W przypadku zestawienia połączenia celem nasłuchiwania wydarzeń (ang. event) centrali, warto rozważyć założenie dodatkowych filtrów w manager.conf, żeby nieco ograniczyć ilość otrzymywanych informacji.

				
					;eventfilter=Event: Newchannel
;eventfilter=Channel: (PJ)?SIP/(james|jim|john)-
;eventfilter=!Channel: DAHDI/
				
			

Powyższe filtry możesz zastosować globalnie lub do wybranych użytkowników. Więcej informacji znajdziesz w dokumentacji cytowanej na początku.

5) Konfiguracja Managera we FreePBX

FreePBX nie daje nam bezpośredniego dostępu do centrali ale w panelu sterowania na stronie www są opcje umożliwiające konfigurację i zarządzanie Managerem. Zaloguj się do konsoli zarządzającej freePBX i wybierz Settings -> Asterisk Manager Users

Możemy tutaj edytować istniejących użytkowników i ich uprawnienia albo dodać nowego. My tak zrobimy klikając + Add Manager. Otrzymamy ekran jak poniżej, gdzie możemy ustawić parametry, które wcześniej definiowaliśmy w pliku manager.conf

W zakładce Permissions ustawimy uprawnienia do odczytu i zapisu dla danego użytkownika.

Oczywiście po ustawieniu wszystkich parametrów klikamy jeszcze przycisk Apply Config i mamy skonfigurowanego naszego managera we FreePBX

W kolejnych postach omówimy, jak zestawić i realizować zapytania do AMI za pomocą PHP, Node.JS i podobnych…

Jeżeli chciałbyś monitorować wszystko co dzieje się na Twojej centrali wypróbuj nasze autorskie oprogramowanie VOIPERO

Instalacja i konfiguracja zajmuje kilka minut a system jest obecnie udostępniany całkowicie za darmo.

Przeczytaj co potrafi nasz system VOIPERO w zakresie monitorowania na żywo i raportowania systemów VoIP opartych na asterisku.

Właśnie opisany powyżej interfejs managera AMI jest w głównej mierze wykorzystywany w Voipero.

Share this post

Do you have questions or you need an offer?

Contact us!

Most popular

Related Posts

We Have Launched

Monitoring & Reporting of Your VoIP Server