PKR-Lab

30040 - MediaMTX — Live-Streaming (RTMP/RTSP → HLS)

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/30040-mediamtx.md

MediaMTX — Live-Streaming (RTMP/RTSP → HLS)

Cluster: TECH · Ordner argocd/apps/tech/mediamtx/ · URL https://stream.prod.homeserver und https://stream-prod.pke-lab.de. kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

MediaMTX ist ein selbst-gehosteter
Streaming-Server: Encoder (Kamera, OBS, ffmpeg) publishen ein Live-Signal
per RTMP oder RTSP, MediaMTX macht es intern als HLS und WebRTC verfügbar,
Zuschauer schauen es im Browser.

Sicherheitsmodell dieses Setups — zwei getrennte Zugriffsrichtungen:

Richtung Protokoll Zugriff Absicherung
Publish (Kamera/OBS → Server) RTMP/RTSP Nur LAN/Tailnet (NodePort) mediamtx interne Auth — Nutzername/Passwort im Stream-URL
Read (Zuschauer → Server) HLS (HTTP) Intern (stream.prod.homeserver) + öffentlich über Cloudflare Tunnel (stream.pke-lab.de) mediamtx interne Auth — HTTP-Basic-Auth-Dialog im Browser

Beide Mechanismen laufen komplett lokal in mediamtx (authMethod: internal, siehe mediamtx-Doku)
— kein externer Identity-Provider, kein OAuth-Provider, kein JWKS-Endpunkt
nötig. Passwörter werden nur als SHA256-Hash in der Konfiguration
hinterlegt, nie im Klartext.

                    LAN / Tailnet only (NodePort 31935/31554)
OBS / ffmpeg / Kamera ───────────────────────────────────────▶ mediamtx (RTMP/RTSP)
   rtmp://streamer:<passwort>@...                                  │
                                                                    │ intern
                                                                    ▼
                                                              HLS (Port 8888)
                                                                    │
                                              ┌─────────────────────┴─────────────────────┐
                                              ▼                                           ▼
                                https://stream.prod.homeserver                    https://stream.pke-lab.de
                                  HTTP-Basic-Auth (mediamtx)              (Cloudflare Tunnel, HTTP-Basic-Auth)

Inhaltsverzeichnis

  1. Voraussetzungen
  2. Warum Publish nicht über Cloudflare läuft
  3. Schritt 1 — Chart deployen
  4. Schritt 2 — Zugangsdaten generieren
  5. Schritt 3 — Streamen (OBS/ffmpeg)
  6. Verifizierung
  7. Aufnahmen (optional)
  8. Skalierung (HPA)
  9. Troubleshooting
  10. Rollback

Voraussetzungen

Kein zusätzlicher Identity-Provider nötig — mediamtx
verwaltet Publish- und Zuschauer-Zugang komplett selbst.


Warum Publish nicht über Cloudflare läuft

RTMP/RTSP sind reine TCP-Protokolle ohne HTTP-Host-Header — Cloudflare
Tunnel kann sie zwar grundsätzlich als generischen TCP-Stream tunneln, aber
ohne den HTTP-Layer greift keine hostnamenbasierte Routing-Regel. Ein offen
ins Internet getunnelter RTMP-Port wäre nur durch das Stream-Passwort
geschützt — ein System, das in diesem Repo konsequent vermieden wird (siehe
capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md → Sicherheitsprinzipien).

Stattdessen bleibt Publish wie ArgoCD/Semaphore/Headlamp strikt
LAN/Tailnet-only (NodePort, siehe
README.md#networking--security) —
wer streamen will, braucht ohnehin Tailscale oder ist im Heimnetz. Die
eigentliche Autorisierung innerhalb dieses vertrauenswürdigen Netzes
übernimmt mediamtx' interne Auth (Schritt 2): Netzwerkzugriff allein reicht
nicht, ohne gültiges Nutzername/Passwort-Paar lehnt mediamtx den Publish ab.


Schritt 1 — Chart deployen

Der Chart liegt bereits unter argocd/apps/tech/mediamtx/ (Helm-Chart, analog zu
ntfy/cloudflared). Relevante Werte in
argocd/apps/tech/mediamtx/values.yaml:

publishService:
  ports:
    rtmp: { port: 1935, nodePort: 31935 }
    rtsp: { port: 8554, nodePort: 31554 }

auth:
  streamer:
    user: "sha256:CHANGEME"
    pass: "sha256:CHANGEME"
  viewer:
    user: "sha256:CHANGEME"
    pass: "sha256:CHANGEME"

Die CHANGEME-Platzhalter sind absichtlich ungültige Hashes — Publish und
Playback sind damit standardmäßig für niemanden erreichbar, bis in
Schritt 2 echte Hashes eingetragen werden.

Committen und pushen (wie jede andere App in diesem Repo, siehe
capulus-core/b-kubernetes-gitops/b0010-argocd.md):

git add argocd/apps/tech/mediamtx capulus-core/3-apps-workloads/30040-mediamtx.md
git commit -m "feat(mediamtx): add live-streaming server with internal auth"
git push

ArgoCD legt die Application mediamtx im gleichnamigen Namespace an und
synct automatisch (~3 Minuten, wie in
capulus-core/e-externe-erreichbarkeit/e0010-cloudflare-deploy.md → Erstdeployment
beschrieben).

ssh [email protected] 'sudo kubectl -n mediamtx get pods,svc'

Schritt 2 — Zugangsdaten generieren

mediamtx unterstützt gehashte Zugangsdaten direkt in der Konfiguration
(sha256:<Base64-Hash> für Nutzername und Passwort) — kein Klartext,
keine SealedSecret nötig, da ein Hash allein nutzlos ist, ohne das
Ursprungspasswort zu kennen.

2.1 — Streamer-Zugang (Publish)

Wichtig: Das Streamer-Passwort landet bei RTMP unverändert (ohne
URL-Encoding) in einer Query-String (?user=...&pass=..., siehe
Schritt 3) — weder OBS noch mediamtx kodieren das automatisch.
Sonderzeichen wie &, @, %, #, Leerzeichen oder gar
Steuerzeichen (z. B. aus manchen Passwort-Managern) führen zu einem
Parse-Fehler und die Verbindung schlägt fehl (siehe Troubleshooting).
Nur alphanumerische Zeichen verwenden, z. B. generiert mit:

openssl rand -hex 20

Für den Zuschauer-Zugang (2.2) gilt diese Einschränkung nicht — der läuft
über HTTP-Basic-Auth, die codiert automatisch.

echo -n "<streamer-username>" | openssl dgst -binary -sha256 | openssl base64
echo -n "<streamer-passwort>" | openssl dgst -binary -sha256 | openssl base64

Beide Ausgaben mit sha256:-Präfix in
argocd/apps/tech/mediamtx/values.yaml
unter auth.streamer.user / auth.streamer.pass eintragen.

2.2 — Zuschauer-Zugang (Read/Playback)

Gleiches Vorgehen für auth.viewer.user / auth.viewer.pass:

echo -n "<viewer-username>" | openssl dgst -binary -sha256 | openssl base64
echo -n "<viewer-passwort>" | openssl dgst -binary -sha256 | openssl base64

Für mehrere Zuschauer mit unterschiedlichen Passwörtern: den viewer-
Eintrag in authInternalUsers
(templates/configmap.yaml)
um weitere Einträge mit action: read / action: playback ergänzen —
analog zum bestehenden Muster, ein Eintrag pro Person.

Committen, pushen — ArgoCD synct die neue ConfigMap, mediamtx lädt sie
automatisch neu (Pod-Neustart per checksum/config-Annotation im
Deployment).


Schritt 3 — Streamen (OBS/ffmpeg)

Server-Adresse: <server-ip> = die LAN- oder Tailscale-IP des Home-Servers
(siehe capulus-core/c-netzwerk-dns/c0010-tailscale.md).

RTMP (OBS):

RTMP kennt kein user:pass@host in der URL (anders als RTSP) — mediamtx
nimmt die Zugangsdaten bei RTMP stattdessen als Query-Parameter entgegen.
Die gehören an den Stream-Key, nicht an die Server-URL:

Der eigentliche Pfad ist dann live/mystream (Server-Pfad + Stream-Key,
ohne die Query-Parameter) — unter genau diesem Pfad rufst du den Stream
später zum Zuschauen ab.

RTSP/ffmpeg-Beispiel:

ffmpeg -re -i input.mp4 -c copy \
  -f rtsp "rtsp://<streamer-user>:<streamer-passwort>@<server-ip>:31554/mystream"

Ohne gültiges (oder falsches) Nutzername/Passwort-Paar lehnt mediamtx den
Publish mit einem Auth-Fehler ab — siehe Troubleshooting.


Verifizierung

Pods laufen:

ssh [email protected] 'sudo kubectl -n mediamtx get pods'

Publish testen (mit den Zugangsdaten aus Schritt 2.1):

ffmpeg -re -i input.mp4 -c copy \
  -f rtsp "rtsp://<streamer-user>:<streamer-passwort>@<server-ip>:31554/test"

Playback intern:

Browser → https://stream.prod.homeserver/test → mediamtx fragt per
HTTP-Basic-Auth-Dialog nach den Zugangsdaten aus Schritt 2.2, danach der
eingebaute HLS-Player.

Playback extern (über Mobilfunknetz, NICHT über Heimnetz/Tailscale
testen):

https://stream.pke-lab.de/test

Erwartet: derselbe Basic-Auth-Dialog, nach korrekten Zugangsdaten der
HLS-Player mit dem Live-Stream.

Publish ohne/mit falschem Passwort wird abgelehnt:

ffmpeg -re -i input.mp4 -c copy -f rtsp "rtsp://<server-ip>:31554/test"
# Erwartet: Verbindung wird von mediamtx mit Auth-Fehler abgelehnt.

Aufnahmen (optional)

Dieses Setup speichert standardmäßig nichts — reines Live-Durchreichen.
Für Aufzeichnung auf Platte müsste paths.all_others.record: yes plus eine
PVC (analog zu argocd/apps/tech/ntfy/templates/pvc.yaml) ergänzt werden — bei
Bedarf separat einrichten, um den Speicherbedarf bewusst zu halten.


Skalierung (HPA)

Skaliert per HPA auf 1–2 Replicas (CPU 75%). Wichtig: RTMP/RTSP-Publish-
Verbindungen sind pro Pod langlebig — kube-proxy verteilt nur neue
Verbindungen über die Service-IP auf Replicas, ein bereits verbundener
Stream wandert nicht automatisch zu einem anderen Pod. Der HPA hilft also
bei vielen gleichzeitigen neuen Verbindungen/Zuschauern, nicht dabei,
einen einzelnen bestehenden Stream zu verteilen. Details für alle Apps:
../b-kubernetes-gitops/b0040-hpa-autoscaling.md.


Troubleshooting

mediamtx-Pod crasht / CrashLoopBackOff:

ssh [email protected] 'sudo kubectl -n mediamtx logs deploy/mediamtx'

Meist ein YAML-Syntaxfehler in der ConfigMap (authInternalUsers etc.) —
kubectl -n mediamtx get configmap mediamtx-config -o yaml gegenprüfen.

Publish/Playback schlägt mit Auth-Fehler fehl, obwohl Zugangsdaten
korrekt scheinen:

stream.pke-lab.de zeigt 404/502:

Prüfen, ob argocd/apps/tech/cloudflared/values.yaml den stream.pke-lab.de-
Eintrag enthält, auf mediamtx.mediamtx.svc.cluster.local:8888 zeigt und
der cloudflared-Pod die neue Config geladen hat (siehe capulus-core/e-externe-erreichbarkeit/e0010-cloudflare-deploy.md →
ConfigMap-Änderung kommt nicht im Pod
an
).

stream.pke-lab.de/stream.prod.homeserver fragt gar nicht nach Login:

OBS zeigt "Failed to connect to server":

OBS zeigt "Auf den angegebenen Kanal oder Streamschlüssel konnte nicht
zugegriffen werden":

Das ist mediamtx' generische RTMP-Fehlermeldung für so ziemlich jeden
Publish-Fehler (Auth, Parse-Fehler, doppelter Pfad, …) — sagt selbst
nichts Genaues aus. Die eigentliche Ursache steht im mediamtx-Log:

ssh [email protected] 'sudo kubectl -n mediamtx logs deploy/mediamtx --tail=50'

Typischer Befund: net/url: invalid control character in URL oder
ähnliches — dann liegt es am Streamer-Passwort (siehe Warnkasten in
Schritt 2.1). Falls das Passwort in der Log-Ausgabe im Klartext
auftaucht
(wie bei einem gescheiterten Parse-Versuch), gilt es als
kompromittiert — neues, rein alphanumerisches Passwort generieren, neu
hashen (Schritt 2.1) und in values.yaml eintragen.


Rollback

Wie jede andere App per Git-Revert:

git log --oneline -- argocd/apps/tech/mediamtx
git revert <commit-hash>
git push

Um mediamtx vorübergehend abzuschalten, ohne die App zu löschen, reicht
replicaCount: 0 in values.yaml setzen und pushen — der
stream.pke-lab.de-Hostname liefert danach mangels laufendem Backend nur
noch einen 502.