Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Stadion-Intercom – Administration

Admin-GUI, Provisionierung und Ueberwachung fuer ein Mumble-basiertes PTT-Intercom im Leichtathletik-Stadion: Regie, Kameras, Zeitnahme (FinishLynx), Stadionsprecher, Technik, Kampfgericht.

Kein Dashboard zum Anschauen, sondern ein Betriebs-Cockpit: jeder Client mit IP, Ping, Paketverlust, Version und Zertifikat; jede Regel; jede Rolle. Dazu ein Pult, an dem Personen, Rollen und Plaetze per Ziehen verbunden, Rechte je Platz verteilt und Ruftasten zentral belegt werden.

Die Wahrheit steht im Server. Angelegt und geaendert wird in der Oberflaeche, und was dort steht, bleibt dort — es gibt keine Datei, die beim naechsten Start etwas zurueckschreibt. Fuer den Anfang gibt es Baukaesten, fuer wechselnde Veranstaltungen benannte Shows (ganzer Aufbau speichern und laden), fuer den Notfall eine Sicherung als Datei. Die YAML-Provisionierung gibt es weiterhin, aber als Werkzeug, nicht als Herrn: PROVISION_ON_START ist per Vorgabe aus.


Inhalt

  1. Schnellstart
  2. Architektur
  3. Vertrag mit der Compose
  4. Dateiformat: Shows, Sicherung, intercom.yaml
  5. Kommandozeile
  6. Bekannte Grenzen
  7. Fehlersuche
  8. Entwicklung und Tests

Schnellstart

Zielsystem ist ein beliebiger Linux-Rechner mit Docker — Raspberry Pi, Zima Board, Mini-PC, virtuelle Maschine. Gebaut und gegen einen echten mumble-server geprueft auf x86-64 und arm64. Das Betriebssystem des Hosts spielt keine Rolle (Ubuntu, Debian, Raspberry Pi OS): der Container bringt sein eigenes mit.

Docker aus der offiziellen Quelle

Bewusst nicht apt install docker.io. Nachgemessen auf Ubuntu 24.04 und 22.04 (Stand September 2026):

offizielle Quelle Ubuntu-Paket
Engine docker-ce 29.8.1 docker.io 29.1.3
Compose docker-compose-plugin 5.5.1 docker-compose-v2 2.40.3
buildx docker-buildx-plugin 0.37.1 docker-buildx 0.30.1

Die Engine selbst ist nah dran — der Abstand bei Compose ist dagegen ein Hauptversionssprung. Dazu kommt das Praktische: apt install docker.io allein gibt weder docker compose noch docker buildx, beides sind getrennte Pakete, die man einzeln kennen und nachziehen muss. Und Docker nennt docker.io in seiner eigenen Anleitung unter den Paketen, die vor der Installation weg muessen -- beides nebeneinander geht nicht.

Die folgenden Befehle sind nicht abgeschrieben, sondern in einem frischen ubuntu:24.04 durchlaufen: Ergebnis Docker 29.8.1, Compose v5.5.1, buildx 0.37.1.

# Falls eine Distributionsfassung im Weg liegt (auf fertigen Pi-Abbildern oft):
sudo apt remove -y docker.io docker-compose docker-compose-v2 docker-doc \
                   podman-docker containerd runc

# Schluessel und Paketquelle von Docker eintragen:
sudo apt update
sudo apt install -y ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
     -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
                    docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker "$USER"     # danach ab- und wieder anmelden

Auf Raspberry Pi OS oder Debian statt Ubuntu: in den beiden Zeilen mit download.docker.com das ubuntu durch debian ersetzen, und bei Suites: genuegt $VERSION_CODENAME. Sonst ist alles gleich.

Die Paketquelle liefert arm64 und amd64 — derselbe Befehlssatz auf Pi wie auf dem Zima Board.

Zum Pruefen, bevor es weitergeht:

docker run --rm hello-world
docker compose version

Einrichten

git clone https://github.com/ConGp20/mumble-gui.git ~/stadion-intercom
cd ~/stadion-intercom
./setup.sh

setup.sh prueft Docker, legt ./server, ./admin-data und das (leere) ./config an, setzt die beiden ersten auf UID/GID 10000, ersetzt alle ERSETZEN_*-Werte in der .env durch Zufallswerte, startet den Mumble-Server, wartet auf dessen Ice-Schnittstelle, gleicht MUMBLE_VERSION an die tatsaechlich laufende Serverversion an und zieht das Admin-Image aus der Registry (gebaut wird nur, wenn das fehlschlaegt). Der Server bleibt dabei leer — Kanaele legt man danach in der Oberflaeche an.

Das Skript stellt keine Rueckfragen und ist wiederholbar: ein zweiter Lauf aendert nur, was noch nicht stimmt.

./setup.sh --check    # nur pruefen, nichts aendern

Am Ende nennt es die Adresse, den Benutzernamen und die Schritte, mit denen es weitergeht. Das Passwort steht in der erzeugten .env als ADMIN_PASSWORD.

Und dann?

Schritt Wo
1. Einen Baukasten anwenden (erst Testlauf, dann Anwenden) /einrichten
2. Alle einmal mit dem Mumble-Programm verbinden lassen —
3. Jeden registrieren — der Server erkennt Leute am Zertifikat, nicht am Namen /nutzer
4. Personen per Ziehen in Rollen und auf Plaetze setzen, Rechte verteilen /pult
5. Ruftasten belegen und einmal je Geraet im Mumble-Programm einrichten (das Platzblatt fuehrt durch) /pult
6. Aktuellen Stand als Show speichern /einrichten („Shows“)

Wenn Mumbles Modell unklar ist: /anleitung erklaert es in Klartext — vor allem, warum Rechte am Platz haengen und nicht an der Person.

Danach liegt die Oberflaeche auf http://<rechner>:8080/. Benutzer und Passwort stehen in der .env (ADMIN_USER, ADMIN_PASSWORD).

Auf den neuesten Stand bringen

cd ~/stadion-intercom
git pull
./setup.sh

setup.sh ist wiederholbar: es laesst die .env und alle Daten stehen, zieht das aktuelle Admin-Image und startet neu. Was wo liegt und davon unberuehrt bleibt:

Verzeichnis Inhalt
./server Plaetze, Rollen, Rechte, registrierte Personen — die Datenbank des Mumble-Servers
./admin-data Shows, feste Plaetze, Mithoeren und Vorrang je Person, Verbindungen, Ruftasten, Netzsegmente, Verlauf und Protokoll
./config leer; nur fuer eine Vorgabedatei der Kommandozeile

Von einem Stand vor Oktober 2026: Die intercom.yaml im Projektverzeichnis wird nicht mehr gelesen (DECISIONS.md, D-034). Hast du sie nie veraendert, entfernt git pull sie von selbst. Hast du sie veraendert, bricht git pull mit „local changes would be overwritten“ ab — dann vorher beiseitelegen und danach entscheiden, ob sie gebraucht wird:

mkdir -p config && mv intercom.yaml config/intercom.yaml   # bleibt Vorgabe fuer die Kommandozeile
git pull && ./setup.sh

Als Show einspielen geht stattdessen in der Oberflaeche (Shows → Datei waehlen …); dann config/intercom.yaml wieder loeschen.

Das Image wird normalerweise nicht gebaut, sondern geladen

.github/workflows/image.yml baut es bei jedem Push nach admin/ und legt es in die Container-Registry von GitHub. Gebaut wird auf zwei Laeufern, jeder nativ fuer seine Architektur — ubuntu-latest fuer x86-64 und ubuntu-24.04-arm fuer arm64 — und am Ende zu einer Multi-Arch-Liste zusammengefasst. docker pull waehlt daraus von selbst das Passende; auf einem Pi ist damit nichts zu uebersetzen.

setup.sh versucht zuerst zu ziehen und baut nur, wenn das nicht klappt:

✔ Fertiges Image geladen – es muss nichts gebaut werden

Gemessen: die komplette Einrichtung mit fertigem Image dauert 14 Sekunden, mit lokalem Bau rund eine Minute auf x86-64.

Einmalig von Hand: ein neues Paket in der GitHub-Registry ist privat, auch wenn das Repository oeffentlich ist — es erbt vom Repository die Zugriffsrechte, aber nicht die Sichtbarkeit. Damit ein Pi ohne Anmeldung ziehen kann, das Paket einmal auf public stellen: GitHub → Profil → Packages → mumble-admin → Package settings → Change visibility.

Soll es privat bleiben, meldet sich das Geraet mit einem Token an:

echo "<TOKEN mit read:packages>" | docker login ghcr.io -u <konto> --password-stdin

Selbst bauen, wenn du am Quelltext etwas geaendert hast:

docker compose build mumble-admin
# oder direkt:
docker build -t stadion-intercom/mumble-admin:v1.5.735 admin/

Damit setup.sh das eigene Image nimmt statt zu ziehen, in der .env ADMIN_IMAGE auf den eigenen Namen setzen.

Gemessen ohne jeden Cache: 50 Sekunden auf x86-64. Es wird nichts uebersetzt, nur installiert — deshalb bleibt es auch auf schwacher Hardware in derselben Groessenordnung. Das fertige Image meldet docker images mit rund 330 MB.

Es prueft sich selbst: schlaegt import MumbleServer, Ice oder import intercom.web.app fehl, bricht der Bau ab, statt ein Image zu hinterlassen, das erst im Stadion auffaellt. Hinter einem Proxy mit TLS-Aufbruch: admin/ca/README.md.

Auf einem Raspberry Pi ist nichts weiter zu tun — docker build nimmt von selbst die arm64-Fassung der Basisimages. Das ist nachgewiesen, nicht vermutet: das arm64-Image wurde gebaut, gestartet und gegen denselben echten mumble-server gefahren wie die x86-Fassung — uname -m meldet aarch64, Ice 3.7.8 mit 133 Pruefsummen, alle Seiten und Endpunkte antworten, der Monitor-Bot haengt stumm und taub im Zielkanal.

Der Nachweis lief unter QEMU-Emulation auf einem x86-Rechner. Er belegt, dass das Image auf arm64 baut und laeuft — nicht, wie schnell es auf echter Pi-Hardware ist. Die Antwortzeiten unter Emulation (Cockpit-Seite 0,22 s gegen 0,03 s nativ) sind Emulationskosten, kein Massstab fuer den Pi.

Wer auf einem x86-Rechner fuer den Pi bauen will (etwa um die SD-Karte zu schonen):

docker build --platform linux/arm64 -t stadion-intercom/mumble-admin:v1.5.735 admin/
docker save stadion-intercom/mumble-admin:v1.5.735 | gzip > intercom-arm64.tgz
# auf dem Pi:
gunzip -c intercom-arm64.tgz | docker load

Dafuer muss auf dem bauenden Rechner die Emulation eingerichtet sein: docker run --privileged --rm tonistiigi/binfmt --install arm64.

Das Cockpit laeuft unverschluesselt. Passwort und Sitzungscookie gehen im Klartext ueber das Netz. Fuer ein abgeschlossenes Stadionnetz ist das vertretbar — aber nur dann. Haengt der Rechner mit einem Bein im Internet oder im Buero-LAN, gehoert ein Reverse Proxy mit TLS davor; die Anwendung aendert sich dafuer nicht, sie liefert weiterhin nur HTTP auf LISTEN_PORT.

Erste Absicherung ohne Zusatzsoftware: LISTEN_HOST in der .env auf die Netzkarte des Stadionnetzes setzen statt auf 0.0.0.0. Dann ist der Port auf den anderen Schnittstellen gar nicht erst offen.


Architektur

  Stadion-LAN                    Host-Netz des Rechners
 ┌──────────────┐
 │ Mumble-Desktop│──64738──┐
 │ Mumla (PoC)   │         │   ┌──────────────────────────────────────┐
 │ Mumble iOS    │         └──▶│ mumble-server (murmur 1.5)           │
 └──────────────┘             │                                       │
                              │   Ice  127.0.0.1:6502  ◀──────────┐   │
                              └──────────────────────────────────┼───┘
                                                                 │
                              ┌──────────────────────────────────┼───┐
                              │ mumble-admin (ein Prozess)       │   │
                              │                                  │   │
                              │  ┌────────────┐  Ice-Aufrufe ────┘   │
                              │  │ IceClient  │                      │
                              │  │            │◀── Callbacks ────────┤
                              │  └─────┬──────┘   (eigener Adapter   │
                              │        │           auf 127.0.0.1)    │
                              │        ▼                             │
                              │  ┌────────────┐   ┌───────────────┐  │
                              │  │ LiveState  │◀──│ Monitor-Bot   │──┼──64738──▶
                              │  │ + Alarme   │   │ (pymumble)    │  │
                              │  └─────┬──────┘   └───────┬───────┘  │
                              │        │                  │          │
                              │        ▼                  ▼          │
                              │  ┌────────────┐   ┌───────────────┐  │
                              │  │ FastAPI    │   │ SQLite        │  │
                              │  │ + SSE      │   │ /data/…sqlite │  │
                              │  └─────┬──────┘   └───────────────┘  │
                              └────────┼─────────────────────────────┘
                                       │ HTTP 8080
                              ┌────────▼─────────┐
                              │  Browser im      │
                              │  Stadionnetz     │
                              └──────────────────┘

Ein Container, ein Prozess. uvicorn betreibt den asyncio-Loop; Polling, Verlaufs-Aufraeumen und der Verbindungswaechter sind asyncio-Tasks. Ice und pymumble bringen eigene Threads mit — deren Ereignisse werden mit call_soon_threadsafe in den Loop gehoben, Ice-Aufrufe laufen ueber einen kleinen Threadpool. Begruendung: DECISIONS.md, D-009.

Daraus folgt eine Regel fuer die Endpunkte: wer LiveState anfasst, ist eine Koroutine (async def, laeuft im Loop), wer SQLite anfasst, bleibt synchron (def, landet in FastAPIs Threadpool, wo Blockieren richtig ist). Ein Ice-Aufruf darf in einer Koroutine nur ueber await ctx.ice.run(...) passieren. Siehe DECISIONS.md, D-018. Jeder einzelne Ice-Aufruf ist zusaetzlich auf 15 s begrenzt — nicht ueber Ice.Override.Timeout, das dafuer nachweislich nicht taugt, sondern ueber ice_invocationTimeout (D-017).

Warum zwei Datenquellen? Ice liefert pro Client udpPing, tcpPing, bytespersec und tcponly — aber keinen Paketverlust. Ein getUserStats gibt es in der Slice nicht. good/late/lost/resync stehen ausschliesslich in der UserStats-Nachricht des Mumble-Protokolls, die nur ein angemeldeter Client abfragen kann. Genau dafuer haengt der Monitor-Bot im Server.

Die Seiten

Seite Wofuer
Die Navigation ist in drei Gruppen geordnet; die Namen folgen
admin/intercom/woerter.py (Platz statt Kanal, Rolle statt Gruppe, Person statt
registrierter Nutzer, oberster Platz heisst „Ueberall“).
Gruppe Seite Wofuer
Betrieb / Cockpit Wer ist verbunden, wie ist die Leitung (Ping, Verlust, Netzsegment), was alarmiert
Aufbauen /pult Pult Personen in Rollen und auf Plaetze ziehen, Rechte je Platz, Verbindungen, Ruftasten
Aufbauen /nutzer Personen Registrieren, umbenennen, entfernen — der Server erkennt Leute am Zertifikat
Aufbauen /kanaele Plaetze Anlegen, umbenennen, verschieben
Aufbauen /einrichten Shows Ganze Aufbauten speichern, vergleichen (Testlauf) und laden; Sicherung als Datei; Baukaesten fuer den Anfang
Fachsicht /acl Rechte Die Regeln Eintrag fuer Eintrag, so wie Mumble sie fuehrt (ACL)
Fachsicht /server Server Serverkonfiguration, Netzsegmente, Sperren
Fachsicht /audit Protokoll Wer hat wann was geaendert
/anleitung Mumbles Modell in Klartext — Vererbung, Richtung der Rechte, Raster lesen

Jede Seite traegt oben denselben Erklaerkopf: was man hier tut, wann man es braucht, worueber alle einmal stolpern. Das Pult ist die Alltagsansicht, die Fachsicht bleibt daneben stehen. Wo das Raster im Pult etwas nicht verlustfrei abbilden kann — mehrere eigene ACL-Eintraege derselben Rolle an einem Kanal, deren Reihenfolge entscheidet — sperrt es die Zelle und verweist auf /acl, statt zu raten.

Verzeichnisse

Pfad Inhalt
admin/intercom/ice/ Ice-Anbindung: Client, Callbacks, Rechtetabelle, Domaenenmodell
admin/intercom/provision/ Dateiformat, ACL-Abbildung, Planer, Exporter, Baukaesten
admin/intercom/ice/wirkung.py Nachgebaute Rechte-Auswertung (ACL.cpp, Group.cpp)
admin/intercom/runtime.py Laufzeit-Abgleich: fester Platz, Vorrang, Mithoeren, Ruftasten
admin/intercom/ruftasten.py Belegung der Ruftasten, Vererbung, Abdeckung (D-032)
admin/intercom/woerter.py Die Woerter der Oberflaeche und warum
admin/intercom/monitor/ pymumble-Bot und Auswertung der UserStats
admin/intercom/store/ SQLite: Verlauf, Protokoll, Notizen, Wunschzustand, Verbindungen, Ruftasten, Netze, Shows
admin/intercom/web/ FastAPI, SSE, Anmeldung, JSON-Schnittstelle
admin/intercom/web/pult.py Pult: Plaetze, Rollen, Personen, Rechtematrix, Verbindungen, Ruftasten
admin/intercom/web/shows.py Shows und Sicherung: ein Einspielweg mit Testlauf (D-033)
beispiele/ Ein ganzer Stadion-Aufbau als Datei — Beispiel, nicht aktiv
admin/templates/, admin/static/ Oberflaeche (htmx + Alpine, kein Bauschritt)
admin/tests/ Tests inkl. murmur-Doppel ueber echtes Ice

Vertrag mit der Compose

Alles, was zwischen docker-compose.yml und der Anwendung ausgetauscht wird, steht an genau einer Stelle im Code: admin/intercom/config.py. Wer eine Variable einfuehrt, aendert diese Datei und die Compose — sonst nichts.

Umgebungsvariablen

Variable Vorgabe Bedeutung
MUMBLE_VERSION v1.5.735 Einzige Versionsquelle. Bestimmt den Tag des Server-Images und den Tag, aus dem MumbleServer.ice geladen wird.
ICE_HOST / ICE_PORT 127.0.0.1 / 6502 Ice-Endpunkt von murmur.
ICE_SECRET – icesecretwrite des Servers. Ohne passendes Secret keine schreibenden Aufrufe. Wird nie geloggt.
ICE_SERVER_ID 1 Virtueller Server. murmur zaehlt ab 1.
LISTEN_HOST / LISTEN_PORT 0.0.0.0 / 8080 Wo das GUI lauscht (plain HTTP).
ADMIN_USER / ADMIN_PASSWORD admin / – Vollzugang.
ADMIN_READONLY_USER / ADMIN_READONLY_PASSWORD – Optionaler Nur-Lese-Zugang. Leer = aus.
SESSION_SECRET – Signiert das Sitzungs-Cookie. Fehlt er, wird ein Zufallswert erzeugt und gewarnt — alle Anmeldungen gehen dann bei jedem Neustart verloren.
INTERCOM_CONFIG /config/intercom.yaml Vorgabedatei fuer die Kommandozeile. Fehlt sie, ist das der Normalfall. Liegt dort eine, liest die Oberflaeche daraus auch Netze, Geraete und Soll-Plaetze.
PROVISION_ON_START false Beim Containerstart die Vorgabedatei anwenden. Aus, weil der Server die Wahrheit ist (D-029).
PROVISION_PRUNE false Plaetze/Rollen loeschen, die nicht in der Datei stehen — beim Start, fuer Baukaesten und fuer intercom apply ohne --prune. Shows und Dateien fragen in der Oberflaeche je Testlauf nach („Aufraeumen“).
MONITOR_BOT_ENABLED true Monitor-Bot an/aus. Aus = kein Paketverlust.
MONITOR_BOT_NAME monitor Anmeldename des Bots.
MONITOR_BOT_CHANNEL leer Platz als Pfad. Leer = der Bot bleibt ganz oben.
MONITOR_BOT_CERT /data/monitor-cert.pem Client-Zertifikat. Fehlt es, wird eines erzeugt.
MONITOR_STATS_INTERVAL_MS 5000 Abstand zwischen zwei UserStats-Runden.
MUMBLE_PORT 64738 Port, auf dem der Bot sich anmeldet.
POLL_INTERVAL_MS 2000 Statistik-Polling. Werte unter 250 werden angehoben.
HISTORY_RETENTION_HOURS 48 Aufbewahrung des Metrik-Verlaufs.
ALERT_PING_MS 80 Schwelle Warnung; das Doppelte gilt als kritisch.
ALERT_LOSS_PCT 2.0 dito fuer Paketverlust.
LOG_LEVEL INFO
DATA_DIR /data SQLite und Bot-Zertifikat.
SLICE_DIR /opt/intercom/slice Uebersetzte Slice. Wird im Image gesetzt.

Volumes und Netz

  • ./server:/data (mumble-server), ./admin-data:/data (mumble-admin), ./config:/config:ro (mumble-admin, im Normalfall leer)
  • Beide Dienste laufen mit network_mode: host. Das ist keine Bequemlichkeit: Ice-Callbacks sind kein Polling — murmur baut eine Verbindung zum Admin-Prozess auf. Laege der Server in einem Bridge-Netz, waere 127.0.0.1 aus seiner Sicht sein eigener Namespace und der Rueckruf ginge ins Leere. Siehe DECISIONS.md, D-002.
  • Kein Dienst haengt an einem Compose-Profil: docker compose down beendet beide, docker compose up -d startet beide. Beide stehen auf restart: unless-stopped und kommen nach einem Stromausfall von selbst wieder. Beides haelt admin/tests/test_compose.py fest.

Dateiformat: Shows, Sicherung, intercom.yaml

Eine Show, eine heruntergeladene Sicherung und eine Vorgabedatei fuer die Kommandozeile sind dasselbe Format. Ein vollstaendiges Beispiel liegt unter beispiele/stadion-intercom.yaml — als Beispiel, nicht aktiv: kein Container liest es. Einspielen in der Oberflaeche unter Shows → Datei waehlen ….

Die Namen in der Datei sind Mumbles Namen (channels, groups, users): die Datei ist die Fachsicht. In der Oberflaeche heissen dieselben Dinge Plaetze, Rollen und Personen.

Aufbau

version: 1
server:        { defaultchannel: …, welcometext: … }
groups:        [ … ]          # Rollen
acl_templates: { name: [ … ] }
channels:      [ … ]          # Plaetze, als Baum
policies:      { … }
users:         { name: { groups: [...], channel: … } }
networks:      [ { name, cidr, note } ]
devices:       { name: { … } }

# Nur aus der Oberflaeche -- Mumble merkt sich das nicht (D-031 bis D-033):
wunsch:        { platz|mithoeren|vorrang: { person: [ pfad, … ] } }
verbindungen:  { hoert|reinschalten: { von-pfad: [ nach-pfad, … ] } }
ruftasten:     { pfad: { 1: rolle, … } }   # "/" = Ueberall

Die letzten drei Abschnitte schreibt der Export, und Shows/Sicherung spielen sie wieder ein. Personen stehen dort mit Namen, Plaetze mit Pfad — IDs vergibt der Server und waeren nach dem Wiederanlegen falsch. Wen der Server beim Einspielen nicht kennt, nennt das Ergebnis. Die Kommandozeile (intercom apply) ueberliest diese drei Abschnitte.

groups

Liste eigener Gruppennamen. Sie werden am Wurzelkanal angelegt und vererben sich nach unten.

Abweichung von der urspruenglichen Vorgabe. Vorgesehen war der oberste konfigurierte Kanal (Intercom). Das funktioniert fuer kick, ban und register_users nicht: murmur wertet diese Rechte ausschliesslich am Wurzelkanal aus (src/ACL.cpp: if (ch->iId == 0 && applyFromSelf)). Damit Richtlinien und Gruppen dieselbe Stelle sehen, liegen beide an der Wurzel.

Von murmur fest eingebaut und nicht neu definierbar: all, auth, in, out, sub, ~sub, admin.

In ACL-Eintraegen versteht murmur zusaetzlich Praefixe:

Praefix Bedeutung
!gruppe kehrt die Bedingung um
~gruppe bezieht sich auf den Kanal, in dem die ACL steht
#token Zugriffstoken statt Gruppe
$hash Zertifikatshash statt Gruppe

channels[]

Schluessel Bedeutung
name Pflicht. Eindeutig unter demselben Elternkanal, ohne /.
description Tooltip im Client.
position Sortierung (kleiner = weiter oben).
acl_template Name aus acl_templates. Wird zuerst angewendet.
acl Rohe ACL-Eintraege, gleiche Form wie in acl_templates. Danach angewendet.
groups Eigene Gruppen dieses Kanals (Name, Mitglieder als Namen, optional inherit/inheritable). Die Gruppen aus groups: auf oberster Ebene liegen dagegen am Wurzelkanal.
speak Gruppen, die hier sprechen duerfen.
whisper_in Gruppen, die hierher fluestern duerfen.
listen_for Gruppen, die den Kanal mithoeren duerfen.
listen_to Kanaele, die die speak-Gruppen zusaetzlich mithoeren sollen.
priority Gruppen, deren Mitglieder hier Priority Speaker sind.
links Kanaele, mit denen verlinkt wird.
children Unterkanaele.

Wie speak / whisper_in / listen_for zu ACLs werden

murmur gewaehrt ohne jede ACL bereits Traverse | Enter | Speak | Whisper | TextMessage | Listen (src/ACL.cpp, def). Ein deny ist also kein Zierrat, sondern noetig, um etwas wegzunehmen.

Pro Kanal entsteht immer dieselbe Reihenfolge — und Reihenfolge ist Semantik, weil murmur granted |= allow; granted &= ~deny der Reihe nach auswertet, ein spaeterer Eintrag also gewinnt:

  1. Eintraege aus acl_template
  2. Eintraege aus acl
  3. ein zusammengefasster @all-Eintrag
  4. je ein Eintrag pro Gruppe, alphabetisch
Angabe Ergebnis
speak: [regie, leitung] @all deny Speak; @regie/@leitung allow Speak + Traverse + Enter
speak: [all] @all allow Speak
speak: fehlt zu Speak wird nichts gesagt; die Vererbung bleibt unangetastet
whisper_in: [technik] @all deny Whisper; @technik allow Whisper + Traverse
listen_for: [all] @all allow Listen
listen_for: [regie] @all deny Listen; @regie allow Listen + Traverse

Traverse und Enter werden mitgegeben. Wer sprechen soll, muss den Kanal betreten koennen; wer mithoeren oder hineinfluestern soll, muss ihn wenigstens sehen. Ohne das ergaeben restriktive Vorlagen Kanaele, die niemand benutzen kann. Bei den Vorgabewerten aendert das nichts — nur dort, wo eine Vorlage Enter oder Traverse entzieht.

policies

Richtlinie Recht Geltung
whisper_anywhere Whisper Wurzel + Unterkanaele
move_users Move Wurzel + Unterkanaele
mute_deafen MuteDeafen Wurzel + Unterkanaele
make_channel MakeChannel Wurzel + Unterkanaele
kick Kick nur Wurzel
ban Ban nur Wurzel
register_users Register nur Wurzel
guests_listen_only @all deny Speak+Whisper Wurzel + Unterkanaele
priority_speaker kein ACL Nutzerzustand, zur Laufzeit gesetzt

users

users:
  regie-1: { groups: [regie], channel: "Intercom/Regie" }

groups steuert die Mitgliedschaft. Der Name muss registriert sein — ohne Registrierung gibt es keine Nutzer-ID, und Gruppenmitgliedschaft laeuft ueber IDs. Unbekannte Namen landen im Provisioning-Report, statt still zu verschwinden.

channel ist optional und rein fuer die Alarmleiste: steht der Client nicht dort, faellt es im Cockpit auf. Verschoben wird niemand automatisch — waehrend eines Wettkampfs waere das gefaehrlich.

Kanaleigene Gruppen

channels:
  - name: Intercom
    children:
      - name: Kameras
        groups:
          - name: kamera-lokal
            add: [kam-1, kam-2]
        speak: [kamera-lokal]

Mitglieder stehen als Namen, nicht als IDs: Nutzer-IDs vergibt der Server und waeren auf einem anderen Server bedeutungslos. Aufgeloest wird erst beim Anwenden — ein nicht registrierter Name landet im Provisioning-Report.

Gruppen, die an einem Kanal existieren und nicht in der YAML stehen, bleiben beim Anwenden erhalten; der Plan zeigt sie als „wuerde geloescht" an und PROVISION_PRUNE entfernt sie. Genauso wie an der Wurzel — setACL ersetzt immer alle Gruppen eines Kanals auf einmal.

networks und devices

networks ordnet Client-IPs Segmenten zu (Netzsicht, Heatmap); der erste passende Eintrag gewinnt. devices ist reine Dokumentation und erscheint im Detailpanel.

Rechtenamen

Write, Traverse, Enter, Speak, MuteDeafen, Move, MakeChannel, LinkChannel, Whisper, TextMessage, MakeTempChannel, Listen, Kick, Ban, Register, SelfRegister, ResetUserContent.


Kommandozeile

Fuer SSH ohne Browser. export und status gehen immer; validate, plan und apply brauchen eine Vorgabedatei unter ./config/intercom.yaml (Vorlage: beispiele/stadion-intercom.yaml).

docker compose exec mumble-admin intercom export > sicherung.yaml   # vollstaendige Sicherung
docker compose exec mumble-admin intercom status     # Kurzbericht
docker compose exec mumble-admin intercom validate   # nur die Datei pruefen
docker compose exec mumble-admin intercom plan       # zeigen, was sich aendern wuerde
docker compose exec mumble-admin intercom apply      # anwenden (fragt nach)
docker compose exec mumble-admin intercom apply --yes --prune

export schreibt dasselbe wie der Knopf in der Oberflaeche — samt festen Plaetzen, Verbindungen, Ruftasten und Netzen. Die Datei laesst sich unter Shows → Datei waehlen … wieder einspielen oder als Show ablegen.

Rueckgabewerte: 0 in Ordnung, 1 Fehler, 2 Konfiguration unbrauchbar, 3 bei plan --detailed-exitcode, wenn es etwas zu tun gaebe.

Dieselbe Logik haengt im GUI hinter den Knoepfen. Plan und Anwendung laufen durch denselben Code (Reconciler mit dry_run) — ein Plan kann also nicht von dem abweichen, was ein apply anschliessend tut.


Bekannte Grenzen

Channel-Listener ueberleben keinen Reconnect

startListening gibt es in der Slice von 1.5 — die urspruengliche Annahme, das ginge serverseitig nicht, war falsch. Die Slice-Dokumentation ist aber irrefuehrend: sie nennt den ersten Parameter „The ID of the user", die Implementierung nennt ihn session und loest ihn ueber NEED_PLAYER als Sitzung auf (MumbleServerIce.cpp). getListeningUsers gibt entsprechend Session-IDs zurueck.

Folge: Listener sind Sitzungszustand. Der Provisioner schreibt sie deshalb nicht in den Soll-Zustand; stattdessen setzt der Laufzeit-Abgleich sie bei userConnected und bei jedem Polling-Durchlauf nach. Im Cockpit steht pro Nutzer Soll gegen Ist, Abweichungen sind rot.

Listen fehlt in der Slice, wirkt aber

Die Slice von 1.5.857 deklariert keine Konstante PermissionListen. Der Server kennt das Recht (Listen = 0x800 in src/ACL.h), und setACL maskiert nur gegen ChanACL::All, das Listen enthaelt. Wir fuehren die Bit-Tabelle deshalb selbst und pruefen sie beim Start gegen die Slice. listen_for ist voll funktionsfaehig. Belegt durch test_listen_bit_ueberlebt_einen_echten_server samt Gegenprobe.

Ebenfalls korrigiert: die Slice heisst PermissionRegisterSelf (nicht PermissionSelfRegister) und ResetUserContent (ohne Permission-Praefix).

Ruftasten: zentral belegt, aber einmal im Client einzurichten

Profisysteme belegen Beltpack-Tasten zentral. Mumble hat Fluestertasten nur im Client, und die Slice kann sie nicht setzen. Der Umweg ueber redirectWhisperGroup ist gemessen (D-032): jedes Geraet richtet einmal Taste 1–4 als "Rufen an den obersten Platz samt Unterplaetzen, beschraenkt auf Gruppe ruf1…ruf4" ein; wen die Taste ruft, legt danach allein das Pult je Platz fest — auch fuer verbundene Geraete sofort, auch nach Platzwechsel.

Grenzen: die Einrichtung im Client bleibt Handarbeit (das Platzblatt fuehrt mit den deutschen Bezeichnungen des Mumble-Programms 1.5 hindurch). Gemessen ist die Serverseite mit einem Testclient, der genau das sendet, was das Mumble-Programm nach dieser Einrichtung sendet; am Desktop-Programm selbst ist es nicht durchgeklickt, mit Mumla und anderen Apps nicht geprueft. Eine Taste ruft eine Rolle, keinen einzelnen Platz.

Nicht ueber Ice moeglich

Was Warum
max_users pro Kanal Das Channel-Struct der Slice hat kein solches Feld, und es gibt keinen anderen Weg. Wird als Warnung gemeldet, nicht still ignoriert. Im Client von Hand setzbar.
Temporaere Kanaele anlegen addChannel legt immer dauerhaft an; Channel.temporary ist beim Schreiben wirkungslos.
priority_speaker exportieren Priority Speaker ist Nutzerzustand, kein ACL-Eintrag — der Server haelt dafuer keine Sollvorgabe vor.
Dauerhafte Gruppenmitgliedschaft ueber addUserToGroup Ausdruecklich temporaer und an die Sitzung gebunden. Der Provisioner benutzt ausschliesslich setACL.
Paketverlust Kein getUserStats in der Slice — dafuer gibt es den Monitor-Bot.

getAllConf ist nicht die wirksame Konfiguration

Die Namen der beiden Ice-Aufrufe fuehren in die Irre. Gegen murmur 1.5.735 nachgemessen, belegt in MumbleServerIce.cpp und Meta.cpp:

Aufruf Was wirklich drinsteht
Server::getAllConf SELECT key, value FROM config WHERE server_id = ? — nur was jemand zur Laufzeit per setConf geaendert hat. Auf einem frischen Server steht dort ausser dem selbst erzeugten certificate nichts.
Meta::getDefaultConf qmConfig, gebaut von MetaParams aus der ini-Datei plus den eingebauten Vorgaben. Beim Docker-Image ist das genau der Stand, den die MUMBLE_CONFIG_*-Variablen der Compose geschrieben haben.

„Default" heisst also nicht „murmurs Werkseinstellung". Der wirksame Wert ist: Datenbank, wenn dort ein Eintrag steht, sonst Datei. Die Ansicht Server → Konfiguration zeigt deshalb drei Spalten — Wirksam, Herkunft (Datenbank/Datei) und Faellt zurueck auf — statt eines irrefuehrenden Ist/Soll-Vergleichs. Eine Zeile mit Herkunft Datenbank ist der interessante Fall: dieser Wert wurde live geaendert und folgt der Compose nicht mehr, ueberlebt aber jeden docker compose up -d.

Ebenfalls nachgemessen: write-only ist nur key und passphrase. impl_Server_getConf prueft wortwoertlich diese zwei Namen. getConf("icesecretwrite") gelingt und liefert einen leeren String — das Secret steht in der ini-Datei, nicht in der config-Tabelle. Wer den leeren String fuer „kein Secret gesetzt" haelt, zieht den falschen Schluss.

VOX-Erkennung ist eine Heuristik

Mumble meldet den Sendemodus weder ueber Ice noch im Protokoll. Erkennbar ist nur dauerhafter Datenfluss ohne Leerlauf. Der Alarm schlaegt erst nach laengerer Zeit an, damit eine lange Ansage keinen Fehlalarm ausloest — und er ist im GUI als Verdacht gekennzeichnet, nicht als Feststellung.

Clients

  • Mumble Desktop – voller Funktionsumfang, inklusive Channel Listener und Zertifikatsanmeldung.
  • Mumla (Android, PoC-Handhelds Inrico/Anysecu) – PTT und Kanalwechsel funktionieren. Channel Listener setzt Mumla nicht selbst; genau deshalb setzt der Laufzeit-Abgleich sie serverseitig. Aeltere Fassungen melden nur das alte version-Feld, weshalb im Cockpit version2 bevorzugt und auf version zurueckgefallen wird.
  • Mumble iOS – PTT und Kanalwechsel; Funktionsumfang liegt zwischen den beiden.

Verhalten bei einem Serverneustart

Faellt murmur weg, bleibt das Cockpit stehen: /healthz liefert weiter 200 (sonst wuerde der Docker-Healthcheck den Admin-Container wegen eines fremden Dienstes neu starten, und beide kreisen umeinander), die Seiten zeigen den letzten bekannten Stand, und ein Banner nennt den Grund. Die Verbindung wird im Hintergrund mit wachsendem Abstand erneut versucht.

Nach dem Wiederverbinden wird nicht erneut provisioniert. PROVISION_ON_START heisst Containerstart, nicht Serverneustart. Ein Netzaussetzer waehrend des Wettkampfs darf nicht dazu fuehren, dass die ACLs neu geschrieben werden und dabei eine bewusste Aenderung von vor fuenf Minuten verlorengeht. Ist die Serverdatenbank tatsaechlich weg, zeigt der Testlauf der zuletzt geladenen Show die Abweichung sofort — „Laden“ holt den Zustand zurueck.

Abgesichert durch test_ueberlebt_einen_serverneustart_und_verbindet_neu.

Slice- und Versionsabgleich

Beim Start werden zwei Dinge geprueft: Meta.getVersion() gegen MUMBLE_VERSION, und zusaetzlich die Slice-Pruefsummen (Meta.getSliceChecksums() gegen Ice.sliceChecksums). Letzteres erkennt auch einen Schnittstellenbruch innerhalb derselben Versionsnummer. Abweichungen erscheinen als Banner im Cockpit und als Warnung im Log — sie verhindern den Start nicht: ein Container, der deswegen nicht hochkommt, hilft waehrend einer laufenden Veranstaltung niemandem.


Fehlersuche

„Keine Verbindung zur Ice-Schnittstelle"

docker compose logs --tail 80 mumble-server
docker compose exec mumble-admin intercom status

Der Reihe nach pruefen:

  1. Laeuft der Server? docker compose ps
  2. Ist Ice ueberhaupt an? In der Serverkonfiguration muessen ice und icesecretwrite gesetzt sein. In der Compose sind das MUMBLE_CONFIG_ICE und MUMBLE_CONFIG_ICESECRETWRITE. Die erzeugte ini-Zeile muss so aussehen:
    ice="tcp -h 127.0.0.1 -p 6502"
    
  3. Ist der Port offen? timeout 2 bash -c '</dev/tcp/127.0.0.1/6502' && echo offen
  4. Beide im Host-Netz? Steht bei einem der Dienste kein network_mode: host, funktionieren die Callbacks nicht.

„murmur hat das Ice-Secret abgelehnt"

ICE_SECRET in der .env passt nicht zu icesecretwrite im Server. Nach jeder Aenderung beide Container neu starten:

docker compose up -d --force-recreate

Das Secret laesst sich absichtlich nicht ueber das GUI aendern — danach waere die eigene Verbindung sofort tot.

Versionsabweichung im Banner

docker exec mumble-server mumble-server --version

MUMBLE_VERSION in der .env auf v<version> setzen und das Admin-Image neu bauen:

docker compose up -d --build mumble-admin

./setup.sh macht das von selbst.

Rechte auf ./server oder ./admin-data

Der Mumble-Server laeuft im Image als UID/GID 10000; das Admin-Image legt denselben Benutzer an.

sudo chown -R 10000:10000 ./server ./admin-data

Symptome: der Server startet und beendet sich sofort wieder, oder das Cockpit zeigt das Banner „/data/history.sqlite ist nicht benutzbar" (dann laeuft das GUI weiter, nur ohne Verlauf und Audit-Log).

Kein Paketverlust in der Tabelle

Die Spalte zeigt –, solange der Monitor-Bot keine Werte liefert. Moegliche Gruende:

  1. MONITOR_BOT_ENABLED=false.

  2. Der Bot ist nicht verbunden — im Cockpit oben rechts sichtbar, Fehlertext in der Kachel „Monitor-Bot".

  3. Der Bot hat zu wenig Rechte — Kachel „Messung“ zeigt dann eingeschraenkt. Server::msgUserStats (murmur 1.5.735) fuellt die Paketzaehler nur, wenn der Fragende im selben Kanal steht oder Register am obersten Platz hat:

    bool extend = (uSource == pDstServerUser)
                  || hasPermission(uSource, qhChannels.value(0), ChanACL::Register);
    bool local  = extend || (pDstServerUser->cChannel == uSource->cChannel);

    Die Anwendung setzt dafuer selbst eine Regel fuer den Zertifikats-Hash des Bots (in der Fachsicht als „Monitor-Bot“ beschriftet); Shows und Aufraeumen lassen sie stehen. Steht dort trotzdem eingeschraenkt, nimmt eine spaetere Regel am obersten Platz Register wieder weg — oder Ice ist nur lesend angebunden. Siehe DECISIONS.md, D-035 (und D-015 fuer den frueheren, falschen Stand mit Ban).

  4. Ein Client laeuft nur ueber TCP: dessen UDP-Zaehler bleiben auf 0. Das Cockpit zeigt dann – statt 0,0 % — „unbekannt" ist die richtige Aussage, und die Alarmschwelle darf darauf nicht anschlagen.

Dasselbe gilt fuer den Verlauf: die Sparkline „Verlust" im Detailpanel zeigt in solchen Zeitraeumen eine Unterbrechung, keine Nulllinie. In der Datenbank steht dort NULL. Der Unterschied ist der ganze Punkt — „kein Verlust" ist eine Entwarnung, „nicht gemessen" ist keine. Eine Messung gilt nach 60 s als veraltet (LiveState.STATS_MAX_AGE_S); danach faellt die Anzeige zurueck auf –, und weder Alarmbalken noch /metrics melden noch etwas. Auch das ist Absicht: ein Wert von vor zehn Minuten sieht aus wie eine Messung, ist aber eine Erinnerung.

SSE bleibt stehen / Cockpit aktualisiert nicht

Ohne Reverse Proxy tritt das nicht auf. Setzt jemand spaeter einen davor, ist Pufferung die erste Verdaechtige: die Anwendung schickt X-Accel-Buffering: no und Cache-Control: no-cache, aber manche Konfigurationen ueberschreiben das (bei nginx hilft proxy_buffering off;). Zum Eingrenzen direkt am Port testen, am Proxy vorbei:

curl -N http://127.0.0.1:8080/api/events   # nach Anmeldung

Kommen dort laufend event: state-Zeilen an, liegt es am Proxy, nicht an der Anwendung.

Provisionierung schlaegt fehl

intercom plan zeigt jede Aenderung einzeln mit Vorher/Nachher. Fehlgeschlagene Aenderungen stehen mit Fehlertext im Report — ein apply bricht nicht beim ersten Fehler ab, sondern macht weiter und meldet am Ende alles.

Haeufigster Fall: „Nicht registriert: …". Diese Nutzer haben keine ID und koennen darum in keiner Rolle sein. Auf der Seite „Personen" registrieren (verbundene Clients per Knopf mit ihrem aktuellen Zertifikat).


Entwicklung und Tests

cd admin
python3.11 -m pip install -e ".[dev,ice]"   # ice nur ohne python3-zeroc-ice
./scripts/build_slice.sh v1.5.735 slice     # Slice holen und uebersetzen
python -m pytest -q                          # gut 340 Tests; die gegen den echten Server werden ohne ihn uebersprungen
python -m ruff check .
python -m mypy intercom

Zwei Teststufen

1. Gegen ein murmur-Doppel (laeuft ueberall). tests/fake_murmur.py spricht echtes Ice — eigener Objektadapter, echte Proxies, echte Serialisierung, echte Rueckrufe. Nachgebildet ist die Semantik aus MumbleServerIce.cpp und ACL.cpp: setACL ersetzt vollstaendig, getACL liefert geerbte Eintraege markiert mit, Gruppen arbeiten mit Nutzer-IDs, Listener haengen an der Session, allow/deny werden gegen ChanACL::All maskiert.

2. Gegen einen echten Server (optional).

docker compose -f docker-compose.test.yml up -d
cd admin && python -m pytest -m integration -v
docker compose -f docker-compose.test.yml down -v

Diese Tests pruefen das, was ein Doppel nicht kann — vor allem, ob unsere Lesart des murmur-Quelltextes stimmt: ueberlebt Listen (0x800) einen echten setACL-Umlauf, wird ein Bit ausserhalb von ChanACL::All wirklich wegmaskiert, ist Gruppenmitgliedschaft ueber setACL tatsaechlich dauerhaft. Ohne erreichbaren Testserver werden sie uebersprungen.

Sie sind gegen murmur 1.5.735 ausgefuehrt worden und laufen durch. Dabei gefunden und behoben: eine unbrauchbare Variable in docker-compose.test.yml (MUMBLE_CONFIG_LOGLEVEL gibt es nicht — der Testserver startete nicht), die verdrehte Konfigurationsansicht und zwei Exporter-Fehler (siehe DECISIONS.md, D-023 bis D-025). Ein Doppel haette keinen davon gezeigt.

Hinweis zum Netz. In der Umgebung, in der dieser Code entstanden ist, ist production.cloudfront.docker.com — der Layer-Auslieferer von Docker Hub — von der Egress-Richtlinie gesperrt (CONNECT → 403), waehrend auth.docker.io und registry-1.docker.io antworten. Ein docker pull gegen Docker Hub scheitert deshalb beim Herunterladen der Layer. Bau und Tests liefen ueber den Spiegel mirror.gcr.io:

docker pull mirror.gcr.io/mumblevoip/mumble-server:v1.5.735
docker tag  mirror.gcr.io/mumblevoip/mumble-server:v1.5.735 \
            mumblevoip/mumble-server:v1.5.735
docker build --build-arg BASE_IMAGE=mirror.gcr.io/library/debian:bookworm-slim ...

Auf einem normalen Netz ist das nicht noetig: dort genuegen die Vorgaben.

Warum der Live-Strom nicht ueber den TestClient geprueft wird

Starlettes TestClient wartet, bis eine Antwort vollstaendig ist. Ein SSE-Strom endet nie von allein — client.stream("/api/events") haengt also fuer immer. Das ist eine Eigenheit des Testwerkzeugs, kein Fehler der Anwendung. Geprueft werden deshalb die Route direkt (erster Rahmen, Kopfzeilen) und der Verteiler als Einheit (Verwerfen alter Rahmen bei einem eingefrorenen Browser).


Weiterfuehrend

  • DECISIONS.md – warum etwas so gebaut ist, mit Belegstellen im Mumble-Quelltext.
  • /metrics – Prometheus-Format: Ping, Verlust, Bandbreite und Online-Zeit je Client, Nutzerzahl je Kanal, Server-Laufzeit, offene Alarme. Ohne Anmeldung, damit ein Prometheus im Homelab es abholen kann.
  • /healthz – Zustandsbericht fuer den Docker-Healthcheck. Enthaelt bewusst keine Secrets.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages