moby/docs/rootless.md

Rootless mode (Experimental)

The rootless mode allows running dockerd as an unprivileged user, using user_namespaces(7), mount_namespaces(7), network_namespaces(7).

No SETUID/SETCAP binary is required except newuidmap and newgidmap.

Requirements

• newuidmap and newgidmap need to be installed on the host. These commands are provided by the uidmap package on most distros.

• /etc/subuid and /etc/subgid should contain >= 65536 sub-IDs. e.g. penguin:231072:65536.

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

Distribution-specific hint

Debian (excluding Ubuntu)

• sudo sh -c "echo 1 > /proc/sys/kernel/unprivileged_userns_clone" is required

Arch Linux

• sudo sh -c "echo 1 > /proc/sys/kernel/unprivileged_userns_clone" is required

openSUSE

• sudo modprobe ip_tables iptable_mangle iptable_nat iptable_filter is required. (This is likely to be required on other distros as well)

RHEL/CentOS 7

• sudo sh -c "echo 28633 > /proc/sys/user/max_user_namespaces" is required
• COPR package vbatts/shadow-utils-newxidmap needs to be installed

Restrictions

• Only vfs graphdriver is supported. However, on Ubuntu and a few distros, overlay2 and overlay are also supported.
• Following features are not supported:
  • Cgroups (including docker top, which depends on the cgroups device controller)
  • Apparmor
  • Checkpoint
  • Overlay network
  • Exposing SCTP ports
• To expose a TCP/UDP port, the host port number needs to be set to >= 1024.

Usage

Daemon

You need to run dockerd-rootless.sh instead of dockerd.

$ dockerd-rootless.sh --experimental

As Rootless mode is experimental per se, currently you always need to run dockerd-rootless.sh with --experimental.

Remarks:

• The socket path is set to $XDG_RUNTIME_DIR/docker.sock by default. $XDG_RUNTIME_DIR is typically set to /run/user/$UID.
• The data dir is set to ~/.local/share/docker by default.
• The exec dir is set to $XDG_RUNTIME_DIR/docker by default.
• The daemon config dir is set to ~/.config/docker (not ~/.docker, which is used by the client) by default.
• The dockerd-rootless.sh script executes dockerd in its own user, mount, and network namespaces. You can enter the namespaces by running nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid).
• docker info shows rootless in SecurityOptions
• docker info shows none as Cgroup Driver

Client

You can just use the upstream Docker client but you need to set the socket path explicitly.

$ docker -H unix://$XDG_RUNTIME_DIR/docker.sock run -d nginx

Expose Docker API socket via TCP

To expose the Docker API socket via TCP, you need to launch dockerd-rootless.sh with 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

Routing ping packets

To route ping packets, you need to set up net.ipv4.ping_group_range properly as the root.

$ sudo sh -c "echo 0   2147483647  > /proc/sys/net/ipv4/ping_group_range"

Changing network stack

dockerd-rootless.sh uses slirp4netns (if installed) or VPNKit as the network stack by default. These network stacks run in userspace and might have performance overhead. See RootlessKit documentation for further information.

Optionally, you can use lxc-user-nic instead for the best performance. To use lxc-user-nic, you need to edit /etc/lxc/lxc-usernet and set $DOCKERD_ROOTLESS_ROOTLESSKIT_NET=lxc-user-nic.