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

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

	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^[76]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

	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.

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“[77] (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^[78] 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^[79], 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^[80].

#!/usr/bin/expect
#
# Aufruf: ./vmcount.exp 1234@default

# der Benutzer-Zugang wie in manager.conf eingerichtet:
set username "admin"
set secret "geheim"
set host "127.0.0.1"
set port "5038"

if {[llength $argv] != 1} {
    send_user "Fehler: Geben Sie eine Mailbox an!\n"
    exit 1
}

# erstes Argument ist die abzufragende Mailbox:
set mailbox [lindex $argv 0]
send_user "Mailbox: $mailbox\n"

# Durchschleifen von stdout zum User abschalten:
log_user 0

# Verbindung zum AMI öffnen:
spawn telnet $host $port

# für den Fall, daß telnet abbricht weil keine Verbindung
# hergestellt werden kann:
expect_before eof {
    send_user "Fehler beim Verbinden.\n"
    exit 1
}

# auf die Zeichenfolge "Manager" warten und bei Erfolg
# ein Login-Paket senden:
#
expect "Manager" {
    send_user "Verbunden.\n"
    send "Action: Login\nUsername: $username\nSecret: $secret\n\n"
    # Beachten Sie, daß telnet Zeilenumbrüche (\n) automatisch
    # in CR LF (\r\n) umwandelt. Man darf hier also nicht \r\n
    # angeben.
}

# Login erfolgreich?:
#
expect {
    -re "Response:\\s*Error" {
        send_user "Login fehlgeschlagen.\n"
        exit 1
    }
    -re "Response:\\s*Success" {
        send_user "Eingeloggt.\n"
        # Anzahl der Mailbox-Nachrichten abfragen:
        send "Action: MailboxCount\nMailbox: $mailbox\n\n"
    }
}

expect {
    -re "Response:\\s*Error" {
        send_user "Abfragen der Mailbox fehlgeschlagen.\n"
        exit 1
    }
    -re "Response:\\s*Success" {}
}
expect {
    -re "NewMessages:\\s*(\[\\d]*)" {
        send_user "Neue Nachrichten: $expect_out(1,string)\n"
    }
}
expect {
    -re "OldMessages:\\s*(\[\\d]*)" {
        send_user "Alte Nachrichten: $expect_out(1,string)\n"
    }
}

# Ausloggen - nicht unbedingt nötig, aber sauber:
send "Action: Logoff\n\n"

$ ./vmcount.exp 123@default
Mailbox: 123@default
Verbunden.
Eingeloggt.
Neue Nachrichten: 0
Alte Nachrichten: 0

mos-eisley*CLI> 
  == Parsing '/etc/asterisk/manager.conf': Found
[Jan 26 20:08:09] NOTICE[10352]: manager.c:961 authenticate: 127.0.0.1 t
ried to authenticate with nonexistent user 'mark'
  == Connect attempt from '127.0.0.1' unable to authenticate
mos-eisley*CLI> 

$  php -q sLogin.php 
Login Sucessful 

Response: Error
ActionID: 1
Message: Authentication failed

mos-eisley*CLI> 
  == Parsing '/etc/asterisk/manager.conf': Found
  == Manager 'admin' logged on from 127.0.0.1
mos-eisley*CLI> 

Event: Reload
Privilege: system,all
Message: Reload Requested

Event: ChannelReload
Privilege: system,all
Channel: SIP
ReloadReason: RELOAD (Channel module reload)
Registry_Count: 0
Peer_Count: 0
User_Count: 0

#!/usr/bin/php -q
<?php
# der Parameter -q dient dazu, bei einem CGI-PHP die Ausgabe der
# Header abzuschalten

if ($argc != 2) {
    echo "Fehler: Geben Sie eine Mailbox an!\n";
    exit(1);
}
# das erste Argument nach dem Programmnamen ist die Mailbox:
$mailbox = $argv[1];
echo "Mailbox: $mailbox\n\n";

# StarAstAPI einbinden:
require_once './StarAstAPI/StarAstAPI.php';

# verbinden und einloggen:
#
$ami = new AstClientConnection();
if ($ami->Login( 'admin', 'geheim', '127.0.0.1', 5038 )) {
    $rp = $ami->GetResponse('1');
    //echo $rp->ToString();
} else {
    exit(1);
}

# folgendes Paket senden:
#     Action: MailboxCount
#     Mailbox: $mailbox
#     ActionID: 2
#
$data = new AstPacketData;
$data->AddKVPair( 'Action'  , 'MailboxCount' );
$data->AddKVPair( 'Mailbox' , $mailbox );
$data->AddKVPair( 'ActionID', '2' );
$packet = new AstPacket;
$packet->SetAstPacketType( 'Action' );
$packet->SetAstPacketData( $data );
$ami->SendPacket( $packet );

# Antwort-Paket mit ActionID 2 lesen:
#
$rPacket = $ami->GetResponse('2');
//echo $rp->ToString();
$rData = $rPacket->GetAstPacketData();
$r = $rData->GetAll();

echo "Neue Nachrichten: ", (int)trim($r['NewMessages:']), "\n";
echo "Alte Nachrichten: ", (int)trim($r['OldMessages:']), "\n";
echo "\n";

# Ausloggen - nicht unbedingt nötig, aber sauber:
#
$ami->Logoff();
# allerdings ist die Funktion der StarAstAPI nicht gerade schön.
# sie tut dies:
#echo "Logoff Called from somewhere ...";
#socket_close($this->mSocket);

echo "\n";
?>

$ ./vmcount.php 123@default
Mailbox: 123123123

Neue Nachrichten: 0
Alte Nachrichten: 0

Logoff Called from somewhere ...