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:
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.webenabled: Określa, czy interfejs AMI jest dostępny przez interfejs HTTP. Ustawienie na
yespozwala na komunikację przez HTTP.port: Określa numer portu, na którym będzie nasłuchiwać interfejs AMI.
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.displayconnects: Określa, czy informacje o połączeniach będą wyświetlane w konsoli systemowej Asteriska. Ustawienie na
yeswyświetli powiadomienia o połączeniach AMI w konsoli.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ć.
deny: Określa adresy IP, które są zabronione w celu łączenia się z interfejsem AMI.
permit: Określa adresy IP, które są dozwolone w celu łączenia się z interfejsem AMI. Możesz używać
permitidenydo definiowania polityki dostępu.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.write: Określa listę uprawnień do operacji zapisu w interfejsie AMI. Podobnie jak
read, wartościami mogą być różne typy operacji.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
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
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.
