Überarbeitet: 25.09.26

Ich wollte eige.ntlich nur wissen, wie viele echte Benutzer eigentlich auf meinem Matrix-Server aktiv sind. Der erste Aufruf der Synapse-API war da wenig aufschlussreich. Telegram-, Discord- und andere Bridge-Konten füllten die Liste. Nachdem ich meinen jq-Filter ergänzt hatte, kam allerdings gar nichts mehr.

Kurz dachte ich, ich hätte die falsche API erwischt. Das Problem war am Ende viel kleiner: Mein Filter verlangte ein Feld, das in der Antwort gar nicht vorhanden war.

Token einlesen und Benutzerliste abrufen

Für die Admin-API brauche ich ein Zugriffstoken eines Serveradministrators. Ich schreibe es nicht direkt in den Befehl, weil es sonst im Shell-Verlauf landet:

read -rsp "Matrix-Admin-Token: " MATRIX_TOKEN; echo
MATRIX_URL="https://matrix.example.de"

Die Beispieladresse ersetze ich natürlich durch meine eigene Matrix-Domain. Danach lasse ich mir zunächst die unveränderte Liste ausgeben:

curl -s \
  -H "Authorization: Bearer $MATRIX_TOKEN" \
  "$MATRIX_URL/_synapse/admin/v3/users?limit=1000&deactivated=false" \
| jq -r '.users[] | select(.is_guest == false) | .name' \
| while read -r USER; do

    ENCODED_USER=$(printf '%s' "$USER" | jq -sRr @uri)

    DETAILS=$(curl -s \
      -H "Authorization: Bearer $MATRIX_TOKEN" \
      "$MATRIX_URL/_synapse/admin/v2/users/$ENCODED_USER")

    APPSERVICE=$(printf '%s' "$DETAILS" | jq -r '.appservice_id // empty')
    USER_TYPE=$(printf '%s' "$DETAILS" | jq -r '.user_type // empty')

    if [ -z "$APPSERVICE" ] && [ "$USER_TYPE" != "bot" ] && [ "$USER_TYPE" != "support" ]; then
        printf '%s\n' "$USER"
    fi
done

Nun sehe ich, was Synapse wirklich liefert. Bridge-Konten erkennt man oft an Präfixen wie @telegram_…. Diese Namen sind aber nicht überall gleich. Deshalb nehme ich die Muster aus meinen eigenen Appservice-Konfigurationen und nicht aus irgendeiner fremden Liste.

Welche Felder die Synapse-API tatsächlich in der Benutzerliste zurückliefert, kann je nach Endpunkt und Version unterschiedlich sein. In meinem Fall enthielt die Übersicht unter /v3/users beispielsweise keine appservice_id. Deshalb reicht ein einfacher jq-Filter auf der Listenabfrage nicht aus, um Bridge-Puppets zuverlässig zu erkennen.

Für die Filterung frage ich deshalb zusätzlich die Detailinformationen jedes Benutzers über /v2/users/<MXID> ab. Dort steht die appservice_id zur Verfügung, sodass Appservice-Konten sauber ausgeschlossen werden können.

Sind das wirklich alle Konten?

Die Antwort kann einen next_token enthalten. Dann wartet noch eine weitere Seite und der nächste Aufruf benötigt diesen Wert als Parameter from. Bei meiner überschaubaren Installation reichen 1.000 Einträge, kontrollieren möchte ich den Token trotzdem.

Für längere Terminalarbeiten nutze ich gern eine Sitzung, die einen Verbindungsabbruch überlebt. Das habe ich in meiner tmux-Anleitung für Einsteiger beschrieben.

Der wichtigste Schritt war diesmal übrigens nicht der fertige Filter, sondern der Blick auf die echte JSON-Antwort. Habt ihr in euren Matrix-Listen auch mehr Bridge-Konten als Menschen?