github.com/rootless-containers/rootlesskit/v2@v2.3.4/README.md (about) 1 # RootlessKit: Linux-native fakeroot using user namespaces 2 3 RootlessKit is a Linux-native implementation of "fake root" using [`user_namespaces(7)`](http://man7.org/linux/man-pages/man7/user_namespaces.7.html). 4 5 The purpose of RootlessKit is to run [Docker and Kubernetes as an unprivileged user (known as "Rootless mode")](https://github.com/rootless-containers/usernetes), so as to protect the real root on the host from potential container-breakout attacks. 6 7 <!-- START doctoc generated TOC please keep comment here to allow auto update --> 8 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> 9 10 11 - [What RootlessKit actually does](#what-rootlesskit-actually-does) 12 - [Similar projects](#similar-projects) 13 - [Projects using RootlessKit](#projects-using-rootlesskit) 14 - [Setup](#setup) 15 - [Requirements](#requirements) 16 - [subuid](#subuid) 17 - [sysctl](#sysctl) 18 - [Usage](#usage) 19 - [Full CLI options](#full-cli-options) 20 - [State directory](#state-directory) 21 - [Environment variables](#environment-variables) 22 - [Additional documents](#additional-documents) 23 24 <!-- END doctoc generated TOC please keep comment here to allow auto update --> 25 26 ## What RootlessKit actually does 27 28 RootlessKit creates [`user_namespaces(7)`](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) and [`mount_namespaces(7)`](http://man7.org/linux/man-pages/man7/mount_namespaces.7.html), 29 and executes [`newuidmap(1)`](http://man7.org/linux/man-pages/man1/newuidmap.1.html)/[`newgidmap(1)`](http://man7.org/linux/man-pages/man1/newgidmap.1.html) along with [`subuid(5)`](http://man7.org/linux/man-pages/man5/subuid.5.html) and [`subgid(5)`](http://man7.org/linux/man-pages/man5/subgid.5.html). 30 31 RootlessKit also supports isolating [`network_namespaces(7)`](http://man7.org/linux/man-pages/man7/network_namespaces.7.html) with userspace NAT using ["slirp"](./docs/network.md). 32 Kernel-mode NAT using SUID-enabled [`lxc-user-nic(1)`](https://linuxcontainers.org/lxc/manpages/man1/lxc-user-nic.1.html) is also experimentally supported. 33 34 ## Similar projects 35 36 Tools based on `LD_PRELOAD` (not enough to run rootless containers and yet lacks support for static binaries): 37 * [`fakeroot`](https://wiki.debian.org/FakeRoot) 38 39 Tools based on `ptrace(2)` (not enough to run rootless containers and yet slow): 40 * [`fakeroot-ng`](https://fakeroot-ng.lingnu.com/) 41 * [`proot`](https://proot-me.github.io/) 42 43 Tools based on `user_namespaces(7)` (as in RootlessKit, but without support for `--copy-up`, `--net`, ...): 44 * [`unshare -r`](http://man7.org/linux/man-pages/man1/unshare.1.html) 45 * [`podman unshare`](https://github.com/containers/libpod/blob/master/docs/source/markdown/podman-unshare.1.md) 46 * [`become-root`](https://github.com/giuseppe/become-root) 47 48 ## Projects using RootlessKit 49 50 Container engines: 51 * [Docker/Moby](https://get.docker.com/rootless) 52 * [Podman](https://podman.io/) (since Podman v1.8.0) 53 * [nerdctl](https://github.com/containerd/nerdctl): Docker-compatible CLI for containerd 54 * [iSulad](https://github.com/openeuler-mirror/iSulad/tree/master/docs/manual/rootless.md): a lightweight container engine 55 56 Container image builders: 57 * [BuildKit](https://github.com/moby/buildkit): Next-generation `docker build` backend 58 59 Kubernetes distributions: 60 * [Usernetes](https://github.com/rootless-containers/usernetes): Docker & Kubernetes, installable under a non-root user's `$HOME`. 61 * [k3s](https://k3s.io/): Lightweight Kubernetes 62 63 ## Setup 64 65 Run `make && sudo make install` . 66 67 The following binaries will be installed: 68 - `/usr/local/bin/rootlesskit` 69 - `/usr/local/bin/rootlessctl` 70 - `/usr/local/bin/rootlesskit-docker-proxy` (DEPRECATED; Only required for Docker prior to [v28](https://github.com/moby/moby/pull/48132/commits/dac7ffa3404138a4f291c16586e5a2c68dad4151)) 71 72 ### Requirements 73 74 ### subuid 75 76 * `newuidmap` and `newgidmap` need to be installed on the host. These commands are provided by the `uidmap` package on most distributions. 77 78 * `/etc/subuid` and `/etc/subgid` should contain more than 65536 sub-IDs. e.g. `penguin:231072:65536`. These files are automatically configured on most distributions. 79 80 ```console 81 $ id -u 82 1001 83 $ whoami 84 penguin 85 $ grep "^$(whoami):" /etc/subuid 86 penguin:231072:65536 87 $ grep "^$(whoami):" /etc/subgid 88 penguin:231072:65536 89 ``` 90 91 See also https://rootlesscontaine.rs/getting-started/common/subuid/ 92 93 ### sysctl 94 95 Some distros require setting up sysctl: 96 97 - Debian (excluding Ubuntu) and Arch: `sudo sh -c "echo 1 > /proc/sys/kernel/unprivileged_userns_clone"` 98 - RHEL/CentOS 7 (excluding RHEL/CentOS 8): `sudo sh -c "echo 28633 > /proc/sys/user/max_user_namespaces"` 99 100 To persist sysctl configurations, edit `/etc/sysctl.conf` or add a file under `/etc/sysctl.d`. 101 102 See also https://rootlesscontaine.rs/getting-started/common/sysctl/ 103 104 ## Usage 105 106 Inside `rootlesskit bash`, your UID is mapped to 0 but it is not the real root: 107 108 ```console 109 (host)$ rootlesskit bash 110 (rootlesskit)# id 111 uid=0(root) gid=0(root) groups=0(root),65534(nogroup) 112 (rootlesskit)# ls -l /etc/shadow 113 -rw-r----- 1 nobody nogroup 1050 Aug 21 19:02 /etc/shadow 114 (rootlesskit)# cat /etc/shadow 115 cat: /etc/shadow: Permission denied 116 ``` 117 118 Environment variables are kept untouched: 119 120 ```console 121 (host)$ rootlesskit bash 122 (rootlesskit)# echo $USER 123 penguin 124 (rootlesskit)# echo $HOME 125 /home/penguin 126 (rootlesskit)# echo $XDG_RUNTIME_DIR 127 /run/user/1001 128 ``` 129 130 Filesystems can be isolated from the host with `--copy-up`: 131 132 ```console 133 (host)$ rootlesskit --copy-up=/etc bash 134 (rootlesskit)# rm /etc/resolv.conf 135 (rootlesskit)# vi /etc/resolv.conf 136 ``` 137 138 You can even create network namespaces with [Slirp](./docs/network.md): 139 140 ```console 141 (host)$ rootlesskit --copy-up=/etc --copy-up=/run --net=slirp4netns --disable-host-loopback bash 142 (rootleesskit)# ip netns add foo 143 ... 144 ``` 145 146 ## Full CLI options 147 148 ```console 149 $ rootlesskit --help 150 NAME: 151 rootlesskit - Linux-native fakeroot using user namespaces 152 153 USAGE: 154 rootlesskit [global options] [arguments...] 155 156 VERSION: 157 2.0.0-alpha.0 158 159 DESCRIPTION: 160 RootlessKit is a Linux-native implementation of "fake root" using user_namespaces(7). 161 162 Web site: https://github.com/rootless-containers/rootlesskit 163 164 Examples: 165 # spawn a shell with a new user namespace and a mount namespace 166 rootlesskit bash 167 168 # make /etc writable 169 rootlesskit --copy-up=/etc bash 170 171 # set mount propagation to rslave 172 rootlesskit --propagation=rslave bash 173 174 # create a network namespace with slirp4netns, and expose 80/tcp on the namespace as 8080/tcp on the host 175 rootlesskit --copy-up=/etc --net=slirp4netns --disable-host-loopback --port-driver=builtin -p 127.0.0.1:8080:80/tcp bash 176 177 Note: RootlessKit requires /etc/subuid and /etc/subgid to be configured by the real root user. 178 See https://rootlesscontaine.rs/getting-started/common/ . 179 180 OPTIONS: 181 Misc: 182 --debug debug mode (default: false) 183 --print-semver value print a version component as a decimal integer [major, minor, patch] 184 --help, -h show help 185 --version, -v print the version 186 187 Mount: 188 --copy-up value [ --copy-up value ] mount a filesystem and copy-up the contents. e.g. "--copy-up=/etc" (typically required for non-host network) 189 --copy-up-mode value copy-up mode [tmpfs+symlink] 190 --propagation value mount propagation [rprivate, rslave] 191 192 Network: 193 --net value network driver [host, pasta(experimental), slirp4netns, vpnkit, lxc-user-nic(experimental)] 194 --mtu value MTU for non-host network (default: 65520 for pasta and slirp4netns, 1500 for others) (default: 0) 195 --cidr value CIDR for pasta and slirp4netns networks (default: 10.0.2.0/24) 196 --ifname value Network interface name (default: tap0 for pasta, slirp4netns, and vpnkit; eth0 for lxc-user-nic) 197 --disable-host-loopback prohibit connecting to 127.0.0.1:* on the host namespace (default: false) 198 --ipv6 enable IPv6 routing. Unrelated to port forwarding. Only supported for pasta and slirp4netns. (experimental) (default: false) 199 --detach-netns detach network namespaces (default: false) 200 201 Network [lxc-user-nic]: 202 --lxc-user-nic-binary value path of lxc-user-nic binary for --net=lxc-user-nic 203 --lxc-user-nic-bridge value lxc-user-nic bridge name 204 205 Network [pasta]: 206 --pasta-binary value path of pasta binary for --net=pasta 207 208 Network [slirp4netns]: 209 --slirp4netns-binary value path of slirp4netns binary for --net=slirp4netns 210 --slirp4netns-sandbox value enable slirp4netns sandbox (experimental) [auto, true, false] (the default is planned to be "auto" in future) 211 --slirp4netns-seccomp value enable slirp4netns seccomp (experimental) [auto, true, false] (the default is planned to be "auto" in future) 212 213 Network [vpnkit]: 214 --vpnkit-binary value path of VPNKit binary for --net=vpnkit 215 216 Port: 217 --port-driver value port driver for non-host network. [none, implicit (for pasta), builtin, slirp4netns] 218 --publish value, -p value [ --publish value, -p value ] publish ports. e.g. "127.0.0.1:8080:80/tcp" 219 220 Process: 221 --pidns create a PID namespace (default: false) 222 --cgroupns create a cgroup namespace (default: false) 223 --utsns create a UTS namespace (default: false) 224 --ipcns create an IPC namespace (default: false) 225 --reaper value enable process reaper. Requires --pidns. [auto,true,false] 226 --evacuate-cgroup2 value evacuate processes into the specified subgroup. Requires --pidns and --cgroupns 227 228 State: 229 --state-dir value state directory 230 231 SubID: 232 --subid-source value the source of the subids. "dynamic" executes /usr/bin/getsubids. "static" reads /etc/{subuid,subgid}. [auto,dynamic,static] 233 234 ``` 235 236 ## State directory 237 238 The following files will be created in the state directory, which can be specified with `--state-dir`: 239 * `lock`: lock file 240 * `child_pid`: decimal PID text that can be used for `nsenter(1)`. 241 * `api.sock`: REST API socket. See [`./docs/api.md`](./docs/api.md) and [`./docs/port.md`](./docs/port.md). 242 * `netns` (since v2.0.0): Detached NetNS. Created only with `--detach-netns`. Valid only in the child mount namespace. 243 * `resolv.conf` (since v2.0.0): `resolv.conf` file. Bind-mounted to `/etc/resolv.conf` unles `--detach-netns` is specified. 244 * `hosts` (since v2.0.0): `hosts` file. Bind-mounted to `/etc/hosts` unless `--detach-netns` is specified. 245 246 If `--state-dir` is not specified, RootlessKit creates a temporary state directory on `/tmp` and removes it on exit. 247 248 Undocumented files are subject to change. 249 250 ## Environment variables 251 252 The following environment variables will be set for the child process: 253 * `ROOTLESSKIT_STATE_DIR` (since v0.3.0): absolute path to the state dir 254 * `ROOTLESSKIT_PARENT_EUID` (since v0.8.0): effective UID 255 * `ROOTLESSKIT_PARENT_EGID` (since v0.8.0): effective GID 256 257 Undocumented environment variables are subject to change. 258 259 ## Additional documents 260 - [`./docs/network.md`](./docs/network.md): Networking (`--net`, `--mtu`, `--cidr`, `--disable-host-loopback`, `--slirp4netns-*`, ...) 261 - [`./docs/port.md`](./docs/port.md): Port forwarding (`--port-driver`, `-p`, ...) 262 - [`./docs/mount.md`](./docs/mount.md): Mount (`--propagation`, ...) 263 - [`./docs/process.md`](./docs/process.md): Process (`--pidns`, `--reaper`, `--cgroupns`, `--evacuate-cgroup2`, ...) 264 - [`./docs/api.md`](./docs/api.md): REST API 265 - [`./docs/subid.md`](./docs/subid.md): Sub UIDs and sub GIDs