無根模式

無根模式允許以非 root 使用者身份執行 Docker 守護程式和容器，以緩解守護程式和容器執行時中潛在的漏洞。

只要滿足先決條件，無根模式甚至在安裝 Docker 守護程式期間也不需要 root 許可權。

工作原理

無根模式在使用者名稱空間內執行 Docker 守護程式和容器。這與 userns-remap 模式非常相似，不同之處在於 userns-remap 模式下，守護程式本身以 root 許可權執行，而在無根模式下，守護程式和容器都以非 root 許可權執行。

無根模式不使用帶有 SETUID 位或檔案功能（除了 newuidmap 和 newgidmap，它們是允許在使用者名稱空間中使用多個 UID/GID 所必需的）的二進位制檔案。

先決條件

• 您必須在主機上安裝 newuidmap 和 newgidmap。這些命令由大多數發行版上的 uidmap 包提供。

• /etc/subuid 和 /etc/subgid 應該至少包含 65,536 個使用者的從屬 UID/GID。在下面的示例中，使用者 testuser 擁有 65,536 個從屬 UID/GID (231072-296607)。

$ id -u
1001
$ whoami
testuser
$ grep ^$(whoami): /etc/subuid
testuser:231072:65536
$ grep ^$(whoami): /etc/subgid
testuser:231072:65536

特定發行版的提示

提示

我們建議您使用 Ubuntu 核心。

已知限制

• 僅支援以下儲存驅動程式
  • overlay2（僅當使用核心 5.11 或更高版本，或 Ubuntu 風味核心時）
  • fuse-overlayfs（僅當使用核心 4.18 或更高版本，並安裝了 fuse-overlayfs 時）
  • btrfs（僅當使用核心 4.18 或更高版本，或使用 user_subvol_rm_allowed 掛載選項掛載 ~/.local/share/docker 時）
  • vfs
• 僅當使用 cgroup v2 和 systemd 執行時支援 Cgroup。請參閱限制資源。
• 不支援以下功能
  • AppArmor
  • 檢查點
  • 覆蓋網路
  • 暴露 SCTP 埠
• 要使用 ping 命令，請參閱路由 ping 資料包。
• 要暴露特權 TCP/UDP 埠（< 1024），請參閱暴露特權埠。
• docker inspect 中顯示的 IPAddress 在 RootlessKit 的網路名稱空間中進行名稱空間隔離。這意味著在不 nsenter 進入網路名稱空間的情況下，主機無法訪問該 IP 地址。
• 主機網路 (docker run --net=host) 也被名稱空間隔離在 RootlessKit 中。
• 不支援將 NFS 掛載作為 Docker“資料根”。此限制並非無根模式特有。

安裝

注意

如果系統範圍的 Docker 守護程式已在執行，請考慮停用它

$ sudo systemctl disable --now docker.service docker.socket
$ sudo rm /var/run/docker.sock

如果您選擇不關閉 docker 服務和套接字，則需要在下一節中使用 --force 引數。沒有已知問題，但在您關閉和停用之前，您仍在執行有根 Docker。

$ dockerd-rootless-setuptool.sh install
[INFO] Creating /home/testuser/.config/systemd/user/docker.service
...
[INFO] Installed docker.service successfully.
[INFO] To control docker.service, run: `systemctl --user (start|stop|restart) docker.service`
[INFO] To run docker.service on system startup, run: `sudo loginctl enable-linger testuser`

[INFO] Make sure the following environment variables are set (or add them to ~/.bashrc):

export PATH=/usr/bin:$PATH
export DOCKER_HOST=unix:///run/user/1000/docker.sock

$ sudo apt-get install -y docker-ce-rootless-extras

$ curl -fsSL https://get.docker.com/rootless | sh
...
[INFO] Creating /home/testuser/.config/systemd/user/docker.service
...
[INFO] Installed docker.service successfully.
[INFO] To control docker.service, run: `systemctl --user (start|stop|restart) docker.service`
[INFO] To run docker.service on system startup, run: `sudo loginctl enable-linger testuser`

[INFO] Make sure the following environment variables are set (or add them to ~/.bashrc):

export PATH=/home/testuser/bin:$PATH
export DOCKER_HOST=unix:///run/user/1000/docker.sock

如果您遇到錯誤，請參閱故障排除。

解除安裝

要刪除 Docker 守護程式的 systemd 服務，請執行 dockerd-rootless-setuptool.sh uninstall

$ dockerd-rootless-setuptool.sh uninstall
+ systemctl --user stop docker.service
+ systemctl --user disable docker.service
Removed /home/testuser/.config/systemd/user/default.target.wants/docker.service.
[INFO] Uninstalled docker.service
[INFO] This uninstallation tool does NOT remove Docker binaries and data.
[INFO] To remove data, run: `/usr/bin/rootlesskit rm -rf /home/testuser/.local/share/docker`

如果您已將 PATH 和 DOCKER_HOST 環境變數新增到 ~/.bashrc，請取消設定它們。

要刪除資料目錄，請執行 rootlesskit rm -rf ~/.local/share/docker。

要刪除二進位制檔案，如果您使用包管理器安裝了 Docker，請刪除 docker-ce-rootless-extras 包。如果您使用 https://get.docker.com/rootless 安裝了 Docker（不帶包安裝），請刪除 ~/bin 下的二進位制檔案

$ cd ~/bin
$ rm -f containerd containerd-shim containerd-shim-runc-v2 ctr docker docker-init docker-proxy dockerd dockerd-rootless-setuptool.sh dockerd-rootless.sh rootlesskit rootlesskit-docker-proxy runc vpnkit

用法

守護程序

$ systemctl --user start docker

$ systemctl --user enable docker
$ sudo loginctl enable-linger $(whoami)

目錄路徑備註

• 套接字路徑預設設定為 $XDG_RUNTIME_DIR/docker.sock。$XDG_RUNTIME_DIR 通常設定為 /run/user/$UID。
• 資料目錄預設設定為 ~/.local/share/docker。資料目錄不應位於 NFS 上。
• 守護程式配置目錄預設設定為 ~/.config/docker。此目錄與客戶端使用的 ~/.docker 不同。

客戶端

您需要顯式指定套接字路徑或 CLI 上下文。

使用 $DOCKER_HOST 指定套接字路徑

$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock
$ docker run -d -p 8080:80 nginx

使用 docker context 指定 CLI 上下文

$ docker context use rootless
rootless
Current context is now "rootless"
$ docker run -d -p 8080:80 nginx

最佳實踐

Docker 中的無根 Docker

要在“有根”Docker 中執行無根 Docker，請使用 docker:<版本>-dind-rootless 映象而不是 docker:<版本>-dind。

$ docker run -d --name dind-rootless --privileged docker:25.0-dind-rootless

docker:<版本>-dind-rootless 映象以非 root 使用者 (UID 1000) 執行。但是，需要 --privileged 才能停用 seccomp、AppArmor 和掛載掩碼。

透過 TCP 暴露 Docker API 套接字

要透過 TCP 暴露 Docker API 套接字，您需要使用 DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp" 啟動 dockerd-rootless.sh。

$ DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp" \
  dockerd-rootless.sh \
  -H tcp://0.0.0.0:2376 \
  --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem

透過 SSH 暴露 Docker API 套接字

要透過 SSH 暴露 Docker API 套接字，您需要確保在遠端主機上設定了 $DOCKER_HOST。

$ ssh -l <REMOTEUSER> <REMOTEHOST> 'echo $DOCKER_HOST'
unix:///run/user/1001/docker.sock
$ docker -H ssh://<REMOTEUSER>@<REMOTEHOST> run ...

路由 ping 資料包

在某些發行版上，ping 預設不工作。

將 net.ipv4.ping_group_range = 0 2147483647 新增到 /etc/sysctl.conf（或 /etc/sysctl.d）並執行 sudo sysctl --system 以允許使用 ping。

暴露特權埠

要暴露特權埠（< 1024），請在 rootlesskit 二進位制檔案上設定 CAP_NET_BIND_SERVICE 並重新啟動守護程式。

$ sudo setcap cap_net_bind_service=ep $(which rootlesskit)
$ systemctl --user restart docker

或者將 net.ipv4.ip_unprivileged_port_start=0 新增到 /etc/sysctl.conf（或 /etc/sysctl.d）並執行 sudo sysctl --system。

資源限制

使用 cgroup 相關 docker run 標誌（例如 --cpus、--memory、--pids-limit）限制資源僅在 cgroup v2 和 systemd 執行時受支援。請參閱更改 cgroup 版本以啟用 cgroup v2。

如果 docker info 將 Cgroup Driver 顯示為 none，則條件不滿足。當這些條件不滿足時，無根模式將忽略 cgroup 相關的 docker run 標誌。有關解決方法，請參閱不使用 cgroup 限制資源。

如果 docker info 將 Cgroup Driver 顯示為 systemd，則條件滿足。但是，通常，預設情況下，只有 memory 和 pids 控制器會委託給非 root 使用者。

$ cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/cgroup.controllers
memory pids

要允許委託所有控制器，您需要按如下方式更改 systemd 配置

# mkdir -p /etc/systemd/system/user@.service.d
# cat > /etc/systemd/system/user@.service.d/delegate.conf << EOF
[Service]
Delegate=cpu cpuset io memory pids
EOF
# systemctl daemon-reload

注意

委託 cpuset 需要 systemd 244 或更高版本。

不使用 cgroup 限制資源

即使 cgroup 不可用，您仍然可以使用傳統的 ulimit 和 cpulimit，儘管它們以程序粒度而不是容器粒度工作，並且可以被容器程序隨意停用。

例如：

• 要將 CPU 使用率限制為 0.5 核（類似於 docker run --cpus 0.5）：docker run cpulimit --limit=50 --include-children

• 要將最大 VSZ 限制為 64MiB（類似於 docker run --memory 64m）：docker run sh -c "ulimit -v 65536; "

• 要將每個名稱空間 UID 2000 的最大程序數限制為 100（類似於 docker run --pids-limit=100）：docker run --user 2000 --ulimit nproc=100

故障排除

當系統上存在 systemd 時，無法使用 systemd 安裝

$ dockerd-rootless-setuptool.sh install
[INFO] systemd not detected, dockerd-rootless.sh needs to be started manually:
...

如果您透過 sudo su 切換到您的使用者，rootlesskit 無法正確檢測 systemd。對於無法登入的使用者，您必須使用 machinectl 命令，它是 systemd-container 包的一部分。安裝 systemd-container 後，使用以下命令切換到 myuser

$ sudo machinectl shell myuser@

其中 myuser@ 是您想要的使用者名稱，@ 表示此機器。

啟動 Docker 守護程式的錯誤

[rootlesskit:parent] 錯誤：無法啟動子程序：fork/exec /proc/self/exe：操作不被允許

此錯誤通常發生在 /proc/sys/kernel/unprivileged_userns_clone 的值設定為 0 時

$ cat /proc/sys/kernel/unprivileged_userns_clone
0

要解決此問題，請將 kernel.unprivileged_userns_clone=1 新增到 /etc/sysctl.conf（或 /etc/sysctl.d）並執行 sudo sysctl --system。

[rootlesskit:parent] 錯誤：無法啟動子程序：fork/exec /proc/self/exe：裝置上沒有空間

此錯誤通常發生在 /proc/sys/user/max_user_namespaces 的值太小時

$ cat /proc/sys/user/max_user_namespaces
0

要解決此問題，請將 user.max_user_namespaces=28633 新增到 /etc/sysctl.conf（或 /etc/sysctl.d）並執行 sudo sysctl --system。

[rootlesskit:parent] 錯誤：無法設定 UID/GID 對映：無法計算 uid/gid 對映：未找到使用者 1001 ("testuser") 的子 uid 範圍

當未配置 /etc/subuid 和 /etc/subgid 時，會發生此錯誤。請參閱先決條件。

無法獲取 XDG_RUNTIME_DIR

當未設定 $XDG_RUNTIME_DIR 時，會發生此錯誤。

在非 systemd 主機上，您需要建立目錄然後設定路徑

$ export XDG_RUNTIME_DIR=$HOME/.docker/xrd
$ rm -rf $XDG_RUNTIME_DIR
$ mkdir -p $XDG_RUNTIME_DIR
$ dockerd-rootless.sh

注意

您必須在每次登出時刪除該目錄。

在 systemd 主機上，使用 pam_systemd 登入主機（見下文）。該值會自動設定為 /run/user/$UID 並在每次登出時清理。

systemctl --user 失敗並顯示“Failed to connect to bus: No such file or directory”

此錯誤通常發生在您使用 sudo 從 root 使用者切換到非 root 使用者時

# sudo -iu testuser
$ systemctl --user start docker
Failed to connect to bus: No such file or directory

您需要使用 pam_systemd 登入，而不是 sudo -iu 。例如

• 透過圖形控制檯登入
• ssh @localhost
• machinectl shell @

守護程式未自動啟動

您需要 sudo loginctl enable-linger $(whoami) 才能使守護程式自動啟動。請參閱用法。

iptables 失敗：iptables -t nat -N DOCKER: 致命錯誤：無法開啟鎖檔案 /run/xtables.lock：許可權被拒絕

當主機上啟用了 SELinux 時，此錯誤可能發生在較舊版本的 Docker 上。

此問題已在 Docker 20.10.8 中修復。對於較舊版本的 Docker，一個已知的解決方法是執行以下命令以停用 iptables 的 SELinux

$ sudo dnf install -y policycoreutils-python-utils && sudo semanage permissive -a iptables_t

docker pull 錯誤

docker：註冊層失敗：處理 tar 檔案失敗（退出狀態 1）：lchown <檔案>：無效引數

當 /etc/subuid 或 /etc/subgid 中可用條目不足時，會發生此錯誤。所需的條目數量因映象而異。但是，對於大多數映象，65,536 個條目就足夠了。請參閱先決條件。

docker：註冊層失敗：ApplyLayer 退出狀態 1 stdout：stderr：lchown <檔案>：操作不被允許

此錯誤通常發生在 ~/.local/share/docker 位於 NFS 上時。

一個解決方法是在 ~/.config/docker/daemon.json 中指定非 NFS data-root 目錄，如下所示

{"data-root":"/somewhere-out-of-nfs"}

docker run 錯誤

docker：守護程式響應錯誤：OCI 執行時建立失敗：...：讀取 unix @->/run/systemd/private：讀取：連線被對端重置：未知。

此錯誤通常發生在 cgroup v2 主機上，當用戶的 dbus 守護程式未執行時。

$ systemctl --user is-active dbus
inactive

$ docker run hello-world
docker: Error response from daemon: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:385: applying cgroup configuration for process caused: error while starting unit "docker
-931c15729b5a968ce803784d04c7421f791d87e5ca1891f34387bb9f694c488e.scope" with properties [{Name:Description Value:"libcontainer container 931c15729b5a968ce803784d04c7421f791d87e5ca1891f34387bb9f694c488e"} {Name:Slice Value:"use
r.slice"} {Name:PIDs Value:@au [4529]} {Name:Delegate Value:true} {Name:MemoryAccounting Value:true} {Name:CPUAccounting Value:true} {Name:IOAccounting Value:true} {Name:TasksAccounting Value:true} {Name:DefaultDependencies Val
ue:false}]: read unix @->/run/systemd/private: read: connection reset by peer: unknown.

要解決此問題，請執行 sudo apt-get install -y dbus-user-session 或 sudo dnf install -y dbus-daemon，然後重新登入。

如果錯誤仍然存在，請嘗試執行 systemctl --user enable --now dbus（不帶 sudo）。

--cpus、--memory 和 --pids-limit 被忽略

這是 cgroup v1 模式下的預期行為。要使用這些標誌，主機需要配置為啟用 cgroup v2。有關更多資訊，請參閱限制資源。

網路錯誤

本節提供無根模式下網路的故障排除技巧。

無根模式下的網路透過 RootlessKit 中的網路和埠驅動程式支援。網路效能和特性取決於您使用的網路和埠驅動程式的組合。如果您遇到與網路相關的意外行為或效能問題，請查看下錶，其中顯示了 RootlessKit 支援的配置及其比較

有關特定網路問題的故障排除資訊，請參閱

• docker run -p 失敗並顯示 cannot expose privileged port
• Ping 不工作
• docker inspect 中顯示的 IPAddress 無法訪問
• --net=host 未在主機網路名稱空間上偵聽埠
• 網路速度慢
• docker run -p 不傳播源 IP 地址

docker run -p 失敗並顯示 cannot expose privileged port

當將特權埠（< 1024）指定為主機埠時，docker run -p 會失敗並顯示此錯誤。

$ docker run -p 80:80 nginx:alpine
docker: Error response from daemon: driver failed programming external connectivity on endpoint focused_swanson (9e2e139a9d8fc92b37c36edfa6214a6e986fa2028c0cc359812f685173fa6df7): Error starting userland proxy: error while calling PortManager.AddPort(): cannot expose privileged port 80, you might need to add "net.ipv4.ip_unprivileged_port_start=0" (currently 1024) to /etc/sysctl.conf, or set CAP_NET_BIND_SERVICE on rootlesskit binary, or choose a larger port number (>= 1024): listen tcp 0.0.0.0:80: bind: permission denied.

當您遇到此錯誤時，請考慮使用非特權埠。例如，8080 而不是 80。

$ docker run -p 8080:80 nginx:alpine

要允許暴露特權埠，請參閱暴露特權埠。

Ping 不工作

當 /proc/sys/net/ipv4/ping_group_range 設定為 1 0 時，Ping 不工作

$ cat /proc/sys/net/ipv4/ping_group_range
1       0

有關詳細資訊，請參閱路由 ping 資料包。

docker inspect 中顯示的 IPAddress 無法訪問

這是預期行為，因為守護程式在 RootlessKit 的網路名稱空間中被名稱空間隔離。請改用 docker run -p。

--net=host 未在主機網路名稱空間上偵聽埠

這是預期行為，因為守護程式在 RootlessKit 的網路名稱空間中被名稱空間隔離。請改用 docker run -p。

網路速度慢

如果安裝了 slirp4netns v0.4.0 或更高版本，無根模式下的 Docker 會使用 slirp4netns 作為預設網路堆疊。如果未安裝 slirp4netns，Docker 會回退到 VPNKit。安裝 slirp4netns 可能會提高網路吞吐量。

有關 RootlessKit 網路驅動程式的更多資訊，請參閱RootlessKit 文件。

此外，更改 MTU 值可能會提高吞吐量。MTU 值可以透過建立 ~/.config/systemd/user/docker.service.d/override.conf 幷包含以下內容來指定

[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_MTU=<INTEGER>"

然後重啟守護程式

$ systemctl --user daemon-reload
$ systemctl --user restart docker

docker run -p 不傳播源 IP 地址

這是因為無根模式下的 Docker 預設使用 RootlessKit 的 builtin 埠驅動程式，它不支援源 IP 傳播。要啟用源 IP 傳播，您可以

• 使用 slirp4netns RootlessKit 埠驅動程式
• 使用 pasta RootlessKit 網路驅動程式，並使用 implicit 埠驅動程式

pasta 網路驅動程式是實驗性的，但與 slirp4netns 埠驅動程式相比，它提供了改進的吞吐量效能。pasta 驅動程式需要 Docker Engine 25.0 或更高版本。

要更改 RootlessKit 網路配置

1. 在 ~/.config/systemd/user/docker.service.d/override.conf 建立一個檔案。

2. 根據您要使用的配置新增以下內容

   • slirp4netns

     [Service]
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET=slirp4netns"
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"

   • 使用 implicit 埠驅動程式的 pasta 網路驅動程式

     [Service]
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_NET=pasta"
     Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=implicit"

3. 重啟守護程式

   $ systemctl --user daemon-reload
   $ systemctl --user restart docker
   

有關 RootlessKit 網路選項的更多資訊，請參閱

• 網路驅動程式
• 埠驅動程式

除錯技巧

進入 dockerd 名稱空間

dockerd-rootless.sh 指令碼在其自己的使用者、掛載和網路名稱空間中執行 dockerd。

為了除錯，您可以透過執行 nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid) 進入名稱空間。