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

読む時間の目安: 12 分

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ビットやファイルケーパビリティーは利用しません。 ただしnewuidmapnewgidmapは利用します。 これらはユーザー名前空間内において、複数の UID/GID を利用するために必要となるものです。

前提条件

  • ホスト上にnewuidmapnewgidmapをインストールすることが必要です。 このコマンドは、たいていのディストリビューションにおいて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

  • 事前準備するものは何もありません。

  • デフォルトでoverlay2ストレージドライバーが有効になっています。 (Ubuntu 固有のカーネルパッチ)

  • Ubuntu 16.04、18.04、20.04 において動作します。

Debian GNU/Linux

  • /etc/sysctl.conf(または/etc/sysctl.d)にkernel.unprivileged_userns_clone=1を追加して、sudo sysctl --systemを実行してください。

  • overlay2ストレージドライバー(推奨)を利用するには、sudo modprobe overlay permit_mounts_in_userns=1を実行してください。 (Debian 固有のカーネルパッチ、Debian 10 において導入) そして/etc/modprobe.dに設定を追加してください。

  • Debian 9 と 10 において動作します。 overlay2がサポートされるのは Debian 10 からであり、上に示したmodprobeの設定が必要です。

Arch Linux

  • fuse-overlayfsをインストールすることが推奨されます。 その場合はsudo pacman -S fuse-overlayfsを実行します。

  • /etc/sysctl.conf(または/etc/sysctl.d)にkernel.unprivileged_userns_clone=1を追加して、sudo sysctl --systemを実行してください。

openSUSE

  • fuse-overlayfsをインストールすることが推奨されます。 その場合はsudo zypper install -y fuse-overlayfsを実行します。

  • sudo modprobe ip_tables iptable_mangle iptable_nat iptable_filterを実行することが必要です。 設定方法によっては他のディストリビューションにおいても必要なことかもしれません。

  • openSUSE 15 において動作します。

CentOS 8 と Fedora

  • fuse-overlayfsをインストールすることが推奨されます。 その場合はsudo dnf install -y fuse-overlayfsを実行します。

  • sudo dnf install -y iptablesが必要かもしれません。

  • CentOS 8 と Fedora 32 において動作します。

CentOS 7

  • /etc/sysctl.conf(または/etc/sysctl.d)にuser.max_user_namespaces=28633を追加して、sudo sysctl --systemを実行してください。

  • デフォルトではsystemctl --userは動作しません。 デーモンは sysmted を使わずに直接dockerd-rootless.shを起動してください。

  • CentOS 7.7 において動作します。 これより古いリリースにおいては、追加の設定手順が必要になります。

  • CentOS 7.6 やこれ以前のリリースにおいては、COPR パッケージのvbatts/shadow-utils-newxidmap をインストールしていることが必要です。

  • CentOS 7.5 やこれ以前のリリースにおいてはsudo grubby --update-kernel=ALL --args="user_namespace.enable=1"の実行と、その後にシステムを再起動することが必要です。

既知の制約

  • 以下のストレージドライバーのみがサポートされます。
    • overlay2(Ubuntu ホストおよび Debian 10 ホストのみ。)
    • fuse-overlayfs(カーネル 4.18 またはそれ以降の稼動時、そしてfuse-overlayfsインストール時のみ。)
    • 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 内で名前空間化されます。

インストール

https://get.docker.com/rootless から、インストールスクリプトを入手することができます。

$ curl -fsSL https://get.docker.com/rootless | sh

スクリプトの実行は root 以外のユーザーで行います。 Rootless Docker を root ユーザーがインストールする場合は 手動インストール の手順を参照してください。

このスクリプトを実行すると、必要となる環境変数が表示されます。

$ curl -fsSL https://get.docker.com/rootless | sh
...
# Docker binaries are installed in /home/testuser/bin
# WARN: dockerd is not in your current PATH or pointing to /home/testuser/bin/dockerd
# Make sure the following environment variables are set (or add them to ~/.bashrc):

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

#
# To control docker service run:
# systemctl --user (start|stop|restart) docker
#
$ curl -fsSL https://get.docker.com/rootless | sh
...
# Docker バイナリが /home/testuser/bin にインストールされました。
# 警告: dockerd が現在の PATH にない、あるいは /home/testuser/bin/dockerd を指していません。
# 以下の環境変数を設定してください。(あるいは ~/.bashrc に追加してください):

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

#
# Docker サービスは以下により制御します:
# systemctl --user (start|stop|restart) docker
#

手動インストール

インストーラーを利用せずに手動でバイナリをインストールする場合は、docker-<version>.tar.gzとともに配布されているdocker-rootless-extras-<version>.tar.gzを抽出します。 これは https://download.docker.com/linux/static/stable/x86_64/ から入手します。

Docker デーモンをすでに root で実行している場合は、docker-rootless-extras-<version>.tgzを入手するだけです。 このアーカイブを$PATH上のいずれかのディレクトリに伸張(解凍)します。 たとえば/usr/local/bin$HOME/binなどです。

最新版チャネル

Rootless Docker の最新版(Nightly)をインストールするには、インストールスクリプトにおいてCHANNEL="nightly"を指定します。

$ curl -fsSL https://get.docker.com/rootless | CHANNEL="nightly" sh

実行バイナリのアーカイブは以下から入手できます。

  • https://master.dockerproject.org/linux/x86_64/docker-rootless-extras.tgz
  • https://master.dockerproject.org/linux/x86_64/docker.tgz

利用方法

デーモン

Use systemctl --user to manage the lifecycle of the daemon:

$ systemctl --user start docker

システム起動時にデーモンを起動するには、Systemd サービスに対して linger を有効にします。

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

Systemd を使わずにデーモンを直接起動するには、dockerdの代わりにdockerd-rootless.shを起動する必要があります。

Docker 19.03 においてdockerd-rootless.shを実行する際には--experimentalの指定が必要でした。 Docker 20.10 からは--experimentalフラグを不要になりました。

ディレクトリパスについて触れておきます。

  • ソケットパスはデフォルトで$XDG_RUNTIME_DIR/docker.sockに設定されます。 $XDG_RUNTIME_DIRは通常/run/user/$UIDに設定されます。
  • データディレクトリはデフォルトで~/.local/share/dockerに設定されます。
  • 実行ディレクトリはデフォルトで$XDG_RUNTIME_DIR/dockerに設定されます。
  • デーモン設定ディレクトリはデフォルトで(クライアントが利用する~/.dockerでなく)~/.config/dockerに設定されます。

その他についてです。

  • dockerd-rootless.shスクリプトは、これが有するユーザー、マウント、ネットワーク名前空間のもとでdockerdを実行します。 その名前空間に入るにはnsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)を実行します。
  • docker infoを実行するとSecurityOptions欄にrootlessと表示されます。

クライアント

ソケットパスは明示的に指定する必要があります。

$DOCKER_HOSTを用いてソケットパス指定するには以下のようにします。

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

docker contextを用いてソケットパスを指定するには以下のようにします。

$ docker context create rootless --description "for rootless mode" --docker "host=unix://$XDG_RUNTIME_DIR/docker.sock"
rootless
Successfully created context "rootless"
$ 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の指定が必要です。

Docker 19.03 においては--experimentalフラグの指定が必要です。

$ docker run -d --name dind-rootless --privileged docker:19.03-dind-rootless --experimental

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 --experimental \
  -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 $HOME/bin/rootlesskit

または/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>を実行します。

ネットワーク関連ソフトウェアの変更

dockerd-rootless.shでは、ネットワーク関連ソフトウェアとしてデフォルトで slirp4netns(インストール時)または VPNKit を利用します。

このネットワークソフトウエアはユーザー空間内で動作するため、性能オーバーヘッドを招く場合があります。 より詳しくは RootlessKit ドキュメント を参照してください。

最適な性能を得るために、上の代わりにlxc-user-nicを利用することもできます。 lxc-user-nicを利用するには/etc/lxc/lxc-usernet を編集し$DOCKERD_ROOTLESS_ROOTLESSKIT_NET=lxc-user-nicを設定する必要があります。

トラブルシューティング

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.

dockerd fails with “rootless mode is supported only when running in experimental mode”

This error occurs when the daemon is launched without the --experimental flag on Docker 19.03. See Usage.

--experimentalフラグは Docker 20.10 からは不要になりました。

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 run errors

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

Error response from daemon: cgroups: cgroup mountpoint does not exist: unknown.

This error occurs mostly when the host is running in cgroup v2. See the section Fedora 31 or later for information on switching the host to use cgroup v1.

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.

security, namespaces, rootless