root ユーザー以外による Docker デーモン起動（rootless モード）

読む時間の目安: 16 分

rootless モードとは、root 以外のユーザーによって Docker デーモンやコンテナーを起動するものであり、デーモンや起動コンテナーにおける潜在的なぜい弱性を軽減します。

rootless モードは root 権限を必要としません。 しかも 前提条件 を満たしていれば、Docker デーモンのインストール時も必要としません。

rootless モードは Docker Engine v19.03 において試験的機能として導入されました。 rootless モードは Docker Engine v20.10 から正規機能となりました。

どのように動作するか

rootless モードは、Docker デーモンやコンテナーをユーザー名前空間の内部で実行します。 これは userns-remap モード に非常によく似ています。 ただしuserns-remapモードにおいては、デーモンだけは root 権限で起動します。 rootless モードの場合は、デーモンとコンテナーがそれぞれ root 権限なしに動作します。

rootless モードは、実行モジュールの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 カーネルの利用をお勧めします。

• Ubuntu
• Debian GNU/Linux
• Arch Linux
• openSUSE と SLES
• CentOS 、RHEL 8、Fedora
• CentOS 7、RHEL 7

既知の制約

• 以下のストレージドライバーのみがサポートされます。
  • overlay2（カーネル 5.11 およびこれ以降が稼働する場合のみ。または Ubuntu 系カーネルのみ。）
  • fuse-overlayfs（カーネル 4.18 またはそれ以降の稼動時、そしてfuse-overlayfsインストール時のみ。）
  • btrfs（カーネル 4.18 またはそれ以降で利用する場合のみ。あるいはuser_subvol_rm_allowedマウントオプションを使って~/.local/share/dockerをマウントしている場合。）
  • vfs
• cgroup は cgroup v2 および systemd を用いて実行するときのみサポートされます。 リソースの利用制限 を参照してください。
• 以下の機能はサポートされません。
  • AppArmor
  • Checkpoint
  • Overlay ネットワーク
  • SCTP ポートの公開
• ping コマンドを利用するには Routing ping packets を参照してください。
• TCP/UDP の特権ポート（1024 未満）を公開するには 特権ポートの公開 を参照してください。
• docker inspectに表示されるIPAddressは RootlessKit のネットワーク名前空間内で名前空間化されます。 これはつまりこの IP アドレスへは、nsenterを使ってそのネットワーク名前空間にアクセスしない限りは、ホストからアクセスできないということです。
• ホストネットワーク（docker run --net=host）も RootlessKit 内で名前空間化されます。
• Docker の「data-root」としての NFS マウントはサポートされません。 この制約は rootless モードだけのものではありません。

インストール

メモ

If the system-wide Docker daemon is already running, consider disabling it: $ sudo systemctl disable --now docker.service docker.socket

• With packages (RPM/DEB)
• Without packages

$ 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

$ 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

See Troubleshooting if you faced an error.

アンインストール

To remove the systemd service of the Docker daemon, run 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`

Unset environment variables PATH and DOCKER_HOST if you have added them to ~/.bashrc.

To remove the data directory, run rootlesskit rm -rf ~/.local/share/docker.

To remove the binaries, remove docker-ce-rootless-extras package if you installed Docker with package managers. If you installed Docker with https://get.docker.com/rootless (Install without packages), remove the binary files under ~/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

利用方法

デーモン

• With systemd (Highly recommended)
• Without systemd

$ 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に設定されます。 The data dir should not be on NFS.
• The daemon config dir is set to ~/.config/docker by default. This directory is different from ~/.docker that is used by the client.

クライアント

ソケットパスまたは 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

ベストプラクティス

Rootless Docker in Docker

「完全な root」で動作する Docker 内において Rootless Docker を起動するには、docker:<version>-dindイメージの代わりにdocker:<version>-dind-rootlessイメージを利用します。

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

docker:<version>-dind-rootlessイメージは非 root ユーザー（UID 1000）により動作します。 ただし seccomp、AppArmor、マウントマスクを無効化するには--privilegedの指定が必要です。

TCP を通じた Docker API ソケットの公開

TCP を通じて Docker API ソケットを公開するには、dockerd-rootless.shの実行にあたってDOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp"を指定する必要があります。

$ 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が動作しないものがあります。

pingを利用するためには/etc/sysctl.confに（あるいは/etc/sysctl.dに）net.ipv4.ping_group_range = 0 2147483647を追加してsudo sysctl --systemを実行します。

特権ポートの公開

特権ポート（1024 未満）を公開するには、rootlesskitバイナリに対してCAP_NET_BIND_SERVICEを設定して、デーモンを再起動します。

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

または/etc/sysctl.conf（あるいは/etc/sysctl.d）にnet.ipv4.ip_unprivileged_port_start=0を追加してsudo sysctl --systemを実行します。

リソースの利用制限

Limiting resources with cgroup-related docker run flags such as --cpus, --memory, --pids-limit is supported only when running with cgroup v2 and systemd. See Changing cgroup version to enable cgroup v2.

If docker info shows none as Cgroup Driver, the conditions are not satisfied. When these conditions are not satisfied, rootless mode ignores the cgroup-related docker run flags. See Limiting resources without cgroup for workarounds.

If docker info shows systemd as Cgroup Driver, the conditions are satisfied. However, typically, only memory and pids controllers are delegated to non-root users by default.

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

To allow delegation of all controllers, you need to change the systemd configuration as follows:

# 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 またはそれ以降が必要です。

Limiting resources without cgroup

Even when cgroup is not available, you can still use the traditional ulimit and cpulimit, though they work in process-granularity rather than in container-granularity, and can be arbitrarily disabled by the container process.

たとえば以下です。

• （docker run --cpus 0.5と同じように）CPU 利用量を 0.5 コアに制限するには、docker run <IMAGE> cpulimit --limit=50 --include-children <COMMAND> を実行します。

• （docker run --memory 64mと同じように）VSZ の最大値を 64 MiB に制限するには、docker run <IMAGE> sh -c "ulimit -v 65536; <COMMAND>"を実行します。

• （docker run --pids-limit=100と同じように）最大プロセス数を UID 2000 の名前空間ごとに 100 とするにはdocker run --user 2000 --ulimit nproc=100 <IMAGE> <COMMAND>を実行します。

トラブルシューティング

Errors when starting the Docker daemon

[rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: operation not permitted

This error occurs mostly when the value of /proc/sys/kernel/unprivileged_userns_clone is set to 0:

$ cat /proc/sys/kernel/unprivileged_userns_clone
0

To fix this issue, add kernel.unprivileged_userns_clone=1 to /etc/sysctl.conf (or /etc/sysctl.d) and run sudo sysctl --system.

[rootlesskit:parent] error: failed to start the child: fork/exec /proc/self/exe: no space left on device

This error occurs mostly when the value of /proc/sys/user/max_user_namespaces is too small:

$ cat /proc/sys/user/max_user_namespaces
0

To fix this issue, add user.max_user_namespaces=28633 to /etc/sysctl.conf (or /etc/sysctl.d) and run 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”)

This error occurs when /etc/subuid and /etc/subgid are not configured. See Prerequisites.

could not get XDG_RUNTIME_DIR

This error occurs when $XDG_RUNTIME_DIR is not set.

On a non-systemd host, you need to create a directory and then set the path:

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

Note: You must remove the directory every time you log out.

On a systemd host, log into the host using pam_systemd (see below). The value is automatically set to /run/user/$UID and cleaned up on every logout.

systemctl --user fails with “Failed to connect to bus: No such file or directory”

This error occurs mostly when you switch from the root user to an non-root user with sudo:

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

Instead of sudo -iu <USERNAME>, you need to log in using pam_systemd. For example:

• Log in through the graphic console
• ssh <USERNAME>@localhost
• machinectl shell <USERNAME>@

The daemon does not start up automatically

You need sudo loginctl enable-linger $(whoami) to enable the daemon to start up automatically. See Usage.

iptables failed: iptables -t nat -N DOCKER: Fatal: can’t open lock file /run/xtables.lock: Permission denied

This error may happen with an older version of Docker when SELinux is enabled on the host.

The issue has been fixed in Docker 20.10.8. A known workaround for older version of Docker is to run the following commands to disable SELinux for iptables:

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

docker pull errors

docker: failed to register layer: Error processing tar file(exit status 1): lchown <FILE>: invalid argument

This error occurs when the number of available entries in /etc/subuid or /etc/subgid is not sufficient. The number of entries required vary across images. However, 65,536 entries are sufficient for most images. See Prerequisites.

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

This error occurs mostly when ~/.local/share/docker is located on NFS.

A workaround is to specify non-NFS data-root directory in ~/.config/docker/daemon.json as follows:

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

docker run errors

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

This error occurs on cgroup v2 hosts mostly when the dbus daemon is not running for the user.

$ 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.

To fix the issue, run sudo apt-get install -y dbus-user-session or sudo dnf install -y dbus-daemon, and then relogin.

If the error still occurs, try running systemctl --user enable --now dbus (without sudo).

--cpus, --memory, and --pids-limit are ignored

This is an expected behavior on cgroup v1 mode. To use these flags, the host needs to be configured for enabling cgroup v2. For more information, see Limiting resources.

Networking errors

docker run -p fails with cannot expose privileged port

docker run -p fails with this error when a privileged port (< 1024) is specified as the host port.

$ 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.

When you experience this error, consider using an unprivileged port instead. For example, 8080 instead of 80.

$ docker run -p 8080:80 nginx:alpine

To allow exposing privileged ports, see Exposing privileged ports.

ping doesn’t work

Ping does not work when /proc/sys/net/ipv4/ping_group_range is set to 1 0:

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

For details, see Routing ping packets.

IPAddress shown in docker inspect is unreachable

This is an expected behavior, as the daemon is namespaced inside RootlessKit’s network namespace. Use docker run -p instead.

--net=host doesn’t listen ports on the host network namespace

This is an expected behavior, as the daemon is namespaced inside RootlessKit’s network namespace. Use docker run -p instead.

Network is slow

Docker with rootless mode uses slirp4netns as the default network stack if slirp4netns v0.4.0 or later is installed. If slirp4netns is not installed, Docker falls back to VPNKit.

Installing slirp4netns may improve the network throughput. See RootlessKit documentation for the benchmark result.

Also, changing MTU value may improve the throughput. The MTU value can be specified by creating ~/.config/systemd/user/docker.service.d/override.conf with the following content:

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

And then restart the daemon:

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

docker run -p does not propagate source IP addresses

The source IP addresses can be propagated by creating ~/.config/systemd/user/docker.service.d/override.conf with the following content:

[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"

And then restart the daemon:

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

Note that this configuration decreases throughput. See RootlessKit documentation for the benchmark result.

Tips for debugging

Entering into dockerd namespaces

The dockerd-rootless.sh script executes dockerd in its own user, mount, and network namespaces.

For debugging, you can enter the namespaces by running nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid).