Szukaj

Konfiguracja AMI (Asterisk Manager Interface)

Konfiguracja AMI (Asterisk Manager Interface)

Manager czyli AMI (Asterisk Manager Interface) to interfejs, który umożliwia zdalne zarządzanie systemem telefonicznym Asterisk. Jest to bardzo ważny element, który pozwala na automatyzację i zdalną kontrolę nad systemem. Można by nawet pokusić sie o twierdzenie, że jest to swego rodzaju CTI (Computer Telephony Integration), czyli usługa umozliwiająca integrację systemu telefonicznego z innymi zewnętrznymi usługami i systemami.

Interfejs Manager w Asterisku jest dostępny przez port TCP 5038 (domyślnie) i obsługuje protokół AMI (Asterisk Manager Interface). Dzięki temu API można obsługiwać z różnych języków programowania, takich jak PHP, Python, Java, Ruby, Perl i wiele innych.

W poniższym poście pokażemy jak korzystać z tego narzędzia w praktyce, również na różnych popularnych platformach telekomunikacyjnych jak FreePBX

Spis treści

1) Konfiguracja Managera

Managera nie trzeba osobno instalować po standardowej instalacji Asteriska. AMI jest wbudowanym interfejsem programistycznym dostępnym wraz z głównym pakietem Asteriska. To oznacza, że jest dostępny wraz z standardową instalacją i konfiguracją Asteriska.

AMI jest obsługiwany poprzez odpowiednią konfigurację pliku manager.conf, który definiuje parametry dostępu, uprawnienia i zachowanie dla połączeń zdalnych do interfejsu AMI. W tym pliku można skonfigurować użytkowników, hasła, dostęp do różnych komend i operacji.

Po poprawnej konfiguracji, AMI będzie gotowy do użycia, i będzie można korzystać z jego interfejsu za pomocą aplikacji zewnętrznych, które mogą łączyć się z Asteriskiem poprzez odpowiedni protokół i port.

Skonfigurujmy teraz nasz plik manager.conf za pomocą naszego ulubionego notatnika nano. Pełna dokumentacja znajduje się w repozytoirum github

				
					nano /etc/asterisk/manager.conf
				
			

Oto najważniejsze parametry w pliku manager.conf wraz z ich znaczeniem:

  1. enabled: Określa, czy interfejs AMI ma być włączony (yes) lub wyłączony (no). Jeśli jest wyłączony, aplikacje zewnętrzne nie będą mogły łączyć się z interfejsem AMI.

  2. webenabled: Określa, czy interfejs AMI jest dostępny przez interfejs HTTP. Ustawienie na yes pozwala na komunikację przez HTTP.

  3. port: Określa numer portu, na którym będzie nasłuchiwać interfejs AMI.

  4. bindaddr: Określa adres IP, na którym będzie nasłuchiwać interfejs AMI. Możesz go ustawić na 0.0.0.0, aby słuchał na wszystkich dostępnych interfejsach sieciowych.

  5. displayconnects: Określa, czy informacje o połączeniach będą wyświetlane w konsoli systemowej Asteriska. Ustawienie na yes wyświetli powiadomienia o połączeniach AMI w konsoli.

  6. secret: Jest to hasło używane przez aplikacje zewnętrzne do uwierzytelniania się w interfejsie AMI. Każda aplikacja musi znać to hasło, aby się połączyć.

  7. deny: Określa adresy IP, które są zabronione w celu łączenia się z interfejsem AMI.

  8. permit: Określa adresy IP, które są dozwolone w celu łączenia się z interfejsem AMI. Możesz używać permit i deny do definiowania polityki dostępu.

  9. read: Określa listę uprawnień do operacji odczytu w interfejsie AMI. Wartością może być all, system, call, log, verbose, agent, user, config, command, dtmf, report, originate, cdr, accounting.

  10. write: Określa listę uprawnień do operacji zapisu w interfejsie AMI. Podobnie jak read, wartościami mogą być różne typy operacji.

  11. writetimeout: Określa czas oczekiwania na potwierdzenie operacji zapisu. Po upływie tego czasu operacja zapisu zostanie anulowana.

Przeanalizujmy przykładową konfigurację dla dwóch różnych użytkowników Managera

1a) Opcje podstawowe – sekcja [general]

W poniższym przykładzie mamy sekcję [general] w której zdefiniujemy globalne ustawienia dla wszystkich użytkowników Managera. Mogą one zostać nadpisane w sekcjach poszczególnych użytkowników.

				
					[general]
enabled = yes
webenabled = no
bindaddr = 0.0.0.0
port = 5038
displayconnects = yes
tlsenable = no


				
			

Opcją enabled = yes zezwalamy na włączenie interfejsu AMI. Opcja  bindaddr = 0.0.0.0 mówi nam, że będzie on dostępny dla wszystkich adresów IP na domyślnym porcie 5038 (opcja port = 5038 ) Dodatkowo chcemy aby informacje o połączeniach były wyświetlane w konsoli systemowej Asteriska  (opcja displayconnects = yes), ale nie chcemy aby interfejs był dostępny przez www (opcja webenabled = no) oraz decydujemy, że Manager nie będzie obsługiwał połączeń z wykorzystaniem TLS, a wszystkie połączenia będą nieszyfrowane. (opcja tlsenable = no). 

Warto zauważyć, że ustawienie "bindaddr = 0.0.0.0" może być niebezpieczne w przypadku, gdy interfejs Manager nie jest odpowiednio zabezpieczony hasłem lub adresami IP, które mają dostęp. W takim przypadku, złośliwe osoby mogą uzyskać nieautoryzowany dostęp do interfejsu i wprowadzać zmiany w systemie.

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

Masz pytania lub potrzebujesz oferty?

Skontaktuj się z naszym doradcą.

Popularne wpisy

Powiązane posty

Projekt wystartował!

Monitorowanie i raportowanie Twojego serwera VoIP