无根模式

无根模式允许以非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 或更高版本，或 `~/.local/share/docker` 使用 `user_subvol_rm_allowed` 挂载选项挂载时）
  • vfs
• 仅在使用 cgroup v2 和 systemd 运行时支持 Cgroup。参见 限制资源。
• 不支持以下功能
  • AppArmor
  • Checkpoint
  • Overlay 网络
  • 公开 SCTP 端口
• 要使用 `ping` 命令，请参见 路由 ping 数据包。
• 要公开特权 TCP/UDP 端口（< 1024），请参见 公开特权端口。
• `docker inspect` 中显示的 `IPAddress` 在 RootlessKit 的网络命名空间内。这意味着如果不进入网络命名空间（使用 `nsenter`），则无法从主机访问该 IP 地址。
• 主机网络（`docker run --net=host`）也在 RootlessKit 内进行命名空间隔离。
• 不支持将 NFS 挂载作为 docker “data-root”。此限制并非无根模式独有。

安装

注意

如果系统范围的 Docker 守护进程已经在运行，请考虑禁用它。

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

如果你选择不关闭 `docker` 服务和套接字，则需要在下一节中使用 `--force` 参数。目前没有已知问题，但在你关闭并禁用之前，你仍在运行 rootful 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（不使用软件包安装），删除 `~/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 in Docker

要在“rootful”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) 身份运行。但是，禁用 seccomp、AppArmor 和挂载掩码需要 `--privileged`。

通过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 v2 和 systemd 运行时，才支持使用与 cgroup 相关的 `docker run` 标志（例如 `--cpus`、`--memory`、`--pids-limit`）来限制资源。参见 更改 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/[email protected]
# cat > /etc/systemd/system/[email protected]/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] error: failed to start the child: fork/exec /proc/self/exe: operation not permitted

此错误主要发生在 `/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] error: failed to start the child: fork/exec /proc/self/exe: no space left on device

此错误主要发生在 `/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] error: failed to setup UID/GID map: failed to compute uid/gid map: No subuid ranges found for user 1001 ("testuser")

当未配置 `/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

不要使用sudo -iu <USERNAME>，而应使用pam_systemd登录。例如：

• 通过图形界面登录
• ssh <USERNAME>@localhost
• machinectl shell <USERNAME>@

守护进程不会自动启动。

您需要运行sudo loginctl enable-linger $(whoami)才能启用守护进程自动启动。请参见使用方法。

iptables失败：iptables -t nat -N DOCKER: Fatal: can't open lock file /run/xtables.lock: Permission denied

当主机上启用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: failed to register layer: Error processing tar file(exit status 1): lchown <FILE>: invalid argument

当/etc/subuid或/etc/subgid中可用条目的数量不足时，会发生此错误。所需条目的数量因镜像而异。但是，对于大多数镜像，65,536个条目就足够了。请参见先决条件。

docker: failed to register layer: ApplyLayer exit status 1 stdout: stderr: lchown <FILE>: operation not permitted

此错误主要发生在~/.local/share/docker位于NFS上时。

解决方法是在~/.config/docker/daemon.json中指定非NFS的data-root目录，如下所示：

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

docker run错误

docker: Error response from daemon: OCI runtime create failed: ...: read unix @->/run/systemd/private: read: connection reset by peer: unknown.

此错误主要发生在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。更多信息，请参见限制资源。

网络错误

本节提供无root模式下网络故障排除的提示。

无root模式下的网络支持通过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的网络命名空间内。

--net=host无法在主机网络命名空间上监听端口。

这是预期行为，因为守护进程在RootlessKit的网络命名空间内。

网络速度慢。

无root模式下的Docker如果安装了slirp4netns v0.4.0或更高版本，则使用slirp4netns作为默认网络堆栈。如果未安装slirp4netns，则Docker将回退到VPNKit。安装slirp4netns可以提高网络吞吐量。

有关RootlessKit网络驱动程序的更多信息，请参见RootlessKit文档。

此外，更改MTU值可以提高吞吐量。可以通过创建包含以下内容的~/.config/systemd/user/docker.service.d/override.conf文件来指定MTU值：

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

然后重新启动守护进程。

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

docker run -p不传播源IP地址。

这是因为无root模式下的Docker默认使用RootlessKit的内置端口驱动程序，该驱动程序不支持源IP传播。要启用源IP传播，您可以：

• 使用slirp4netns RootlessKit端口驱动程序
• 使用pasta RootlessKit网络驱动程序和隐式端口驱动程序

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"

   • 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)来进入命名空间。