Das Manager-Interface aktiviert man, indem man in der manager.conf im Abschnitt [general] den Parameter enabled=yes setzt.

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]

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

Antwort:

Response: Success
ActionID: 1
Message: Authentication accepted

Die primäre Verwendung liegt aber ganz klar im automatisierten Zugriff durch Skripte.

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 callba
ck                 
  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 chan
nel                
  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 chann
el.                
  QueueAdd         agent,all        Add interface to queue.             
                   
  QueuePause       agent,all        Makes a queue member temporarily una
vailable           
  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].