unRAID Docker: GUID und PGID erklärt

unRAID Docker und die beiden Kennungen GUID (genauer: PUID, die Benutzer-ID) und PGID (die Gruppen-ID) entscheiden darüber, ob deine Container sauber auf Dateien im Host zugreifen oder ständig an „Permission denied“ scheitern. Wer Anwendungen wie Plex, Nextcloud oder Jellyfin per Docker betreibt, kommt an diesen Werten nicht vorbei. In diesem Guide erklären wir, was PUID und PGID bedeuten, warum sie in Docker so wichtig sind und wie du sie in unRAID Schritt für Schritt korrekt einrichtest, um Berechtigungsprobleme dauerhaft zu vermeiden.

Was bedeuten GUID (PUID) und PGID?

Beide Werte stammen aus der Rechteverwaltung von Linux. Jeder Prozess läuft dort unter einem bestimmten Benutzer und einer bestimmten Gruppe, und genau daran hängen die Zugriffsrechte auf Dateien und Verzeichnisse.

PUID (oft umgangssprachlich „GUID“ genannt) ist die User-ID (UID). Sie legt fest, als welcher Benutzer ein Prozess bzw. Container ausgeführt wird. Jeder Benutzer im System besitzt eine eindeutige UID.
PGID ist die Gruppen-ID (GID). Sie steht für eine Gruppe von Benutzern und bestimmt, welche Rechte alle Mitglieder dieser Gruppe auf bestimmte Dateien haben.

In einem Docker-Container gibst du PUID und PGID als Umgebungsvariablen an. Der Container übernimmt damit die Identität eines Host-Benutzers und erhält exakt dessen Zugriffsrechte. Wenn dir die Docker-Grundlagen dazu noch fehlen, hilft dir vorab unser Überblick Was ist Docker? weiter.

Warum sind PUID und PGID in Docker wichtig?

Anwendungen in Docker-Containern laufen isoliert vom Host. Sobald ein Container aber auf freigegebene Verzeichnisse zugreifen soll, müssen die Benutzer- und Gruppenrechte zwischen Host und Container zusammenpassen. Genau das leisten PUID und PGID.

Berechtigungsprobleme vermeiden: Passt die ID nicht, kann der Container Dateien weder anlegen noch lesen oder ändern – typischerweise endet das mit der Fehlermeldung „Permission denied“.
Konsistenz zwischen Host und Container: Nutzt der Container dieselben IDs wie unRAID, greifst du auf dieselben Dateien nahtlos zu – egal ob über den Container oder direkt am Host.
Mehr Sicherheit: Über gezielte PUID/PGID schränkst du ein, auf welche Daten ein Container überhaupt zugreifen darf.

Siehe auch Speicherplatz unter Linux analysieren: df, du & ncdu

PUID und PGID in unRAID herausfinden

Auf einem unRAID-Server laufen Docker-Container häufig für Medien- und Cloud-Dienste, die auf gemeinsame Shares zugreifen. Bevor du einen Container einrichtest, brauchst du die richtigen IDs des Host-Benutzers. So gehst du vor:

Terminal öffnen: Öffne auf deinem unRAID-Server das Web-Terminal (Icon oben rechts) oder verbinde dich per SSH.
ID des Benutzers auslesen: Mit dem Befehl id [benutzername] siehst du UID und GID. Für den Standardbenutzer nobody sieht das so aus:

id nobody

Die Ausgabe zeigt dir UID (also die PUID) und GID (die PGID) des Benutzers:

uid=99(nobody) gid=100(users)

In diesem Standardfall lautet die PUID also 99 und die PGID 100. Diese beiden Werte nutzt du gleich im Docker-Container.

PUID und PGID im Docker-Container setzen

Beim Anlegen eines neuen Containers trägst du die ermittelten Werte als Umgebungsvariablen ein – entweder im unRAID Docker-Template oder in einer Docker-Compose-Datei. Für die verbreiteten LinuxServer-Images sieht das so aus:

environment:
  - PUID=99
  - PGID=100

Damit läuft der Container als Benutzer nobody mit der Gruppe users – genau die Kombination, die auf unRAID Zugriff auf die Shares hat. Berechtigungskonflikte mit Host-Verzeichnissen gehören so der Vergangenheit an.

Dateiberechtigungen auf dem Host prüfen

Die richtigen IDs allein reichen nicht – das Zielverzeichnis muss dem Benutzer auch tatsächlich die passenden Rechte einräumen. Welche Rechte nötig sind, hängt davon ab, was der Container tun soll:

Lesen (r): Ein reiner Medienserver, der nur Filme oder Musik streamt, braucht mindestens Lesezugriff auf die Verzeichnisse.
Schreiben (w): Dienste wie Nextcloud, die Dateien hochladen oder synchronisieren, benötigen zusätzlich Schreibrechte (rw).
Ausführen (x): Muss der Container in ein Verzeichnis wechseln oder Skripte starten, braucht der Benutzer auch das Ausführungsrecht auf den Ordner.

Siehe auch Docker Container automatisch aktualisieren mit Watchtower

Ein passendes Rechteschema setzt du bei Bedarf mit chmod. Für ein Medienverzeichnis, auf das der Benutzer lesend, schreibend und ausführend zugreifen soll, sieht das so aus:

chmod -R 755 /mnt/user/mediendaten

Auf unRAID solltest du Berechtigungen für Shares im Zweifel aber über das mitgelieferte Tool „New Permissions“ (Tools → New Permissions) setzen, statt tief in einzelne Ordner einzugreifen. Wie sich die Rechtevergabe je nach Speicher unterscheidet, hängt auch vom gewählten Dateisystem ab – ein Vergleich dazu steht in unserem Guide Bestes Dateisystem für unRAID.

Praxisbeispiel: Plex auf unRAID mit PUID und PGID

Angenommen, du betreibst einen Plex Media Server als Docker-Container und Plex soll auf deine Mediendateien zugreifen. Der komplette Ablauf in drei Schritten:

PUID und PGID des Host-Benutzers ermitteln, der Zugriff auf die Medien hat – per id nobody erhältst du typischerweise PUID=99 und PGID=100.
Diese Werte im Docker-Template bzw. in der Compose-Datei als PUID und PGID eintragen (siehe Beispiel oben).
Prüfen, dass der Media-Share dem Benutzer nobody/der Gruppe users gehört und die passenden Lese- bzw. Schreibrechte besitzt.

Danach startet Plex als Benutzer nobody mit den Gruppenrechten users und kann deine Filme und Serien zuverlässig einlesen und streamen – ohne Zugriffsfehler.

Häufige Fehler und Tipps

Falsche Variablennamen: Achte auf PUID und PGID (nicht UID/GID). Viele Images werten ausschließlich diese Namen aus.
Abweichende IDs: Nutzt du einen eigenen Benutzer statt nobody, prüfe dessen ID immer per id. Nicht jedes System verwendet 99/100.
Zu weite Rechte: Setze nicht pauschal 777. Das öffnet unnötige Sicherheitslücken – 755 oder 775 reichen meist aus.

Siehe auch Proxmox GPU Passthrough einrichten – Anleitung (VFIO)

Fazit

PUID und PGID sind der Schlüssel für reibungslose Docker-Container auf unRAID. Wenn du die Benutzer- und Gruppen-IDs des Hosts korrekt ausliest und im Container hinterlegst, greifen deine Anwendungen sauber auf die freigegebenen Verzeichnisse zu – ganz ohne „Permission denied“. Ein kurzer Blick mit id, die passenden Werte im Template und korrekt gesetzte Ordnerrechte genügen, damit Plex, Nextcloud, Jellyfin und Co. dauerhaft zuverlässig laufen.

Häufige Fragen (FAQ)

Was ist der Unterschied zwischen GUID, PUID und UID?

Technisch gibt es die UID (User-ID) und die GID (Gruppen-ID). In der unRAID- und Docker-Welt heißen die zugehörigen Umgebungsvariablen PUID und PGID. „GUID“ wird umgangssprachlich oft für die PUID verwendet, meint aber dasselbe: die Benutzer-ID, unter der der Container läuft.

Welche PUID und PGID hat unRAID standardmäßig?

Der Standardbenutzer nobody hat auf unRAID die PUID 99, die Gruppe users die PGID 100. Prüfe das im Zweifel mit id nobody direkt auf deinem Server.

Warum bekomme ich trotz PUID/PGID „Permission denied“?

Meist stimmen zwar die IDs, aber die Ordnerrechte auf dem Host passen nicht. Prüfe Eigentümer und Rechte des Zielverzeichnisses und korrigiere sie über „New Permissions“ in unRAID oder gezielt per chmod/chown.

Muss ich PUID und PGID für jeden Container setzen?

Nur Images, die diese Variablen unterstützen (etwa die LinuxServer-Images), werten sie aus. Bei solchen Containern solltest du sie immer setzen, damit Dateien mit den erwarteten Rechten angelegt werden. Andere Images ignorieren die Variablen einfach.

Kann ich einen eigenen Benutzer statt nobody verwenden?

Ja. Lege den Benutzer an, ermittle seine ID mit id benutzername und trage die entsprechenden Werte als PUID und PGID ein. Wichtig ist nur, dass dieser Benutzer die nötigen Rechte auf die betroffenen Shares hat.