Manager w Asterisk 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.
Manager w Asterisk umożliwia administratorom i programistom korzystanie z różnych poleceń i funkcji, które pozwalają na modyfikowanie konfiguracji systemu, wykonywanie i monitorowanie połączeń, zarządzanie nagrywaniem rozmów, kontrolowanie kolejek oczekujących i wiele innych.
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.
Spis treści
1) Konfiguracja Managera – sekcja [general]
/etc/asterisk/manager.conf. Pełna dokumentacja znajduje się w repozytoirum github. Przyjrzyjmy się najpierw sekcji general.
nano /etc/asterisk/manager.conf
1a) Opcje podstawowe
Przykładowa konfiguracja mogła by wyglądać następująco:
[general]
enabled = yes
webenabled = no
bindaddr = 0.0.0.0
port = 5038
displayconnects = yes
tlsenable = no
"enabled" określa, czy interfejs Manager jest włączony czy wyłączony. Ustawienie "enabled=yes" oznacza, że interfejs Manager jest włączony i będzie działał. Natomiast ustawienie opcji "webenabled = no" oznacza, że interfejs nie będzie dostepny przez www.
Opcja "bindaddr" określa adres IP, na którym interfejs Manager będzie nasłuchiwał połączeń. Wartość "bindaddr = 0.0.0.0" oznacza, że interfejs Manager będzie nasłuchiwał na wszystkich adresach IP, na których jest dostępny serwer, na którym działa Asterisk. Innymi słowy, ustawienie "bindaddr = 0.0.0.0" oznacza, że interfejs Manager będzie dostępny z każdej maszyny w sieci, która może się połączyć z serwerem Asterisk, na którym działa interfejs Manager. Domyślny port nasłuchiwania to 5038. 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.
"displayconnects = yes" oznacza, że interfejs Manager będzie wyświetlał informacje o połączeniach klientów, takie jak adres IP i nazwa klienta, na konsoli lub w logach systemowych. Dzięki temu administrator może śledzić, kto się łączy z interfejsem Manager.
Ustawienie "tlsenable = no" oznacza, że interfejs Manager nie będzie obsługiwał połączeń z wykorzystaniem TLS, a wszystkie połączenia będą nieszyfrowane. 1b) Szyfrowanie połączenie z TLS
[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
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 = qwerty12345
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$$w0rd
deny = 0.0.0.0/0.0.0.0
permit = 1.1.1.1/255.255.255.255
read = reporting,user,cdr
write = user
writetimeout = 1000
Mamy zdefiniowanych dwóch użytkowników: user i remote_user z hasłami podanymi w opcji secret. 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. Dodatkowo dzięki opcji permit = 1.1.1.1/255.255.255.255 użytkownik remote_user ma możliwość zalogowania się z adresu 1.1.1.1. Ze względów bezpieczeństwa, warto najpierw wszystkich zablokować, a następnie odblokować tylko hosta lokalnego i/lub wybrane zdalne adresy IP.
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ń.
W przypadku użytkownika user opcja displayconnects = no nadpisuje domyślną wartość yes zdefiniowaną w sekcji general.
Opcja read definiuje jakie zdarzenia systemowe może odbierać dany użytkownik, a opcja write mówi o tym jakie polecenia dany użytkowik może wysyłać do systemu Asterisk.
Dostępne są 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
3) 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.
W kolejnych postach omówimy, jak zestawić i realizować zapytania do AMI za pomocą PHP, Node.JS i podobnych…
