Das Manager-Interface (AMI)

AMI ist das klassische, seit vielen Jahren bestehende TCP-Protokoll, mit dem externe Programme Asterisk fernsteuern und Ereignisse mitlesen. Für neue Anwendungen, die Gespräche steuern (Click-to-Call, IVR mit eigener Logik, Audio abspielen, DTMF verarbeiten), empfehlen wir heute ARI. AMI bleibt weiter sinnvoll für Monitoring-Skripte, für einfaches Event-Handling mit Tools wie expect, nc oder kleinen Python-/ Node-Skripten und für bestehenden Altbestand.

manager.conf

Sie aktivieren das Manager-Interface in der Datei /etc/asterisk/manager.conf. Im Abschnitt [general] muss enabled=yes stehen; darunter legen Sie pro externem Client einen eigenen User-Block an.

[general]
enabled=yes
port=5038
bindaddr=127.0.0.1      ; NUR lokal binden

[admin]
secret = EIN-LANGES-PASSWORT
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.255
read = system,call,log,verbose,agent,user,config,dtmf,reporting,cdr,dialplan
write = system,call,agent,user,config,command,reporting,originate

Binden Sie das AMI niemals auf eine öffentliche IP-Adresse. Wer sich am AMI mit write = command anmelden kann, darf beliebige CLI-Befehle ausführen und damit faktisch alles auf dem System. Die Minimal-Konfiguration ist bindaddr=127.0.0.1, nur lokal erreichbar, plus deny/permit-ACL. Siehe AMI und ARI absichern.

Die read- und write-Listen begrenzen, welche Klassen von Actions/Events ein User sehen und ausführen darf. Die vollständige Klassenliste steht im CLI unter manager show commands (zeigt pro Action, welche Privilege-Klasse sie benötigt).

Erster Test mit Netcat

Nach asterisk -rx 'module reload manager' verbinden Sie sich zum Schnelltest mit nc direkt aufs AMI:

$ nc 127.0.0.1 5038
Asterisk Call Manager/...
Action: Login
Username: admin
Secret: EIN-LANGES-PASSWORT

(Eine Leerzeile schließt das Paket ab.) Wenn alles stimmt, antwortet Asterisk:

Response: Success
Message: Authentication accepted

Zum Ausprobieren können Sie anschließend Actions wie Ping, CoreSettings oder PJSIPShowEndpoints schicken:

Action: PJSIPShowEndpoints

Das Ergebnis kommt in einer Serie von Event-Paketen, abgeschlossen mit einem Event: EndpointListComplete.

Protokoll-Überblick

Ein AMI-Paket ist eine Folge von Schlüssel: Wert-Zeilen, getrennt durch CR/LF, beendet durch eine Leerzeile. Es gibt drei Pakettypen:

  • Action — vom Client gesendet. Beispiel: Action: Originate. Jede Action sollte eine eindeutige ActionID mitschicken, damit die zugehörige Response sich beim parallelen Verkehr zuordnen lässt.

  • Response — die Antwort des Servers auf eine Action. Meist Response: Success oder Response: Error, ggf. gefolgt von weiteren Feldern oder einer Serie von Events (bei längeren Abfragen).

  • Event — der Server sendet ungefragt Events (Newchannel, BridgeEnter, DialEnd, …). Wenn Ihr Client nur Antworten braucht, kann er beim Login Events: off mitschicken.

Die verfügbaren Actions listet manager show commands im Asterisk-CLI auf, Details zu einer Action zeigt manager show command <name> — siehe auch AMI-Befehle.

Beispiel: MailboxCount mit einem kleinen Python-Skript

Ein minimales Skript, das die Nachrichtenanzahl einer Mailbox abfragt — ohne externe Bibliotheken, nur mit der Standard-Socket-API:

#!/usr/bin/env python3
# mailbox-count.py 1234@default
import socket, sys

USER, SECRET = "admin", "EIN-LANGES-PASSWORT"
HOST, PORT   = "127.0.0.1", 5038
mailbox      = sys.argv[1]

def send(sock, action):
    pkt = "".join(f"{k}: {v}\r\n" for k, v in action.items()) + "\r\n"
    sock.sendall(pkt.encode())

def read_until_blank(sock):
    buf = b""
    while b"\r\n\r\n" not in buf:
        buf += sock.recv(4096)
    return buf.decode()

s = socket.create_connection((HOST, PORT))
s.recv(4096)   # Banner verwerfen
send(s, {"Action": "Login", "Username": USER, "Secret": SECRET})
resp = read_until_blank(s)
if "Response: Success" not in resp:
    print("Login fehlgeschlagen"); sys.exit(1)

send(s, {"Action": "MailboxCount", "Mailbox": mailbox, "ActionID": "1"})
resp = read_until_blank(s)
print(resp)

send(s, {"Action": "Logoff"})
s.close()

Aufruf:

$ python3 mailbox-count.py 200@default
Response: Success
ActionID: 1
Message: Mailbox Message Count
Mailbox: 200@default
UrgMessages: 0
NewMessages: 0
OldMessages: 0

Fertige Bibliotheken

Für ernsthafte AMI-Integrationen sollten Sie eine Bibliothek einsetzen, die Re-Connect, Event-Parsing und ActionID-Matching für Sie erledigt. Etablierte Optionen:

Sobald Ihre Anwendung Gespräche nicht nur überwacht, sondern steuert (Originate mit Dialplan-Sprüngen, eigene IVR-Logik, Audio abspielen), sollten Sie stattdessen ARI verwenden. AMI bleibt für reine Überwachung (CDR-Tracking, Statusanzeigen, CTI-Popups) weiterhin das einfachste Werkzeug.