github.com/devdivbcp/moby@v17.12.0-ce-rc1.0.20200726071732-2d4bfdc789ad+incompatible/docs/rootless.md (about)

     1  # Rootless mode (Experimental)
     2  
     3  The rootless mode allows running `dockerd` as an unprivileged user, using `user_namespaces(7)`, `mount_namespaces(7)`, `network_namespaces(7)`.
     4  
     5  No SETUID/SETCAP binary is required except `newuidmap` and `newgidmap`.
     6  
     7  ## Requirements
     8  * `newuidmap` and `newgidmap` need to be installed on the host. These commands are provided by the `uidmap` package on most distros.
     9  
    10  * `/etc/subuid` and `/etc/subgid` should contain >= 65536 sub-IDs. e.g. `penguin:231072:65536`.
    11  
    12  ```console
    13  $ id -u
    14  1001
    15  $ whoami
    16  penguin
    17  $ grep ^$(whoami): /etc/subuid
    18  penguin:231072:65536
    19  $ grep ^$(whoami): /etc/subgid
    20  penguin:231072:65536
    21  ```
    22  
    23  ### Distribution-specific hint
    24  
    25  Using Ubuntu kernel is recommended.
    26  
    27  #### Ubuntu
    28  * No preparation is needed.
    29  * `overlay2` is enabled by default ([Ubuntu-specific kernel patch](https://kernel.ubuntu.com/git/ubuntu/ubuntu-bionic.git/commit/fs/overlayfs?id=3b7da90f28fe1ed4b79ef2d994c81efbc58f1144)).
    30  * Known to work on Ubuntu 16.04 and 18.04.
    31  
    32  #### Debian GNU/Linux
    33  * Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`
    34  * To use `overlay2` storage driver (recommended), run `sudo modprobe overlay permit_mounts_in_userns=1` ([Debian-specific kernel patch, introduced in Debian 10](https://salsa.debian.org/kernel-team/linux/blob/283390e7feb21b47779b48e0c8eb0cc409d2c815/debian/patches/debian/overlayfs-permit-mounts-in-userns.patch)). Put the configuration to `/etc/modprobe.d` for persistence.
    35  * Known to work on Debian 9 and 10. `overlay2` is only supported since Debian 10 and needs `modprobe` configuration described above.
    36  
    37  #### Arch Linux
    38  * Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`
    39  
    40  #### openSUSE
    41  * `sudo modprobe ip_tables iptable_mangle iptable_nat iptable_filter` is required. (This is likely to be required on other distros as well)
    42  * Known to work on openSUSE 15.
    43  
    44  #### Fedora 31 and later
    45  * Run `sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=0"` and reboot.
    46  
    47  #### Fedora 30
    48  * No preparation is needed
    49  
    50  #### RHEL/CentOS 8
    51  * No preparation is needed
    52  
    53  #### RHEL/CentOS 7
    54  * Add `user.max_user_namespaces=28633` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`
    55  * `systemctl --user` does not work by default. Run the daemon directly without systemd: `dockerd-rootless.sh --experimental --storage-driver vfs`
    56  * Known to work on RHEL/CentOS 7.7. Older releases require extra configuration steps.
    57  * RHEL/CentOS 7.6 and older releases require [COPR package `vbatts/shadow-utils-newxidmap`](https://copr.fedorainfracloud.org/coprs/vbatts/shadow-utils-newxidmap/) to be installed.
    58  * RHEL/CentOS 7.5 and older releases require running `sudo grubby --update-kernel=ALL --args="user_namespace.enable=1"` and reboot.
    59  
    60  ## Known limitations
    61  
    62  * Only `vfs` graphdriver is supported. However, on Ubuntu and Debian 10, `overlay2` and `overlay` are also supported.
    63  * Following features are not supported:
    64    * Cgroups (including `docker top`, which depends on the cgroups device controller)
    65    * Apparmor
    66    * Checkpoint
    67    * Overlay network
    68    * Exposing SCTP ports
    69  * To use `ping` command, see [Routing ping packets](#routing-ping-packets)
    70  * To expose privileged TCP/UDP ports (< 1024), see [Exposing privileged ports](#exposing-privileged-ports)
    71  
    72  ## Install
    73  
    74  The installation script is available at https://get.docker.com/rootless .
    75  
    76  ```console
    77  $ curl -fsSL https://get.docker.com/rootless | sh
    78  ```
    79  
    80  Make sure to run the script as a non-root user.
    81  
    82  The script will show the environment variables that are needed to be set:
    83  
    84  ```console
    85  $ curl -fsSL https://get.docker.com/rootless | sh
    86  ...
    87  # Docker binaries are installed in /home/penguin/bin
    88  # WARN: dockerd is not in your current PATH or pointing to /home/penguin/bin/dockerd
    89  # Make sure the following environment variables are set (or add them to ~/.bashrc):
    90  
    91  export PATH=/home/penguin/bin:$PATH
    92  export PATH=$PATH:/sbin
    93  export DOCKER_HOST=unix:///run/user/1001/docker.sock
    94  
    95  #
    96  # To control docker service run:
    97  # systemctl --user (start|stop|restart) docker
    98  #
    99  ```
   100  
   101  To install the binaries manually without using the installer, extract `docker-rootless-extras-<version>.tar.gz` along with `docker-<version>.tar.gz`: https://download.docker.com/linux/static/stable/x86_64/
   102  
   103  ## Usage
   104  
   105  ### Daemon
   106  
   107  Use `systemctl --user` to manage the lifecycle of the daemon:
   108  ```console
   109  $ systemctl --user start docker
   110  ```
   111  
   112  To launch the daemon on system startup, enable systemd lingering:
   113  ```console
   114  $ sudo loginctl enable-linger $(whoami)
   115  ```
   116  
   117  To run the daemon directly without systemd, you need to run `dockerd-rootless.sh` instead of `dockerd`:
   118  ```console
   119  $ dockerd-rootless.sh --experimental --storage-driver vfs
   120  ```
   121  
   122  As Rootless mode is experimental, currently you always need to run `dockerd-rootless.sh` with `--experimental`.
   123  You also need `--storage-driver vfs` unless using Ubuntu or Debian 10 kernel.
   124  
   125  Remarks:
   126  * The socket path is set to `$XDG_RUNTIME_DIR/docker.sock` by default. `$XDG_RUNTIME_DIR` is typically set to `/run/user/$UID`.
   127  * The data dir is set to `~/.local/share/docker` by default.
   128  * The exec dir is set to `$XDG_RUNTIME_DIR/docker` by default.
   129  * The daemon config dir is set to `~/.config/docker` (not `~/.docker`, which is used by the client) by default.
   130  * 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)`.
   131  * `docker info` shows `rootless` in `SecurityOptions`
   132  * `docker info` shows `none` as `Cgroup Driver`
   133  
   134  ### Client
   135  
   136  You need to set the socket path explicitly.
   137  
   138  ```console
   139  $ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock
   140  $ docker run -d nginx
   141  ```
   142  
   143  ### Rootless Docker in Docker
   144  
   145  To run Rootless Docker inside "rootful" Docker, use `docker:<version>-dind-rootless` image instead of `docker:<version>-dind` image.
   146  
   147  ```console
   148  $ docker run -d --name dind-rootless --privileged docker:19.03-dind-rootless --experimental
   149  ```
   150  
   151  `docker:<version>-dind-rootless` image runs as a non-root user (UID 1000).
   152  However, `--privileged` is required for disabling seccomp, AppArmor, and mount masks.
   153  
   154  ### Expose Docker API socket via TCP
   155  
   156  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"`.
   157  
   158  ```console
   159  $ DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp" \
   160   dockerd-rootless.sh --experimental \
   161   -H tcp://0.0.0.0:2376 \
   162   --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem
   163  ```
   164  
   165  ### Routing ping packets
   166  
   167  Add `net.ipv4.ping_group_range = 0   2147483647` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`.
   168  
   169  ### Exposing privileged ports
   170  
   171  To expose privileged ports (< 1024), set `CAP_NET_BIND_SERVICE` on `rootlesskit` binary.
   172  
   173  ```console
   174  $ sudo setcap cap_net_bind_service=ep $HOME/bin/rootlesskit
   175  ```
   176  
   177  Or add `net.ipv4.ip_unprivileged_port_start=0` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`.
   178  
   179  ### Limiting resources
   180  
   181  Currently rootless mode ignores cgroup-related `docker run` flags such as `--cpus` and `memory`.
   182  However, traditional `ulimit` and [`cpulimit`](https://github.com/opsengine/cpulimit) can be still used, though it works in process-granularity rather than container-granularity.
   183  
   184  ### Changing network stack
   185  
   186  `dockerd-rootless.sh` uses [slirp4netns](https://github.com/rootless-containers/slirp4netns) (if installed) or [VPNKit](https://github.com/moby/vpnkit) as the network stack by default.
   187  These network stacks run in userspace and might have performance overhead. See [RootlessKit documentation](https://github.com/rootless-containers/rootlesskit/tree/v0.6.0#network-drivers) for further information.
   188  
   189  Optionally, you can use `lxc-user-nic` instead for the best performance.
   190  To use `lxc-user-nic`, you need to edit [`/etc/lxc/lxc-usernet`](https://github.com/rootless-containers/rootlesskit/tree/v0.6.0#--netlxc-user-nic-experimental) and set `$DOCKERD_ROOTLESS_ROOTLESSKIT_NET=lxc-user-nic`.
   191