Was PUID und PGID in Docker Compose bewirken

Was PUID und PGID tatsächlich sind

PUID und PGID sind zwei Umgebungsvariablen, die bestimmte Container-Images beim Start auswerten. Docker selbst liest sie niemals aus. Es handelt sich um eine Konvention, die von linuxserver.io-Images und einigen anderen verwendet wird. Ein Image, das nicht dafür geschrieben wurde, ignoriert sie daher stillschweigend.

In einem linuxserver.io-Image gibt es einen Benutzer namens abc. Er wird beim Erstellen des Images mit der UID (Benutzer-ID) 911 und der GID (Gruppen-ID) 911 angelegt. Der Container startet als root, führt seine Init-Skripte aus, und eines dieser Skripte ändert die IDs dieses Benutzers, bevor die Anwendung startet:

groupmod -o -g "${PGID}" abc
usermod -o -u "${PUID}" abc

Das Flag -o erlaubt eine ID, die bereits an anderer Stelle verwendet wird. Anschließend gibt das Init-Skript die Berechtigungen ab und startet die Anwendung als abc. Docker übergibt PUID=1000 daher wie jede andere Umgebungsvariable an den Container und verarbeitet die Variable selbst nicht. Die Variable ändert die ID eines Benutzers im Container, bevor die Anwendung startet. Das bedeutet, dass neu erstellte Dateien auf einem standardmäßigen rootful Daemon ohne User-Namespace-Remapping normalerweise mit dem Besitzer 1000 auf Ihrer Festplatte angelegt werden. Beim Schreiben in eine vorhandene, beschreibbare Datei ändert sich deren Besitzer nicht. Rootless Docker verschiebt diese Nummer, wie weiter unten erklärt. Lassen Sie PUID nicht gesetzt, behält abc die ID 911. Deshalb füllt ein nicht konfiguriertes Bind-Mount das Dateisystem mit Dateien, deren Besitzer 911:911 ist.

Ermitteln Sie Ihre beiden IDs mit id

Führen Sie dies auf dem Host als der Benutzer aus, dem die Datenverzeichnisse gehören:

id

uid=1000(deploy) gid=1000(deploy) groups=1000(deploy),27(sudo),988(docker)

uid ist Ihre PUID und gid ist Ihre PGID. Für ein Skript geben id -u und id -g nur die Zahlen aus. Bei den meisten neuen VPS-Images lautet die Zuordnung für das erste Benutzerkonto 1000:1000. Gehen Sie davon jedoch nicht aus. Die Vergabe hängt von den vorhandenen Konten und der Konfiguration ab: Ein neu aufgesetzter Server kann erneut 1000 vergeben, während ein später angelegtes Konto eine höhere verfügbare ID erhält. Wenn Ihre Dienste unter einem dedizierten Dienstkonto statt unter Ihrem eigenen Anmeldekonto ausgeführt werden, führen Sie id thatuser aus und übernehmen Sie die dort ausgegebenen Zahlen.

Warum Ihre Dateien als 911:911 angezeigt werden

ls -l gibt eine numerische ID statt eines Namens aus, wenn kein Host-Konto zu dieser ID passt. Wenn kein Host-Konto zur UID 911 passt, gibt es keinen Namen, der ausgegeben werden kann. Verwenden Sie ls -ln, um immer die numerischen Werte anzuzeigen und die Mehrdeutigkeit zu beseitigen:

ls -ln /srv/appdata/sonarr

drwxr-xr-x 2 911 911 4096 Aug  7 09:12 Backups
-rw-r--r-- 1 911 911  512 Aug  7 09:12 config.xml

Diese Ausgabe entspricht den integrierten Standardeinstellungen des Containers. Vorhandene Dateien allein beweisen jedoch nicht, unter welchem Benutzer die Anwendung jetzt ausgeführt wird. config.xml in dieser Auflistung ist außerdem die Datei, die die Authentifizierungseinstellungen enthält. Das ist wichtig, wenn Sie die Weboberfläche zum ersten Mal öffnen und feststellen, dass Sonarr und Radarr ohne Standardbenutzername und Standardpasswort ausgeliefert werden. Prüfen Sie dies direkt im Container, statt die Einstellung zu erraten:

docker exec sonarr id abc
docker compose logs sonarr | head -n 25

Das linuxserver-Init-System gibt sein Ergebnis im Start-Log als zwei Zeilen aus:

User UID:    911
User GID:    911

Wenn diese Zeilen nach dem Setzen von PUID=1000 in Ihrer Compose-Datei 911 anzeigen, verwendet der laufende Container nicht den von Ihnen gesetzten Wert. Die häufigste Ursache ist, dass Sie docker-compose.yml bearbeitet und anschließend docker compose restart ausgeführt haben. Dadurch wird der vorhandene Container mit seiner ursprünglichen Umgebung wiederverwendet. Änderungen an der Umgebung erfordern docker compose up -d. Dadurch wird der Container neu erstellt. Die andere Ursache ist beabsichtigt: Wenn ein Image im schreibgeschützten oder im Nicht-Root-Modus ausgeführt wird, überspringt das Init-System die Neunummerierung vollständig, obwohl die Variable im Container vorhanden ist. Im schreibgeschützten Modus meldet das Banner die unveränderte ID von abc. Im Nicht-Root-Modus meldet es den Eigentümer von /run.

Warum Sie eine Datei nicht löschen können, die der Container geschrieben hat

Der Kernel vergleicht Zahlen, niemals Namen. Ihre Shell läuft mit der UID 1000. Die Datei gehört der UID 911. Das Verzeichnis, in dem sie liegt, ist drwxr-xr-x und gehört ebenfalls 911. Für Gruppe und andere gelten dort daher Lese- und Ausführungsrechte, aber kein Schreibrecht. Zum Löschen einer Datei benötigen Sie Schreibrechte für ihr Verzeichnis, nicht für die Datei selbst. Deshalb erhalten Sie diese Ausgabe, obwohl die Datei selbst unproblematisch aussieht:

rm: cannot remove '/srv/appdata/sonarr/config.xml': Permission denied

Ein schreibender Container stößt auf dasselbe Problem aus der anderen Richtung. Wenn das Host-Verzeichnis Ihrem Benutzer gehört und den Modus 755 hat, läuft die Anwendung aber mit der UID 911, schlägt ihr erster Schreibversuch mit Permission denied fehl. Die Anwendung meldet den Fehler dann in ihrer eigenen Formulierung. In einer .NET-Anwendung wie Sonarr oder Radarr erscheint er als UnauthorizedAccessException: Access to the path '/data/downloads' is denied. Die Berechtigungszeichenfolge vor dem Dateinamen zeigt, anhand welcher der drei Berechtigungsmengen der Zugriff tatsächlich bewertet wird. drwxr-xr-x korrekt zu lesen macht aus diesem scheinbar rätselhaften Fehler eine eindeutige Ursache.

Dies ist speziell ein Problem von Bind Mounts. Wenn Docker ein leeres benanntes Volume erstellt und es über einen Pfad mountet, der bereits im Image vorhanden ist, kopiert Docker den Inhalt dieses Pfads in das Volume. Dabei werden auch Eigentümer und Berechtigungsbits übernommen. Die Anwendung findet dadurch ein Verzeichnis vor, das ihr bereits gehört. Bei einem Bind Mount geschieht das nicht: Docker mountet Ihr Host-Verzeichnis exakt in seinem aktuellen Zustand. Dieser Unterschied ist einer der praktischen Gründe, zu wissen, wann ein Bind Mount gegenüber einem benannten Volume die bessere Wahl ist und wann nicht.

Ein bereits falsch konfiguriertes Verzeichnis korrigieren

Das Setzen von PUID und PGID ändert das Verhalten der Anwendung ab diesem Zeitpunkt. Es korrigiert nicht rückwirkend jede bereits auf dem Datenträger vorhandene Datei, obwohl das Init-Skript die Eigentümerschaft auf den unten beschriebenen Pfaden korrigiert. Stoppen Sie den Stack, korrigieren Sie die Eigentümerschaft selbst und starten Sie ihn anschließend erneut:

docker compose down
sudo chown -R 1000:1000 /srv/appdata/sonarr
docker compose up -d

Verwenden Sie sudo chown -R "$(id -u):$(id -g)" /srv/appdata/sonarr, wenn Sie die Zahlen nicht eingeben möchten. Führen Sie dies bei gestopptem Container aus, da eine laufende Anwendung, die während eines rekursiven chown schreibt, einen teilweise korrigierten Verzeichnisbaum und eine verwirrende zweite Runde von Fehlern verursachen kann.

Was PUID und PGID nicht beheben

Hier liegt der Teil, der Anwender betrifft, die alles richtig eingerichtet haben. Das User-Setup-Skript des linuxserver-Basis-Images ändert beim Start mit chown den Besitzer der drei Pfade /app, /config und /defaults. Ihre Media-Mounts gehören nicht zu dieser Liste. /data, /downloads und /tv werden unverändert an die Anwendung übergeben. Wenn der Host-Teil dieser Mounts einem Besitzer gehört, für den der Container-Benutzer keinen Schreibzugriff hat, startet der Container fehlerfrei, gibt in seinem Banner die korrekte UID aus und scheitert anschließend beim ersten Import.

Das ist das richtige Verhalten. Ein rekursives chown über eine zwölf Terabyte große Mediensammlung bei jedem Container-Start wäre fatal. Das bedeutet jedoch, dass Sie für die Media-Verzeichnisse zuständig sind. Dort treten Berechtigungsfehler tatsächlich auf. Solche Fehler werden erst Stunden später unauffällig im Anwendungslog sichtbar, obwohl der Container zunächst fehlerfrei wirkte. Ein regelmäßiger Schreibtest mit Benachrichtigungen über ntfy auf Ihrem eigenen VPS, der Meldungen an Ihr Telefon sendet ist daher eine kostengünstige Möglichkeit, rechtzeitig davon zu erfahren. So müssen nicht erst eine Woche lang fehlende Episoden auf das Problem hinweisen.

Drei Möglichkeiten zur Steuerung des Benutzers und wann welche gilt

Umgebungsvariablen PUID und PGID

Dies funktioniert nur bei Images, deren Entrypoint diese Variablen ausliest. Die Methode ist beliebt, weil der Container weiterhin als root startet, seine Einrichtung selbst durchführt, /config korrigiert und erst danach die Berechtigungen reduziert. Docker Mods und benutzerdefinierte Init-Skripte funktionieren weiterhin. Der Nachteil ist, dass Sie einer Konvention statt einer Plattformfunktion vertrauen. Außerdem sind die Variablennamen projektübergreifend nicht standardisiert.

Der Schlüssel user: in Compose

Dies ist eine echte Docker-Funktion und funktioniert mit jedem Image, weil die Container-Laufzeit den Schlüssel anwendet, bevor der Code des Images ausgeführt wird:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    user: "1000:1000"

Der Prozess läuft niemals als root, auch nicht für einen kurzen Moment. Das ist ein echter Sicherheitsgewinn. Gleichzeitig funktionieren alle Bestandteile des Entrypoints nicht mehr, die root benötigen. Bei linuxserver-Images unterstützt das Projekt diese Funktion nach bestem Bemühen und nur für Images, die es getestet hat. Die Einschränkungen sind konkret: PUID und PGID haben keine Wirkung mehr, Docker Mods werden nicht ausgeführt, benutzerdefinierte Dienste werden nicht ausgeführt, und Sie sind für die Berechtigungen auf jedem eingebundenen Volume verantwortlich. Das dokumentierte Muster kombiniert den Schlüssel mit einem beschreibbaren /run:

user: 1000:1000
tmpfs:
  - /run:uid=1000,gid=1000,exec
security_opt:
  - no-new-privileges=true

Ein kosmetischer Nebeneffekt überrascht viele Benutzer. Eine numerische user: ohne passenden Eintrag in der /etc/passwd des Containers wird von Tools im Container als whoami: cannot find name for user ID 1000 angezeigt. Die ID ist gültig, und der Dateizugriff funktioniert normal. Nur die Namensauflösung schlägt fehl.

Rootless Docker

Rootless Docker führt den Daemon selbst unter Ihrem nicht privilegierten Benutzer aus. Dadurch laufen der Daemon und die Container ohne root-Berechtigungen auf dem Host. Die Zuordnung von Besitzern ändert sich dadurch vollständig. Die Container-UID 0 wird der Host-UID des Benutzers zugeordnet, der Rootless Docker ausführt. Die Container-UID n für jede n ab 1 wird subuid + (n - 1) zugeordnet, wobei subuid die Basis des Ihnen in /etc/subuid zugewiesenen Bereichs ist. Für Gruppen-IDs gilt dieselbe Regel mit /etc/subgid. Docker erwartet dort mindestens 65,536 untergeordnete IDs.

Lesen Sie diese Zuordnung noch einmal, weil sie die übliche Empfehlung umkehrt. Unter Rootless Docker erzeugt ein Container, der eine Datei als root erstellt, normalerweise eine Datei, die Ihnen gehört. Ein Container, der eine Datei als UID 1000 erstellt, erzeugt normalerweise eine Datei, die einer untergeordneten ID gehört, beispielsweise 100999, wenn der Bereich bei 100000 beginnt. Der Zugriff Ihrer Shell hängt von den Berechtigungen und ACLs ab. Das Löschen hängt normalerweise vom übergeordneten Verzeichnis ab. Sie können die Datei daher aus einem Verzeichnis löschen, das Sie kontrollieren. Der PUID-Wert, der bei einem rootful Daemon korrekt ist, ist hier also falsch. Die beiden Mechanismen ändern den Besitzer auf unterschiedlichen Ebenen. Wenn Sie sie ohne Prüfung kombinieren, können Sie den Schreibzugriff auf die eingebundenen Daten verlieren. Wenn Sie Rootless Docker verwenden, prüfen Sie vor der Migration einer Bibliothek die Besitzverhältnisse einer auf Ihrem eigenen Server erstellten Datei.

Für die meisten Self-Hosting-Stacks auf einem einzelnen VPS sind PUID und PGID bei einem rootful Daemon die pragmatische Wahl, weil die Images dafür erstellt und dokumentiert sind. Verwenden Sie user:, wenn die README des Images angibt, dass das Image dafür getestet wurde, oder wenn Sie ein offizielles Upstream-Image ohne PUID-Unterstützung betreiben. Ein Dokumentenarbeitsbereich wie eine selbst gehostete AFFiNE-Instanz auf einem VPS fällt in die zweite Kategorie, weil keiner seiner Container PUID ausliest und der Besitzer des Datenbankverzeichnisses sowie der hochgeladenen Dateien von der Laufzeit und nicht vom Environment-Block festgelegt wird. Dasselbe gilt für einen selbst gehosteten Chatwoot-Supportdesk. Dort schreiben sowohl der Rails-Container als auch sein Sidekiq-Worker in ein gemeinsames Uploads-Verzeichnis. Keiner von beiden liest PUID aus. Das Verzeichnis muss daher zu dem Benutzer passen, unter dem das Image bereits ausgeführt wird. Das ändert sich auch bei einem neueren Stack nicht. Wenn Sie also jeder Person im Team eine eigene isolierte OneCLI-Umgebung geben, gehören die Arbeitsbereichsverzeichnisse der einzelnen Personen und das Postgres-Datenverzeichnis weiterhin dem Benutzer, unter dem das jeweilige Image bereits läuft. Damit handelt es sich um ein user:- und chown-Problem, nicht um ein PUID-Problem. Wenn Sie eine einzelne selbst gehostete API vor Codex, Claude Code und Hermes schalten, verwaltet ihr Entrypoint mehrere Identitäten: Der Container muss als root starten, die Konsole und das Gateway laufen unter einem nicht privilegierten Benutzer, und jede Agentensitzung läuft unter einem eigenen Benutzer. Fügen Sie dieser Bereitstellung kein user: hinzu. Der Entrypoint verwaltet den Besitzer des Daten-Volumes.

Der Fall eines Arr-Medienstapels: eine gemeinsame Gruppe für mehrere Container

Ein Arr-Medienstapel mit Sonarr, Radarr und einem Download-Client ist der Punkt, an dem dies praktisch relevant wird. Der Download-Client schreibt eine fertige Datei nach /data/downloads. Sonarr erstellt anschließend einen Hardlink auf diese Datei oder verschiebt sie nach /data/media. Damit der Hardlink funktioniert, benötigen beide Container Schreibzugriff auf denselben Verzeichnisbaum. Wenn der Download-Client als 1000 und Sonarr als 1001 läuft, ohne gemeinsame Schreibrechte der Gruppe, besitzt einer der beiden Container Dateien, die der andere nur lesen kann.

Die Lösung ist eine gemeinsame Gruppe, die jeder Container im Stapel als PGID verwendet:

sudo groupadd -g 13000 media
sudo usermod -aG media deploy
sudo chown -R deploy:media /srv/media
sudo find /srv/media -type d -exec chmod 2775 {} +
sudo find /srv/media -type f -exec chmod 0664 {} +

Das führende 2 in 2775 ist das setgid-Bit. Bei einem Verzeichnis bedeutet es, dass jede darin neu erstellte Datei und jedes neue Unterverzeichnis die Gruppe media statt der primären Gruppe des Erstellers erbt. Dadurch funktioniert die Konfiguration auch für neue Downloads, ohne dass Sie chown erneut ausführen müssen. Melden Sie sich ab und wieder an oder führen Sie newgrp media aus, bevor Sie Ihren eigenen Zugriff prüfen. Eine mit usermod -aG hinzugefügte Gruppe erscheint nicht in einer bereits geöffneten Shell-Sitzung.

Im Container nummeriert groupmod -o -g 13000 abc die Gruppe abc auf 13000 um. Dadurch schreibt abc mit derselben GID wie Ihre Gruppe media auf dem Host. Jeder linuxserver-Container, der auf diesen Verzeichnisbaum zugreift, behält seine eigene PUID und verwendet diese eine PGID. Das gilt auch für Container weiter unten in der Kette, die nur die fertige Bibliothek lesen, beispielsweise Jellyfin selbst. Ein Frontend wie Halcyon, das diese Bibliothek als begehbaren Videoladen der 90er-Jahre bereitstellt, verbindet sich über HTTP mit Jellyfin und verwendet dafür HALCYON_JELLYFIN_URL. Für die standardmäßige Bereitstellung benötigt es weder die gemeinsame Medien-PGID noch einen Mount des Medienverzeichnisses.

Setzen Sie anschließend UMASK=002 in jedem linuxserver-Container des Stapels. Diesen Schritt wird häufig übersehen. Wenn der Wert nicht gesetzt ist, verwendet die Anwendung ihre geerbte umask, sofern nichts anderes daran geändert wird. Der Beispielwert in den READMEs der Images ist UMASK=022. Bei einer effektiven umask von 022 erhält eine Anwendung, die für eine neue Datei 0666 anfordert, ohne Standard-ACL 0644. Der Rest der Gruppe kann die Datei dann weiterhin lesen, aber nicht ändern. Damit wird ein Großteil der gerade eingerichteten gemeinsamen Nutzung unwirksam. Mit 002 und ohne Standard-ACL erhält eine Anwendung, die für Dateien die übliche Berechtigung 0666 und für Verzeichnisse 0777 anfordert, Dateien mit 0664 und innerhalb des setgid-Verzeichnisbaums Verzeichnisse mit 2775. Die Gruppe kann dann schreiben. Eine umask entfernt nur Berechtigungsbits. Eine Anwendung, die 0600 anfordert, erhält daher weiterhin 0600. Ein Verzeichnis mit einer Standard-ACL ignoriert die umask vollständig. Fügen Sie die Variable neben PUID und PGID ein:

services:
  sonarr:
    image: lscr.io/linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - UMASK=002
      - TZ=Etc/UTC
    volumes:
      - /srv/appdata/sonarr:/config
      - /srv/media:/data
    restart: unless-stopped

Diese beiden Werte gehören in eine .env-Datei neben die Compose-Datei. Dadurch verwendet der gesamte Stapel eine gemeinsame Definition:

PUID=1000
PGID=13000

Compose liest diese Datei automatisch für die Ersetzung im Stil von ${PUID} ein. Das ist derselbe Mechanismus, den Sie für Zugangsdaten verwenden. Die Vorgehensweise, Werte aus docker-compose.yml herauszuhalten und in eine .env-Datei zu verschieben, gilt auch hier. Der Unterschied besteht darin, dass diese beiden Zahlen keine Geheimnisse sind.

Überprüfen Sie die Konfiguration vollständig, statt ihr einfach zu vertrauen. Schreiben Sie als Benutzer der Anwendung eine neue Datei und wenden Sie dabei die konfigurierte umask an. Lesen Sie die Datei anschließend vom Host aus. Verwenden Sie einen Testdateinamen, der noch nicht existiert:

docker exec --user abc sonarr sh -c 'umask "$UMASK" && touch /data/downloads/permtest'
ls -ln /srv/media/downloads/permtest

Ein korrektes Ergebnis zeigt Ihre PUID als Eigentümer, 13000 als Gruppe und -rw-rw-r-- als Modus. Wenn die Gruppe 1000 lautet, führen Sie ls -ldn /srv/media/downloads aus. Entweder fehlt das setgid-Bit, also das s in drwxrwsr-x, in diesem Verzeichnis, oder das Verzeichnis gehört weiterhin der Gruppe 1000 statt media. Die Befehle chown und chmod 2775 weiter oben beheben beide Probleme. Wenn der Modus -rw-r--r-- lautet, prüfen Sie den UMASK-Wert des Containers und die Standard-ACL des Verzeichnisses. Erstellen Sie den Container neu, falls seine Umgebung veraltet ist. Dieser Test prüft die Erstellung als abc mit der konfigurierten Maske. Der eigene Erstellungsmodus der Anwendung und ihre effektive umask bestimmen weiterhin die Berechtigungen ihrer Dateien. Entfernen Sie die Testdatei mit rm /srv/media/downloads/permtest, wenn Sie fertig sind.

Welche Images verwenden welche Variable

Images von linuxserver.io verwenden PUID, PGID und UMASK. Paperless-ngx verwendet für dasselbe Konzept andere Namen: USERMAP_UID und USERMAP_GID, beide standardmäßig auf 1000 gesetzt. Die Dokumentation fordert dazu auf, diese Werte aus id -u und id -g zu übernehmen. Bei Fotoservern gibt es dieselbe Bandbreite: PhotoPrism hat ein eigenes Paar aus PHOTOPRISM_UID und PHOTOPRISM_GID, während Immich kein entsprechendes Gegenstück mitliefert und den Container-Benutzer dem Docker-Schlüssel user: überlässt. Die Wahl zwischen PhotoPrism und Immich legt damit auch fest, welchen dieser Mechanismen Sie für die größte Bibliothek auf dem Server verwalten müssen. Viele offizielle Upstream-Images, darunter die gängigen Images für Datenbanken und Webserver, enthalten einen fest vorgegebenen Benutzer. Sie erwarten, dass Sie user: verwenden oder die Vorgabe unverändert lassen. Auch kleine Bereitstellungen mit nur einer Anwendung werfen dieselbe Frage auf. Wenn Sie also einen selbst gehosteten openGym-Workout-Tracker einrichten, sollten Sie prüfen, unter welchem Benutzer der Container tatsächlich läuft, bevor Sie einen Bind-Mount darauf verweisen lassen. Das Verzeichnis mit der Datenbank übernimmt diese Vorgabe unabhängig davon, ob Sie PUID setzen. Ein Relay für den Fernzugriff fällt in dieselbe Kategorie. Wenn Sie Ihren eigenen RustDesk-Relay-Server betreiben, wird das Ed25519-Schlüsselpaar, das hbbs beim ersten Start schreibt, in Ihrem Bind-Mount mit dem Besitzer des Benutzers angelegt, unter dem das Image letztlich läuft. Sie können den Besitzer anschließend mit einem hostseitigen chown korrigieren. Alternativ legen Sie die Identität von Anfang an mit dem Schlüssel user: fest. Dieses Image setzt selbst keinen Benutzer. Das funktioniert, sofern das eingebundene Verzeichnis für die von Ihnen gewählte ID beschreibbar ist. Dasselbe gilt für Infrastruktur, die Sie später ergänzen. Wenn Sie Authentik als zentrale Anmeldung vor Ihre Anwendungen setzen, verwenden Sie die offiziellen Images von authentik und Postgres. Diese lesen überhaupt kein PUID. Der Besitz ihrer Volumes ergibt sich aus den Benutzern, unter denen ihre Prozesse laufen, sowie aus den Aktionen ihrer Entrypoints. Authentik hat seine Redis-Abhängigkeit in Release 2025.10 entfernt.

Prüfen Sie daher die README jedes Images, bevor Sie einen Umgebungsblock zwischen Projekten kopieren. Docker übergibt jede von Ihnen gesetzte Umgebungsvariable an jeden Container, unabhängig davon, ob ein Prozess darin sie ausliest. Ein PUID, das von keinem Prozess verwendet wird, erzeugt keinen Fehler, keine Warnung und keine Wirkung. Der Container startet unter dem Benutzer, der durch die Einstellung user: von Docker oder durch das Dockerfile ausgewählt wurde. Anschließend kann der Entrypoint die Berechtigungen reduzieren, bevor die Anwendung startet. Lesen Sie diese Informationen, bevor Sie etwas Neues auf dem Server einrichten. Das gilt auch für einen selbst gehosteten open-kritt-Sicherheits-Scan-Stack. Die Compose-Datei zeigt, ob die Images PUID berücksichtigen oder ob der Besitz der von Ihnen eingebundenen Verzeichnisse durch die Images selbst festgelegt wird.

FAQ

Warum gehören meine Docker-Dateien 911:911?

911 ist die UID und GID des in den linuxserver.io-Images integrierten Benutzers abc. Die Werte entsprechen damit den integrierten Standardwerten. Dateien können diese Eigentümerschaft jedoch behalten, nachdem Sie PUID und PGID des Containers geändert haben. ls -l zeigt die reinen Zahlenwerte an, wenn auf Ihrem Host kein Konto zu diesen IDs passt. Daher kann kein Name angezeigt werden. Setzen Sie PUID und PGID auf die Ausgabe von id, erstellen Sie den Container mit docker compose up -d neu und korrigieren Sie anschließend die vorhandenen Dateien mit sudo chown -R 1000:1000 im betroffenen Verzeichnis.

Funktionieren PUID und PGID bei jedem Docker-Image?

Nein. Sie sind keine Docker-Funktion, und Docker liest sie niemals aus. Sie funktionieren nur bei Images, deren eigener Entry Point diese Variablen ausliest und vor dem Start der Anwendung usermod und groupmod aufruft. Das ist bei der linuxserver.io-Familie sowie bei einigen Projekten der Fall, die dieses Muster übernommen haben. Andere Projekte verwenden andere Namen, beispielsweise USERMAP_UID und USERMAP_GID bei paperless-ngx. Bei einem Image, das keine dieser Variablen ausliest, werden die Variablen ohne Warnung akzeptiert und ignoriert.

Sollte ich PUID und PGID oder den Schlüssel user: in Docker Compose verwenden?

Verwenden Sie PUID und PGID, wenn das Image diese Variablen unterstützt. Der Entry Point läuft dann weiterhin lange genug als root, um /config zu korrigieren und die eigenen Dienste korrekt zu starten. Verwenden Sie user:, wenn das Image die Unterstützung für den ausgewählten Benutzer dokumentiert. Eine fehlende PUID-Unterstützung allein bedeutet nicht, dass der Entry Point ohne root funktioniert. Bei einem linuxserver-Image macht das Setzen von user: PUID und PGID wirkungslos. Außerdem werden Docker Mods und benutzerdefinierte Dienste nicht ausgeführt. Die Berechtigungen aller eingebundenen Volumes liegen dann in Ihrer Verantwortung.

Sonarr hat die richtige PUID, kann Dateien aber weiterhin nicht verschieben. Was ist falsch?

Prüfen Sie drei Punkte in dieser Reihenfolge. Erstens das Medien-Mount selbst: Das Benutzer-Setup-Skript des Basis-Images führt für /app, /config und /defaults chown aus. Daher behält /data oder /downloads die Eigentümerschaft bei, die auf dem Host festgelegt ist. Zweitens die gemeinsame Gruppe: Weisen Sie den Containern, die auf den Medienbaum zugreifen, dieselbe PGID sowie Schreibberechtigungen für die Gruppe zu. Drittens die Umask: Eine effektive Maske von 022 erzeugt 0644-Dateien, wenn die Anwendung 0666 anfordert und keine Standard-ACL gilt. Die anderen Container in der Gruppe können die Dateien dann lesen, aber nicht ändern. Wenn UMASK nicht gesetzt ist, wird keine bestimmte Maske oder kein bestimmter Dateimodus garantiert. Setzen Sie UMASK=002 und setzen Sie mit chmod 2775 das setgid-Bit für die Verzeichnisse. Neue Dateien übernehmen dadurch die Gruppe. Eine Anwendung, die 0600 anfordert, erstellt weiterhin private Dateien. Eine Standard-ACL ändert, wie die Berechtigungen bei der Erstellung zugewiesen werden.