Das Asterisk Buch von Stefan Wintermeyer

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 Benutzereintrag 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.^[127]

	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^[128]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 durch 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“[129] (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^[130] 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^[131], 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 zusammengestellte 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^[132].