3. Das Manager-Interface (AMI)
Das Manager-Interface aktiviert man, indem man in der manager.conf im Abschnitt [general] den Parameter enabled=yes setzt.
Achtung
Das sollte man nie auf einem Server mit öffentlichem Zugang machen, außer man schützt sich zusätzlich durch iptables, ipfw oder eine andere Firewall oder einen SSH-Tunnel!
Ganz unten legen wir uns einen Benutzer-Eintrag mit dem Namen admin an:
[admin]
secret = geheim
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
read = all,system,call,log,verbose,command,agent,user,config
write = all,system,call,log,verbose,command,agent,user,config
Die Optionen nach read und write geben an, für welche Befehlsklassen wir dem User Rechte geben.[124]
Achtung
Diese großzügige Rechtevergabe dient nur zum Testen! Mit dem Recht command kann der User z.B. Asterisk stoppen. Seit 1.4 ist es sogar möglich, durch das AMI den Dialplan zu verändern und dann evtl. mit System() auf der Shell Befehle mit root-Rechten auszuführen!
Nach einem Restart von Asterisk können wir uns auf Port 5038 mit dem AMI verbinden, was wir auf der Shell mit telnet[125]ausprobieren:
$ telnet 127.0.0.1 5038
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Asterisk Call Manager/1.0
Man kann hier von Hand Befehle (die meist aus mehreren Zeilen bestehen) eintippen, z.B.:
Action: Login
ActionID: 1
Username: admin
Secret: geheim
Anmerkung
Alle Befehls-Pakete werden wurch zwei Returns abgeschlossen.
Antwort:
Response: Success
ActionID: 1
Message: Authentication accepted
Die primäre Verwendung liegt aber ganz klar im automatisierten Zugriff durch Skripte.
Anmerkung
Die Manager-API ist nicht unbedingt dafür berühmt, viele gleichzeitige Verbindungen handhaben zu können (auch wenn sich das in der Version 1.4 stark verbessert hat). In so einer Last-Situation könnte man über den Einsatz eines speziellen Proxys wie den „Simple Asterisk Manager Proxy“[126] (ein Perl-Skript) nachdenken, der viele Verbindungen entgegennimmt und zu einer bündelt - für die zugreifenden Skripte völlig transparent. Für die folgenden „Spielereien“ ist das aber unnötig.
Nach erfolgreicher Authentifizierung können in beiden Richtung Pakete gesendet werden. Die Art des Pakets wird immer von der ersten Zeile darin bestimmt. Der Client sendet Action-Pakete, der Server antwortet mit Response oder kann auch von sich aus Event-Pakete schicken. Die Reihenfolge der Zeilen in einem Paket ist ansonsten aber irrelevant. Zeilen werden durch CR LF[127] beendet, das ganze Paket durch ein weiteres CR LF. Normalerweise sendet der Client in jeder Action ein ActionID-Feld mit beliebigem, möglichst eindeutigem, Inhalt[128], das der Server so in seine Response übernimmt, damit sich die Antworten bei Überschneidungen zuordnen lassen.
Der Server sendet Event-Pakete, um den Client über verschiedene Ereignisse zu informieren. Es gibt auch Ereignisse, die von einer Action des Clients ausgelöst werden. Dann sendet der Server ein Response: Follows gefolgt von den Events (die dann ebenfalls die ActionID beinhalten) und ein abschließendes Event (normalerweise AktionsnameComplete).
Wenn Ihr Client keine Events benötigt, kann er direkt im ersten Authentifizierungs-Paket den Parameter Events: off senden, um dann nur Antworten auf von ihm gesendete Actions zu erhalten.
Die Liste der verfügbaren Befehle erhält man im CLI mit show manager commands (bzw. manager show commands), Informationen über einen Befehl mit show manager command Befehlsname (bzw. manager show command Befehlsname):
mos-eisley*CLI> manager show commands
Action Privilege Synopsis
------ --------- --------
AbsoluteTimeout call,all Set Absolute Timeout
AgentCallbackLo agent,all Sets an agent as logged in by callback
AgentLogoff agent,all Sets an agent as no longer logged in
Agents agent,all Lists agents and their status
ChangeMonitor call,all Change monitoring filename of a channel
Command command,all Execute Asterisk CLI Command
DBGet system,all Get DB Entry
DBPut system,all Put DB Entry
Events <none> Control Event Flow
ExtensionState call,all Check Extension Status
GetConfig config,all Retrieve configuration
Getvar call,all Gets a Channel Variable
Hangup call,all Hangup Channel
IAXnetstats <none> Show IAX Netstats
IAXpeers <none> List IAX Peers
ListCommands <none> List available manager commands
Logoff <none> Logoff Manager
MailboxCount call,all Check Mailbox Message Count
MailboxStatus call,all Check Mailbox
Monitor call,all Monitor a channel
Originate call,all Originate Call
Park call,all Park a channel
ParkedCalls <none> List parked calls
PauseMonitor call,all Pause monitoring of a channel
Ping <none> Keepalive command
PlayDTMF call,all Play DTMF signal on a specific channel.
QueueAdd agent,all Add interface to queue.
QueuePause agent,all Makes a queue member temporarily unavailable
QueueRemove agent,all Remove interface from queue.
Queues <none> Queues
QueueStatus <none> Queue Status
Redirect call,all Redirect (transfer) a call
SetCDRUserField call,all Set the CDR UserField
Setvar call,all Set Channel Variable
SIPpeers system,all List SIP peers (text format)
SIPshowpeer system,all Show SIP peer (text format)
Status call,all Lists channel status
StopMonitor call,all Stop monitoring a channel
UnpauseMonitor call,all Unpause monitoring of a channel
UpdateConfig config,all Update basic configuration
UserEvent user,all Send an arbitrary event
WaitEvent <none> Wait for an event to occur
Diese Befehle sind fast immer gleichlautend mit einer entsprechenden Dialplan-Applikation - neu ist vor allem die Action Originate, mit der man einen ausgehenden Anruf veranlassen kann, und Command, was einen Befehl direkt auf dem CLI ausführt. Da wir unserem User admin alle Rechte gegeben haben (s.o.), darf er alle Befehle ausführen. Wie man einen Befehl benutzt, erfährt man so:
mos-eisley*CLI> manager show command Command
Action: Command
Synopsis: Execute Asterisk CLI Command
Privilege: command,a
Description: Run a CLI command.
Variables: (Names marked with * are required)
*Command: Asterisk CLI command to run
ActionID: Optional Action id for message matching.Die von Asterisk verschickten Events sind bisher so gut wie undokumentiert. Auf http://www.voip-info.org/wiki/view/asterisk+manager+events findet sich eine zusammengesammelte Liste mit spärlichen Hinweisen. Ein paar Erklärungen kann man auf http://asterisk-java.sourceforge.net/apidocs/net/sf/asterisk/manager/event/package-frame.html nachlesen[129].
