unRAID Docker: GUID und PGID erklärt

Was sind GUID und PGID?

GUID (Group User Identifier) und PGID (Primary Group Identifier) sind Unix-basierte Kennungen, die festlegen, welcher Benutzer und welche Gruppe auf welche Dateien und Verzeichnisse zugreifen können.
GUID: Dies ist die Benutzer-ID (User Identifier, UID), die angibt, welcher Benutzer einem Prozess zugeordnet ist. Jeder Benutzer im System hat eine eindeutige GUID.
PGID: Dies ist die Gruppen-ID (Group Identifier, GID), die eine Gruppe von Benutzern repräsentiert. Durch die Gruppenmitgliedschaft wird festgelegt, welche Rechte Benutzer innerhalb einer Gruppe auf bestimmte Dateien haben.

In einem Docker-Container legst du fest, mit welcher GUID und PGID der Container arbeiten soll, um sicherzustellen, dass der Container die richtigen Rechte hat, um auf Dateien im Host-System zuzugreifen.

Warum sind PGID und GUID wichtig in Docker?

In Docker-Containern laufen Anwendungen oft isoliert vom Host-System. Damit der Container jedoch auf Dateien oder Verzeichnisse des Host-Systems zugreifen kann, müssen die Benutzer- und Gruppenrechte zwischen dem Host und dem Container korrekt abgeglichen sein.

Berechtigungsprobleme: Wenn der Benutzer oder die Gruppe, unter der der Container läuft, nicht die richtigen Rechte hat, können Anwendungen im Container keine Dateien erstellen, lesen oder ändern, was zu Fehlfunktionen führen kann.
Sicherheitsaspekt: Durch die Zuordnung von spezifischen GUIDs und PGIDs kannst du sicherstellen, dass Container nur auf die Dateien zugreifen, auf die sie zugreifen dürfen.

PGID und GUID in Unraid mit Docker

Auf einem Unraid-Server wird Docker oft genutzt, um Anwendungen wie Plex, Nextcloud oder Jellyfin auszuführen. Diese Anwendungen müssen in der Regel auf freigegebene Verzeichnisse zugreifen, um Medien oder andere Dateien zu speichern oder zu verarbeiten. Dabei ist es wichtig, dass die Docker-Container dieselben Benutzer- und Gruppenrechte wie der Host-Server verwenden.

So findest du die richtige GUID und PGID in Unraid:

Öffne das Unraid-Terminal: Gehe auf deinem Unraid-Server ins Terminal.
GUID des Benutzers herausfinden: Führe den Befehl id [benutzername] aus, um die Benutzer- und Gruppen-ID eines Benutzers zu sehen. Wenn dein Benutzer z.B. nobody ist, sieht der Befehl so aus:

   id nobody

Das Ergebnis zeigt dir die UID (GUID) und GID (PGID) des Benutzers:

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

Einrichtung der Docker-Umgebung: Wenn du einen neuen Docker-Container aufsetzt, gibst du diese GUID und PGID als Umgebungsvariablen im Docker-Template oder in der Docker-Compose-Datei an. Das sieht zum Beispiel so aus:

   environment:
     - PUID=99
     - PGID=100

Dadurch wird sichergestellt, dass der Container als der Benutzer nobody und die Gruppe users ausgeführt wird, was Berechtigungsprobleme mit Host-Verzeichnissen vermeidet.

Warum PUID und PGID auf Unraid sinnvoll sind

Die Konfiguration der PUID und PGID in Docker-Containern auf einem Unraid-Server hat mehrere Vorteile:

Richtige Berechtigungen: Du stellst sicher, dass deine Docker-Container die richtigen Berechtigungen haben, um Dateien im Host-System zu lesen und zu schreiben.
Vermeidung von Fehlern: Falsche Berechtigungen führen oft zu Fehlern wie “Permission denied”. Wenn du PUID und PGID richtig einstellst, vermeidest du solche Probleme.
Konsistenz zwischen Host und Container: Da die Container dieselben Benutzer- und Gruppenrechte wie der Unraid-Host verwenden, kannst du nahtlos auf Dateien zugreifen, egal ob du sie über den Container oder direkt über das Host-System verwendest.

Warum gibt man Docker eine PUID und GUID?

Das Zuweisen von PUID (Benutzer-ID) und PGID (Gruppen-ID) in Docker-Containern auf einem Unraid-Server ist notwendig, um sicherzustellen, dass der Container auf die Dateien und Verzeichnisse des Host-Systems zugreifen kann, ohne auf Berechtigungsprobleme zu stoßen. Dies liegt daran, dass jeder Prozess im Linux-Dateisystem als spezifischer Benutzer und Gruppe ausgeführt wird, und Dateien sowie Verzeichnisse Zugriffsrechte haben, die sich auf die UID (Benutzer) und GID (Gruppe) beziehen.

Warum ist PUID und PGID wichtig?

Benutzerrechte und Sicherheit: Auf einem Unraid-Server (oder jedem anderen Linux-basierten System) bestimmen die Dateisystemrechte, welcher Benutzer oder welche Gruppe Lese-, Schreib- oder Ausführungszugriff auf Dateien und Verzeichnisse hat. Durch das Festlegen von PUID und PGID in einem Docker-Container stellst du sicher, dass der Container die Berechtigungen eines bestimmten Benutzers und einer Gruppe auf dem Host übernimmt. So kann der Container korrekt auf Dateien zugreifen und Änderungen vornehmen, ohne dabei Berechtigungsprobleme oder Sicherheitsrisiken zu erzeugen.
Vermeidung von Berechtigungsfehlern: Ohne die richtige PUID und PGID könnte ein Docker-Container versuchen, als ein nicht existierender oder nicht berechtigter Benutzer auf Dateien zuzugreifen, was zu Fehlermeldungen wie „Permission denied“ führt. Dies kann dazu führen, dass der Container Dateien nicht lesen, schreiben oder erstellen kann.
Sicherheitskontrolle: Das Zuweisen einer spezifischen PUID und PGID gibt dir mehr Kontrolle darüber, welche Container auf welche Dateien zugreifen dürfen. Du kannst Container auf bestimmte Benutzer und Gruppen einschränken und so verhindern, dass sie auf unerwünschte Datenbereiche zugreifen.

Welche Rechte braucht der zugehörige Benutzer, um auf Pfade zuzugreifen?

Damit ein Docker-Container erfolgreich auf bestimmte Dateien und Verzeichnisse im Unraid-Dateisystem zugreifen kann, müssen die zugehörigen Benutzer- und Gruppenrechte korrekt gesetzt sein. Die Rechte, die der Benutzer im Host-System benötigt, hängen von den Aktionen ab, die der Container ausführen soll:

Lesezugriff (Read): Wenn der Container nur Dateien lesen soll (z.B. ein Medienserver, der auf Dateien wie Filme oder Musik zugreift), benötigt der zugewiesene Benutzer mindestens Lesezugriff auf die betreffenden Verzeichnisse. Das wird durch das r-Recht im Linux-Dateisystem definiert.
Schreibzugriff (Write): Wenn der Container Dateien ändern oder neue Dateien erstellen soll (z.B. ein Nextcloud-Container, der Daten hochlädt oder synchronisiert), braucht der zugewiesene Benutzer Lese- und Schreibzugriff (rw) auf die relevanten Pfade. Ohne Schreibrechte kann der Container keine Daten verändern oder erstellen.
Ausführungszugriff (Execute): Wenn der Container Programme oder Skripte ausführen muss, benötigt der Benutzer außerdem Ausführungsrechte (x) auf das betreffende Verzeichnis oder die Datei. Dies ist oft bei Containern erforderlich, die bestimmte Anwendungen oder Prozesse innerhalb von Verzeichnissen starten müssen.
Gruppenberechtigungen: Wenn du möchtest, dass mehrere Container oder Benutzer auf dieselben Dateien zugreifen, kannst du durch die PGID sicherstellen, dass Benutzer, die zur selben Gruppe gehören, dieselben Berechtigungen haben. Dies ist besonders nützlich in Multi-User-Umgebungen oder wenn mehrere Container auf dieselben Ressourcen zugreifen müssen.

Beispiel: Docker-Container mit PUID und PGID

Angenommen, du betreibst einen Plex Media Server auf deinem Unraid-Server. Plex muss auf deine Mediendateien (Filme, Serien, Musik) zugreifen, um sie an deine Geräte zu streamen. Wenn du Plex als Docker-Container ausführst, musst du sicherstellen, dass der Container auf das Verzeichnis mit deinen Mediendaten zugreifen kann.

Finde die PUID und PGID des Unraid-Benutzers, der auf die Mediendateien zugreifen kann (z.B. Benutzer nobody):

   id nobody

Das Ergebnis zeigt dir z.B. PUID=99 und PGID=100.

In der Docker-Compose-Datei oder im Unraid Docker-Template gibst du diese PUID und PGID als Umgebungsvariablen an:

   environment:
     - PUID=99
     - PGID=100

Dadurch wird der Plex-Container als der Benutzer nobody mit den Gruppenrechten users ausgeführt, was ihm Zugriff auf die Mediendateien gewährt.

Stelle sicher, dass die Berechtigungen für die Mediendateien korrekt gesetzt sind:

   chmod -R 755 /mnt/user/mediendaten

Hierbei erhält der Benutzer nobody Lese-, Schreib- und Ausführungszugriff auf das Verzeichnis und seine Dateien.

Zusammenfassung

Die Einrichtung von PUID und PGID in Docker-Containern ist auf einem Unraid-Server essenziell, um sicherzustellen, dass Berechtigungen korrekt gesetzt sind und deine Container reibungslos arbeiten können. Indem du die Benutzer- und Gruppen-IDs des Unraid-Systems mit den entsprechenden Werten im Docker-Container abgleichst, stellst du sicher, dass Dateien und Verzeichnisse korrekt gehandhabt werden und es zu keinen Berechtigungsproblemen kommt.

Durch das Einrichten der richtigen PGID und GUID vermeidest du typische Fehler wie Zugriffsverweigerungen und stellst sicher, dass dein Unraid-Server optimal mit Docker-Containern zusammenarbeitet.