Docker/Userns-remap: Unterschied zwischen den Versionen

Aktuelle Version vom 12. Januar 2026, 13:06 Uhr

Docker/Userns-remap

Beschreibung

Linux-Namespaces

Isolation laufender Prozesse

Systemressourcen beschränken
ohne dass Prozesse die wahrnehmen

Rechteausweitung verhindern

Anwendungen von Containern mit nicht privilegierten Benutzern ausführen

Root-Benutzer innerhalb des Containers

Können einem Benutzer mit weniger Privilegien auf dem Docker-Host zugeordnet werden

Bereich von UIDs

Dem Benutzer wird ein Bereich von UIDs zugewiesen

Docker verwendet Sub-UID/GID-Bereiche aus /etc/subuid und /etc/subgid (default dockremap)

Vorbereitung

Nach dem Aktivieren von userns-remap verwendet Docker einen separaten Datenpfad:

/var/lib/docker/<uid>.<gid>/

Neue Entitäten (Images, Container, Volumes, Overlay-Ebenen) werden dort gespeichert
Kataloge mit bisherigen Entitäten werden in diesem Modus nicht verwendet (wirken ausgeblendet)
docker ps, docker images, docker volume ls zeigen nur Entitäten aus dem aktuell verwendeten Docker-Datenpfad
Der Eigentümer der Dateien in overlay2 und volumes ist nun nicht mehr root, sondern der remapped-Benutzer

Für neue Installationen

Images und Container lassen sich einfacher und schneller neu laden als migrieren

Bei aktiviertem userns-remap

--pid=host und --network=host können nicht verwendet werden
Einige externe Volume-/Speichertreiber verstehen möglicherweise remap nicht und funktionieren nicht mehr
--privileged ohne --userns=host funktioniert nicht mehr wie zuvor, einige Funktionen sind eingeschränkt
Es ist besser, userns-remap bei einer sauberen Docker-Installation zu aktivieren: Alte Image-Layer und Container werden ausgeblendet, da Docker einen separaten Ordner für den neuen Namespace in /var/lib/docker/ erstellt

Migration zu neuen Namespaces

Bei bestehender Installation werden vorhandene Objekte nicht automatisch umgeschrieben

Praktisch erfolgt ein Neuaufbau: Images neu laden, Container neu erstellen
Persistente Daten (Bind-Mounts/Volumes) erfordern passende Ownership für den remapped UID/GID-Bereich

Installation

Standardbereich vorab festlegen

Für konsistente Ownership bei Bind-Mounts empfiehlt sich ein fester Startbereich ab 200000.

Bereiche dürfen sich nicht überschneiden
Startbereich nach produktiver Nutzung zu ändern führt typischerweise zu inkonsistenter Ownership. Neuaufbau und Anpassung persistenter Daten erforderlich

/etc/subuid

dockremap:200000:65536

/etc/subgid

dockremap:200000:65536

Ergebnis

Prozess läuft als root (UID 0) im Container -> Host-UID 200000
Prozess läuft als UID 1000 im Container -> Host-UID 201000
MySQL nutzt häufig UID 999 -> Host-UID 200999
Verwendete UIDs/GIDs sind image-spezifisch

userns-remap aktivieren

/etc/docker/daemon.json

{
  "userns-remap": "default"
}

Oder Sie können den Benutzer manuell eingeben:

{
  "userns-remap": "testuser"
}

Sie können den Namen, die UID oder user:group angeben

Dienst neu starten

Nach dem Speichern der Datei den Dienst neu starten:

sudo systemctl restart docker

Überprüfung

docker info | grep -i userns

Userns mode: private

Bind-Mounts

Bei Bind-Mounts muss der Host-Dateibesitzer zur remapped UID/GID passen, sonst können Dienste nicht starten (z.B. fehlende Schreibrechte)

Ziel-UID berechnen

grep dockremap /etc/subuid /etc/subgid

Ausgabe:

dockremap:200000:65536

Bespiel: Anwendung läuft im Container als UID/GID 1000.

HOST_UID = 200000 + 1000 = 201000

sudo chown -R 201000:201000 /path/to/bind-mount

Die Rechte sind nun korrekt festgelegt.

Anhang

Siehe auch

Dokumentation

Links

Projekt

Weblinks

@@ Zeile 1: / Zeile 1: @@
-'''{{BASEPAGENAME}}''' - Beschreibung
+'''{{BASEPAGENAME}}'''
 == Beschreibung ==
@@ Zeile 15: / Zeile 15: @@
 ; Bereich von UIDs
 Dem Benutzer wird ein Bereich von UIDs zugewiesen
-* die innerhalb des Namespace wie normale UIDs von 0 bis 65536 funktionieren
+* Docker verwendet Sub-UID/GID-Bereiche aus ''/etc/subuid'' und ''/etc/subgid'' (default ''dockremap'')
-* aber keine Privilegien auf dem Host-Rechner selbst haben.
-== userns-remap ==
-* Wenn Docker mit aktiviertem userns-remap betrieben wird, muss der Eigentümer der OpenProject-Volume-Verzeichnisse manuell gesetzt werden.
-* Andernfalls starten die OpenProject-Dienste nicht.
-; Ermittlung des UID/GID-Bereichs des dockremap-Benutzers
-<syntaxhighlight lang="bash" highlight="1" line>
-grep dockremap /etc/subuid /etc/subgid
-</syntaxhighlight>
-Ausgabe:
-<syntaxhighlight lang="bash" highlight="" line>
-dockremap:241074:65536
-</syntaxhighlight>
-* OpenProject verwendet innerhalb des Containers die UID 1000.
-* Zur Berechnung der Ziel-UID muss lediglich 1000 zur dockremap-UID addiert werden.
-* Daraus ergibt sich eine Ziel-UID von '''242074'''.
-<syntaxhighlight lang="bash" highlight="1" copy line>
-sudo chown -R 242074:242074 /var/lib/openproject
-</syntaxhighlight>
-* Die Rechte sind nun korrekt festgelegt.
 == Vorbereitung ==
-Nach dem Aktivieren von userns-remap erstellt Docker einen Unterordner wie folgt:
+Nach dem Aktivieren von userns-remap verwendet Docker einen separaten Datenpfad:
 <syntaxhighlight lang="bash" highlight="">
 /var/lib/docker/<uid>.<gid>/
 </syntaxhighlight>
-* Neue Entitäten (Bilder, Container, Volumes, Overlay-Ebenen) werden nun dort gespeichert.
+* Neue Entitäten (Images, Container, Volumes, Overlay-Ebenen) werden dort gespeichert
+* Kataloge mit bisherigen Entitäten werden in diesem Modus nicht verwendet (wirken ausgeblendet)
+* docker ps, docker images, docker volume ls zeigen nur Entitäten aus dem aktuell verwendeten Docker-Datenpfad
+* Der Eigentümer der Dateien in overlay2 und volumes ist nun nicht mehr root, sondern der remapped-Benutzer
-* Kataloge mit alten Entitäten werden nicht mehr verwendet.
+=== Für neue Installationen ===
+Images und Container lassen sich einfacher und schneller neu laden als migrieren
-* docker ps, docker images, docker volume ls funktionieren nur mit dem aktuellen namepace
+; Bei aktiviertem userns-remap
-* Der Eigentümer der Dateien in overlay2 und volumes ist nun nicht mehr root, sondern der remapped-Benutzer
+:* ''--pid=host'' und ''--network=host'' können nicht verwendet werden
+:* Einige externe Volume-/Speichertreiber verstehen möglicherweise remap nicht und funktionieren nicht mehr
+:* ''--privileged'' ohne ''--userns=host'' funktioniert nicht mehr wie zuvor, einige Funktionen sind eingeschränkt
+:* Es ist besser, ''userns-remap'' bei einer sauberen Docker-Installation zu aktivieren: Alte Image-Layer und Container werden ausgeblendet, da Docker einen separaten Ordner für den neuen Namespace in ''/var/lib/docker/'' erstellt
+=== Migration zu neuen Namespaces ===
+Bei bestehender Installation werden vorhandene Objekte nicht automatisch umgeschrieben
+* Praktisch erfolgt ein Neuaufbau: Images neu laden, Container neu erstellen
+* Persistente Daten (Bind-Mounts/Volumes) erfordern passende Ownership für den remapped UID/GID-Bereich
-=== Für neue Installationen ===
+== Installation ==
-Images und Container lassen sich einfacher und schneller neu laden als migrieren.
-; Bei aktiviertem userns-remap:
+=== Standardbereich vorab festlegen ===
-:* ''--pid=host'' und ''--network=host'' können nicht verwendet werden.
+Für konsistente Ownership bei Bind-Mounts empfiehlt sich ein fester Startbereich ab 200000.
-:* Einige externe Volume-/Speichertreiber verstehen möglicherweise remap nicht und funktionieren nicht mehr.
+* Bereiche dürfen sich nicht überschneiden
-:* ''--privileged'' ohne ''--userns=host'' funktioniert nicht mehr wie zuvor, einige Funktionen sind eingeschränkt.
+* Startbereich nach produktiver Nutzung zu ändern führt typischerweise zu inkonsistenter Ownership. Neuaufbau und Anpassung persistenter Daten erforderlich
-:* Es ist besser, ''userns-remap'' bei einer sauberen Docker-Installation zu aktivieren: Alte Image-Layer und Container werden ausgeblendet, da Docker einen separaten Ordner für den neuen Namespace in ''/var/lib/docker/'' erstellt.
-=== Migration zu neuen Namespaces ===
+; /etc/subuid
-Alle erforderlichen Daten werden in den Ordner /var/lib/docker/<uid.guid> verschoben
+<syntaxhighlight lang="ini" highlight="" copy line>
+dockremap:200000:65536
+</syntaxhighlight>
-=== Bereinigung ===
+; /etc/subgid
-Nach der Migration nicht mehr benötigte Dateien löschen
+<syntaxhighlight lang="ini" highlight="" copy line>
-<syntaxhighlight lang="bash" highlight="" copy line>
+dockremap:200000:65536
-systemctl stop docker
-cd /var/lib/docker
-rm -rf containers image network plugins swarm tmp trust volumes
 </syntaxhighlight>
-== Installation ==
+; Ergebnis
+* Prozess läuft als ''root'' (UID 0) im Container -> Host-UID 200000
+* Prozess läuft als UID 1000 im Container -> Host-UID 201000
+* MySQL nutzt häufig UID 999 -> Host-UID 200999
+* Verwendete UIDs/GIDs sind image-spezifisch
 === userns-remap aktivieren ===
-; /etc/docker/daemon.js
+; /etc/docker/daemon.json
 <syntaxhighlight lang="json" highlight="" line copy>
 {
@@ Zeile 109: / Zeile 95: @@
 Userns mode: private
 </syntaxhighlight>
+== Bind-Mounts ==
+* Bei Bind-Mounts muss der Host-Dateibesitzer zur remapped UID/GID passen, sonst können Dienste nicht starten (z.B. fehlende Schreibrechte)
+; Ziel-UID berechnen
+<syntaxhighlight lang="bash" highlight="1" line>
+grep dockremap /etc/subuid /etc/subgid
+</syntaxhighlight>
+Ausgabe:
+<syntaxhighlight lang="bash" highlight="" line>
+dockremap:200000:65536
+</syntaxhighlight>
+Bespiel: Anwendung läuft im Container als UID/GID 1000.
+* ''HOST_UID = 200000 + 1000 = 201000''
+<syntaxhighlight lang="bash" highlight="1" copy line>
+sudo chown -R 201000:201000 /path/to/bind-mount
+</syntaxhighlight>
+* Die Rechte sind nun korrekt festgelegt.
 <noinclude>