无根模式

无根模式允许以非 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) 进入命名空间。