[19.03 backport] docs/rootless.md: update
Andrew Hsu authored on 2019/10/29 02:46:27... | ... |
@@ -20,43 +20,107 @@ $ grep ^$(whoami): /etc/subgid |
20 | 20 |
penguin:231072:65536 |
21 | 21 |
``` |
22 | 22 |
|
23 |
- |
|
24 | 23 |
### Distribution-specific hint |
25 | 24 |
|
26 |
-#### Debian (excluding Ubuntu) |
|
27 |
-* `sudo sh -c "echo 1 > /proc/sys/kernel/unprivileged_userns_clone"` is required |
|
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. |
|
28 | 36 |
|
29 | 37 |
#### Arch Linux |
30 |
-* `sudo sh -c "echo 1 > /proc/sys/kernel/unprivileged_userns_clone"` is required |
|
38 |
+* Add `kernel.unprivileged_userns_clone=1` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p` |
|
31 | 39 |
|
32 | 40 |
#### openSUSE |
33 | 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 |
|
34 | 52 |
|
35 | 53 |
#### RHEL/CentOS 7 |
36 |
-* `sudo sh -c "echo 28633 > /proc/sys/user/max_user_namespaces"` is required |
|
37 |
-* [COPR package `vbatts/shadow-utils-newxidmap`](https://copr.fedorainfracloud.org/coprs/vbatts/shadow-utils-newxidmap/) needs to be installed |
|
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. |
|
38 | 59 |
|
39 |
-## Restrictions |
|
60 |
+## Known limitations |
|
40 | 61 |
|
41 |
-* Only `vfs` graphdriver is supported. However, on [Ubuntu](http://kernel.ubuntu.com/git/ubuntu/ubuntu-artful.git/commit/fs/overlayfs?h=Ubuntu-4.13.0-25.29&id=0a414bdc3d01f3b61ed86cfe3ce8b63a9240eba7) and a few distros, `overlay2` and `overlay` are also supported. |
|
62 |
+* Only `vfs` graphdriver is supported. However, on Ubuntu and Debian 10, `overlay2` and `overlay` are also supported. |
|
42 | 63 |
* Following features are not supported: |
43 | 64 |
* Cgroups (including `docker top`, which depends on the cgroups device controller) |
44 | 65 |
* Apparmor |
45 | 66 |
* Checkpoint |
46 | 67 |
* Overlay network |
47 | 68 |
* Exposing SCTP ports |
48 |
-* To expose a TCP/UDP port, the host port number needs to be set to >= 1024. |
|
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/ |
|
49 | 102 |
|
50 | 103 |
## Usage |
51 | 104 |
|
52 | 105 |
### Daemon |
53 | 106 |
|
54 |
-You need to run `dockerd-rootless.sh` instead of `dockerd`. |
|
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 |
+``` |
|
55 | 116 |
|
117 |
+To run the daemon directly without systemd, you need to run `dockerd-rootless.sh` instead of `dockerd`: |
|
56 | 118 |
```console |
57 |
-$ dockerd-rootless.sh --experimental |
|
119 |
+$ dockerd-rootless.sh --experimental --storage-driver vfs |
|
58 | 120 |
``` |
59 |
-As Rootless mode is experimental per se, currently you always need to run `dockerd-rootless.sh` with `--experimental`. |
|
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. |
|
60 | 124 |
|
61 | 125 |
Remarks: |
62 | 126 |
* The socket path is set to `$XDG_RUNTIME_DIR/docker.sock` by default. `$XDG_RUNTIME_DIR` is typically set to `/run/user/$UID`. |
... | ... |
@@ -69,12 +133,24 @@ Remarks: |
69 | 69 |
|
70 | 70 |
### Client |
71 | 71 |
|
72 |
-You can just use the upstream Docker client but you need to set the socket path explicitly. |
|
72 |
+You need to set the socket path explicitly. |
|
73 | 73 |
|
74 | 74 |
```console |
75 |
-$ docker -H unix://$XDG_RUNTIME_DIR/docker.sock run -d nginx |
|
75 |
+$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock |
|
76 |
+$ docker run -d nginx |
|
76 | 77 |
``` |
77 | 78 |
|
79 |
+### Rootless Docker in Docker |
|
80 |
+ |
|
81 |
+To run Rootless Docker inside "rootful" Docker, use `docker:<version>-dind-rootless` image instead of `docker:<version>-dind` image. |
|
82 |
+ |
|
83 |
+```console |
|
84 |
+$ docker run -d --name dind-rootless --privileged docker:19.03-dind-rootless --experimental |
|
85 |
+``` |
|
86 |
+ |
|
87 |
+`docker:<version>-dind-rootless` image runs as a non-root user (UID 1000). |
|
88 |
+However, `--privileged` is required for disabling seccomp, AppArmor, and mount masks. |
|
89 |
+ |
|
78 | 90 |
### Expose Docker API socket via TCP |
79 | 91 |
|
80 | 92 |
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"`. |
... | ... |
@@ -88,12 +164,23 @@ $ DOCKERD_ROOTLESS_ROOTLESSKIT_FLAGS="-p 0.0.0.0:2376:2376/tcp" \ |
88 | 88 |
|
89 | 89 |
### Routing ping packets |
90 | 90 |
|
91 |
-To route ping packets, you need to set up `net.ipv4.ping_group_range` properly as the root. |
|
91 |
+Add `net.ipv4.ping_group_range = 0 2147483647` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`. |
|
92 |
+ |
|
93 |
+### Exposing privileged ports |
|
94 |
+ |
|
95 |
+To expose privileged ports (< 1024), set `CAP_NET_BIND_SERVICE` on `rootlesskit` binary. |
|
92 | 96 |
|
93 | 97 |
```console |
94 |
-$ sudo sh -c "echo 0 2147483647 > /proc/sys/net/ipv4/ping_group_range" |
|
98 |
+$ sudo setcap cap_net_bind_service=ep $HOME/bin/rootlesskit |
|
95 | 99 |
``` |
96 | 100 |
|
101 |
+Or add `net.ipv4.ip_unprivileged_port_start=0` to `/etc/sysctl.conf` (or `/etc/sysctl.d`) and run `sudo sysctl -p`. |
|
102 |
+ |
|
103 |
+### Limiting resources |
|
104 |
+ |
|
105 |
+Currently rootless mode ignores cgroup-related `docker run` flags such as `--cpus` and `memory`. |
|
106 |
+However, traditional `ulimit` and [`cpulimit`](https://github.com/opsengine/cpulimit) can be still used, though it works in process-granularity rather than container-granularity. |
|
107 |
+ |
|
97 | 108 |
### Changing network stack |
98 | 109 |
|
99 | 110 |
`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. |