Skip to content

Commit 89635e3

Browse files
AkihiroSudaAkihiroSuda
authored
Merge pull request #582 from AkihiroSuda/dev
docs: update
2 parents c4f4a69 + 968f078 commit 89635e3

4 files changed

Lines changed: 42 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
RootlessKit is a Linux-native implementation of "fake root" using [`user_namespaces(7)`](http://man7.org/linux/man-pages/man7/user_namespaces.7.html).
44

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.
5+
The purpose of RootlessKit is to run [Docker](https://rootlesscontaine.rs/getting-started/docker/) and [Kubernetes](https://rootlesscontaine.rs/getting-started/kubernetes/) as an unprivileged user (known as "Rootless mode"), so as to protect the real root on the host from potential container-breakout attacks.
66

77
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
88
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -92,14 +92,14 @@ See also https://rootlesscontaine.rs/getting-started/common/subuid/
9292

9393
### sysctl
9494

95-
Some distros require setting up sysctl:
95+
Old distros may require setting up sysctl such as `kernel.unprivileged_userns_clone=1`:
96+
See <https://rootlesscontaine.rs/getting-started/common/sysctl/>.
9697

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"`
98+
### AppArmor
9999

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/
100+
On Ubuntu 24.04 or later, the `rootlesskit` binary is expected to be exactly under `/usr/bin`.
101+
To install `rootlesskit` on other paths such as `/usr/local/bin`, you need to install a custom AppArmor profile.
102+
See <https://rootlesscontaine.rs/getting-started/common/apparmor/>.
103103

104104
## Usage
105105

@@ -154,7 +154,7 @@ USAGE:
154154
rootlesskit [global options] [arguments...]
155155

156156
VERSION:
157-
2.0.0-alpha.0
157+
3.0.0-rc.0
158158

159159
DESCRIPTION:
160160
RootlessKit is a Linux-native implementation of "fake root" using user_namespaces(7).
@@ -186,50 +186,51 @@ OPTIONS:
186186
187187
Mount:
188188
--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]
189+
--copy-up-mode value copy-up mode [tmpfs+symlink] (default: "tmpfs+symlink")
190+
--propagation value mount propagation [rprivate, rslave] (default: "rprivate")
191191
192192
Network:
193-
--net value network driver [host, pasta(experimental), slirp4netns, vpnkit, lxc-user-nic(experimental)]
193+
--net value network driver [host, none, pasta(experimental), slirp4netns, vpnkit, lxc-user-nic(experimental), gvisor-tap-vsock(experimental)] (default: "host")
194194
--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)
195+
--cidr value CIDR for pasta, slirp4netns and gvisor-tap-vsock networks (default: 10.0.2.0/24)
196196
--ifname value Network interface name (default: tap0 for pasta, slirp4netns, and vpnkit; eth0 for lxc-user-nic)
197197
--disable-host-loopback prohibit connecting to 127.0.0.1:* on the host namespace (default: false)
198198
--ipv6 enable IPv6 routing. Unrelated to port forwarding. Only supported for pasta and slirp4netns. (experimental) (default: false)
199199
--detach-netns detach network namespaces (default: false)
200200
201201
Network [lxc-user-nic]:
202202
--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
203+
--lxc-user-nic-bridge value lxc-user-nic bridge name (default: "lxcbr0")
204204
205205
Network [pasta]:
206-
--pasta-binary value path of pasta binary for --net=pasta
206+
--pasta-binary value path of pasta binary for --net=pasta (default: "pasta")
207207
208208
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)
209+
--slirp4netns-binary value path of slirp4netns binary for --net=slirp4netns (default: "slirp4netns")
210+
--slirp4netns-sandbox value enable slirp4netns sandbox (experimental) [auto, true, false] (the default is planned to be "auto" in future) (default: "false")
211+
--slirp4netns-seccomp value enable slirp4netns seccomp (experimental) [auto, true, false] (the default is planned to be "auto" in future) (default: "false")
212212
213213
Network [vpnkit]:
214-
--vpnkit-binary value path of VPNKit binary for --net=vpnkit
214+
--vpnkit-binary value path of VPNKit binary for --net=vpnkit (default: "vpnkit")
215215
216216
Port:
217-
--port-driver value port driver for non-host network. [none, implicit (for pasta), builtin, slirp4netns]
217+
--port-driver value port driver for non-host network. [none, implicit (for pasta), builtin, slirp4netns, gvisor-tap-vsock(experimental)] (default: "none")
218218
--publish value, -p value [ --publish value, -p value ] publish ports. e.g. "127.0.0.1:8080:80/tcp"
219+
--source-ip-transparent preserve real client source IP using IP_TRANSPARENT (builtin port driver) (default: true)
219220
220221
Process:
221222
--pidns create a PID namespace (default: false)
222223
--cgroupns create a cgroup namespace (default: false)
223224
--utsns create a UTS namespace (default: false)
224225
--ipcns create an IPC namespace (default: false)
225-
--reaper value enable process reaper. Requires --pidns. [auto,true,false]
226+
--reaper value enable process reaper. Requires --pidns. [auto,true,false] (default: "auto")
226227
--evacuate-cgroup2 value evacuate processes into the specified subgroup. Requires --pidns and --cgroupns
227228
228229
State:
229230
--state-dir value state directory
230231
231232
SubID:
232-
--subid-source value the source of the subids. "dynamic" executes /usr/bin/getsubids. "static" reads /etc/{subuid,subgid}. [auto,dynamic,static]
233+
--subid-source value the source of the subids. "dynamic" executes /usr/bin/getsubids. "static" reads /etc/{subuid,subgid}. [auto,dynamic,static] (default: "auto")
233234
234235
```
235236

‎docs/api.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@ NAME:
4040
rootlessctl - RootlessKit API client
4141

4242
USAGE:
43-
rootlessctl [global options] command [command options] [arguments...]
43+
rootlessctl [global options] command [command options]
4444

4545
VERSION:
46-
0.14.0-beta.0
46+
3.0.0-rc.0
4747

4848
COMMANDS:
4949
list-ports List ports
@@ -55,8 +55,8 @@ COMMANDS:
5555
GLOBAL OPTIONS:
5656
--debug debug mode (default: false)
5757
--socket value Path to api.sock (under the "rootlesskit --state-dir" directory), defaults to $ROOTLESSKIT_STATE_DIR/api.sock
58-
--help, -h show help (default: false)
59-
--version, -v print the version (default: false)
58+
--help, -h show help
59+
--version, -v print the version
6060
```
6161

6262
e.g., `rootlessctl --socket /foo/bar/sock info --json`

‎docs/network.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,19 @@ RootlessKit provides several drivers for providing network connectivity:
99
* `--net=lxc-user-nic`: use `lxc-user-nic` (experimental)
1010
* `--net=gvisor-tap-vsock`: use [gvisor-tap-vsock](https://github.com/containers/gvisor-tap-vsock) (experimental)
1111

12-
[Benchmark: iperf3 from the child to the parent (Mar 8, 2020)](https://github.com/rootless-containers/rootlesskit/runs/492498728):
12+
[Benchmark: iperf3 from the child to the parent (Apr 10, 2026)](https://github.com/rootless-containers/rootlesskit/actions/runs/24200485791/job/70642399211):
1313

1414
| Driver | MTU=1500 | MTU=65520
1515
|---------------------------------------|------------|-------------
16-
|`slirp4netns` | 1.06 Gbps | 7.55 Gbps
17-
|`slirp4netns` (with sandbox + seccomp) | 1.05 Gbps | 7.21 Gbps
18-
|`vpnkit` | 0.60 Gbps |(Unsupported)
19-
|`lxc-user-nic` | 31.4 Gbps | 30.9 Gbps
20-
|(rootful veth) | (38.7 Gbps)| (40.8 Gbps)
16+
|`slirp4netns` | 0.84 Gbps | 6.17 Gbps
17+
|`slirp4netns` (with sandbox + seccomp) | 0.80 Gbps | 6.19 Gbps
18+
|`vpnkit` | 0.10 Gbps |(Unsupported)
19+
|`pasta` | 0.87 Gbps | 6.48 Gbps
20+
|`gvisor-tap-vsock` | 1.55 Gbps | 5.40 Gbps
21+
|`lxc-user-nic` | 29.3 Gbps | 30.4 Gbps
22+
|(rootful veth) | (35.0 Gbps)| (36.2 Gbps)
23+
24+
* To be documented: [`bypass4netns`](https://github.com/rootless-containers/bypass4netns) for native performance.
2125

2226
### `--net=host` (default)
2327

@@ -216,11 +220,11 @@ Currently, the MAC address is always set to a random address.
216220
217221
Pros:
218222
* Possible to perform network-namespaced operations, e.g. creating iptables rules, running `tcpdump`
219-
* Supports ICMP Echo (`ping`) when `/proc/sys/net/ipv4/ping_group_range` is configured
220223

221224
Cons:
222225
* Supports only TCP, UDP, and ICMP Echo packets
223226
* Does not support IPv6 routing (`--ipv6`)
227+
* ICMP Echo replies are [forged](https://github.com/containers/gvisor-tap-vsock/issues/428)
224228

225229
The network is configured as follows by default:
226230
* IP: 10.0.2.100/24

‎docs/port.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,12 @@ The default value is `none` (do not expose ports).
66

77
| `--port-driver` | Throughput | Source IP | Notes
88
|----------------------|-------------|----------|-------
9-
| `slirp4netns` | 9.78 Gbps | Propagated |
10-
| `builtin` | 35.6 Gbps | Propagated (since v3.0) | In the case of Rootless Docker, userland-proxy has to be disabled for propagating the source IP.
11-
| `gvisor-tap-vsock` (Experimental) | 3.99 Gbps | Not propagated | Throughput is currently limited; see issue link below for improvement ideas.
9+
| `slirp4netns` | 8.03 Gbps | Propagated |
10+
| `builtin` | 29.9 Gbps | Propagated (since v3.0) | In the case of Rootless Docker, userland-proxy has to be disabled for propagating the source IP.
11+
| `implicit` | 37.6 Gbps | Propagated | Requires `pasta` network
12+
| `gvisor-tap-vsock` (Experimental) | 3.83 Gbps | Not propagated | Throughput is currently limited; see issue link below for improvement ideas.
1213

13-
Benchmark: iperf3 from the parent to the child is measured on GitHub Actions
14+
Benchmark: iperf3 from the parent to the child is measured on GitHub Actions ([Apr 10, 2026](https://github.com/rootless-containers/rootlesskit/actions/runs/24200485791/job/70642399211))
1415

1516
The `builtin` driver is fast and should be the best choice for most use cases.
1617

0 commit comments

Comments
 (0)