1SLIRP4NETNS(1) User Commands SLIRP4NETNS(1)
2
6 slirp4netns - User-mode networking for unprivileged network namespaces
7
11 slirp4netns [OPTION]... PID|PATH TAPNAME
12
16 slirp4netns provides user-mode networking ("slirp") for network names‐
17 paces.
18 Unlike veth(4), slirp4netns does not require the root privileges on the
21 host.
22 Default configuration:
25 · MTU: 1500
28 · CIDR: 10.0.2.0/24
30 · Gateway/Host: 10.0.2.2 (network address + 2)
32 · DNS: 10.0.2.3 (network address + 3)
34 · IPv6 CIDR: fd00::/64
36 · IPv6 Gateway/Host: fd00::2
38 · IPv6 DNS: fd00::3
40
45 -c, --configure bring up the TAP interface. IP will be set to
46 10.0.2.100 (network address + 100) by default. IPv6 will be set to a
47 random address. Starting with v0.4.0, the loopback interface (lo) is
48 brought up as well.
49 -e, --exit-fd=FD specify the FD for terminating slirp4netns. When the
52 FD is specified, slirp4netns exits when a poll(2) event happens on the
53 FD.
54 -r, --ready-fd=FD specify the FD to write to when the initialization
57 steps are finished. When the FD is specified, slirp4netns writes "1"
58 to the FD and close the FD. Prior to v0.4.0, the FD was written after
59 the network configuration (-c) but before the API socket configuration
60 (-a).
61 -m, --mtu=MTU (since v0.2.0) specify MTU (max=65521).
64 -6, --enable-ipv6 (since v0.2.0, EXPERIMENTAL) enable IPv6
67 -a, --api-socket (since v0.3.0) API socket path
70 --cidr (since v0.3.0) specify CIDR, e.g. 10.0.2.0/24
73 --disable-host-loopback (since v0.3.0) prohibit connecting to
76 127.0.0.1:* on the host namespace
77 --netns-type=TYPE (since v0.4.0) specify network namespace type
80 ([path|pid], default=pid)
81 --userns-path=PATH (since v0.4.0) specify user namespace path
84 --enable-sandbox (since v0.4.0) enter the user namespace and create a
87 new mount namespace where only /etc and /run are mounted from the host.
88 Requires /etc/resolv.conf not to be a symlink to a file outside /etc
91 and /run.
92 When running as the root, the process does not enter the user namespace
95 but all the capabilities except CAP_NET_BIND_SERVICE are dropped.
96 --enable-seccomp (since v0.4.0, EXPERIMENTAL) enable seccomp(2) to
99 limit syscalls. Typically used in conjunction with --enable-sandbox.
100 --outbound-addr=IPv4 (since v1.1.0, EXPERIMENTAL) specify outbound ipv4
103 address slirp should bind to
104 --outbound-addr=INTERFACE (since v1.1.0, EXPERIMENTAL) specify outbound
107 interface slirp should bind to (ipv4 traffic only)
108 --outbound-addr=IPv6 (since v1.1.0, EXPERIMENTAL) specify outbound ipv6
111 address slirp should bind to
112 --outbound-addr6=INTERFACE (since v1.1.0, EXPERIMENTAL) specify out‐
115 bound interface slirp should bind to (ipv6 traffic only)
116 --disable-dns (since v1.1.0) disable built-in DNS (10.0.2.3 by default)
119 --macaddress (since v1.1.9) specify MAC address of the TAP interface
122 (only valid with -c)
123 -h, --help (since v0.2.0) show help and exit
126 -v, --version (since v0.2.0) show version and exit
129
133 Terminal 1: Create user/network/mount namespaces
134 (host)$ unshare --user --map-root-user --net --mount
137 (namespace)$ echo $$ > /tmp/pid
138 In this documentation, we use (host)$ as the prompt of the host shell,
142 (namespace)$ as the prompt of the shell running in the namespaces.
143 If unshare fails, try the following commands (known to be needed on
146 Debian, Arch, and old CentOS 7.X):
147 (host)$ sudo sh -c 'echo "user.max_user_namespaces=28633" >> /etc/sysctl.d/userns.conf'
150 (host)$ if [ -f /proc/sys/kernel/unprivileged_userns_clone ]; then sudo sh -c 'echo "kernel.unprivileged_userns_clone=1" >> /etc/sysctl.d/userns.conf'; fi
151 (host)$ sudo sysctl --system
152 Terminal 2: Start slirp4netns
156 (host)$ slirp4netns --configure --mtu=65520 $(cat /tmp/pid) tap0
159 starting slirp, MTU=65520
160 Terminal 1: Make sure tap0 is configured and connected to the Internet
164 (namespace)$ ip a
167 1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN group default qlen 1000
168 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
169 3: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
170 link/ether c2:28:0c:0e:29:06 brd ff:ff:ff:ff:ff:ff
171 inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
172 valid_lft forever preferred_lft forever
173 inet6 fe80::c028:cff:fe0e:2906/64 scope link
174 valid_lft forever preferred_lft forever
175 (namespace)$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
176 (namespace)$ mount --bind /tmp/resolv.conf /etc/resolv.conf
177 (namespace)$ curl https://example.com
178 Bind-mounting /etc/resolv.conf is only needed when /etc/resolv.conf on
182 the host refers to loopback addresses (127.0.0.X, typically dnsmasq(8)
183 or systemd-resolved.service(8)) that cannot be accessed from the names‐
184 pace.
185 If your /etc/resolv.conf on the host is managed by networkmanager(8) or
188 systemd-resolved.service(8), you might need to mount a new filesystem
189 on /etc instead, so as to prevent the new /etc/resolv.conf from being
190 unmounted unexpectedly when /etc/resolv.conf on the host is regener‐
191 ated.
192 (namespace)$ mkdir /tmp/a /tmp/b
195 (namespace)$ mount --rbind /etc /tmp/a
196 (namespace)$ mount --rbind /tmp/b /etc
197 (namespace)$ mkdir /etc/.ro
198 (namespace)$ mount --move /tmp/a /etc/.ro
199 (namespace)$ cd /etc
200 (namespace)$ for f in .ro/*; do ln -s $f $(basename $f); done
201 (namespace)$ rm resolv.conf
202 (namespace)$ echo "nameserver 10.0.2.3" > resolv.conf
203 (namespace)$ curl https://example.com
204 These steps can be simplified with rootlesskit --copy-up=/etc if root‐
208 lesskit is installed:
209 (host)$ rootlesskit --net=slirp4netns --copy-up=/etc bash
212 (namespace)$ cat /etc/resolv.conf
213 nameserver 10.0.2.3
214
219 To route ping packets, you may need to set up net.ipv4.ping_group_range
220 properly as the root.
221 e.g.
224 (host)$ sudo sh -c 'echo "net.ipv4.ping_group_range=0 2147483647" > /etc/sysctl.d/ping_group_range.conf'
227 (host)$ sudo sysctl --system
228
233 By default, ports listening on INADDR_LOOPBACK (127.0.0.1) on the host
234 are accessible from the child namespace via the gateway (default:
235 10.0.2.2). --disable-host-loopback can be used to prohibit connecting
236 to INADDR_LOOPBACK on the host.
237 However, a host loopback address might be still accessible via the
240 built-in DNS (default: 10.0.2.3) if /etc/resolv.conf on the host refers
241 to a loopback address. You may want to set up iptables for limiting
242 access to the built-in DNS in such a case.
243 (host)$ nsenter -t $(cat /tmp/pid) -U -n
246 (namespace)$ iptables -A OUTPUT -d 10.0.2.3 -p udp --dport 53 -j ACCEPT
247 (namespace)$ iptables -A OUTPUT -d 10.0.2.3 -j DROP
248
253 slirp4netns can provide QMP-like API server over an UNIX socket file:
254 (host)$ slirp4netns --api-socket /tmp/slirp4netns.sock ...
257 add_hostfwd: Expose a port (IPv4 only)
261 (namespace)$ json='{"execute": "add_hostfwd", "arguments": {"proto": "tcp", "host_addr": "0.0.0.0", "host_port": 8080, "guest_addr": "10.0.2.100", "guest_port": 80}}'
264 (namespace)$ echo -n $json | nc -U /tmp/slirp4netns.sock
265 {"return": {"id": 42}}
266 If host_addr is not specified, then it defaults to "0.0.0.0".
270 If guest_addr is not specified, then it will be set to the default
273 address that corresponds to --configure.
274 list_hostfwd: List exposed ports
277 (namespace)$ json='{"execute": "list_hostfwd"}'
280 (namespace)$ echo -n $json | nc -U /tmp/slirp4netns.sock
281 {"return": {"entries": [{"id": 42, "proto": "tcp", "host_addr": "0.0.0.0", "host_port": 8080, "guest_addr": "10.0.2.100", "guest_port": 80}]}}
282 remove_hostfwd: Remove an exposed port
286 (namespace)$ json='{"execute": "remove_hostfwd", "arguments": {"id": 42}}'
289 (namespace)$ echo -n $json | nc -U /tmp/slirp4netns.sock
290 {"return": {}}
291 Remarks:
295 · Client needs to shutdown(2) the socket with SHUT_WR after
298 sending every request. i.e. No support for keep-alive and
299 timeout.
300 · slirp4netns "stops the world" during processing API requests.
302 · A request must be less than 4096 bytes.
304 · JSON responses may contain error instead of return.
306
311 A user can define a network namespace path as opposed to the default
312 process ID:
313 (host)$ slirp4netns --netns-type=path ... /path/to/netns tap0
316 Currently, the netns-type=TYPE argument supports path or pid args with
320 the default being pid.
321 Additionally, a --userns-path=PATH argument can be included to override
324 any user namespace path defaults
325 (host)$ slirp4netns --netns-type=path --userns-path=/path/to/userns /path/to/netns tap0
328
333 A user can defined preferred outbound ipv4 and ipv6 address in multi IP
334 scenarios.
335 (host)$ slirp4netns --outbound-addr=10.2.2.10 --outbound-addr6=fe80::10 ...
338 Optionally you can use interface names instead of ip addresses.
342 (host)$ slirp4netns --outbound-addr=eth0 --outbound-addr6=eth0 ...
345
350 The easiest way to allow inter-namespace communication is to nest net‐
351 work namespaces inside the slirp4netns's network namespace.
352 (host)$ nsenter -t $(cat /tmp/pid) -U -n -m
355 (namespace)$ mount -t tmpfs none /run
356 (namespace)$ ip netns add foo
357 (namespace)$ ip netns add bar
358 (namespace)$ ip link add veth-foo type veth peer name veth-bar
359 (namespace)$ ip link set veth-foo netns foo
360 (namespace)$ ip link set veth-bar netns bar
361 (namespace)$ ip netns exec foo ip link set veth-foo name eth0
362 (namespace)$ ip netns exec bar ip link set veth-bar name eth0
363 (namespace)$ ip netns exec foo ip link set lo up
364 (namespace)$ ip netns exec bar ip link set lo up
365 (namespace)$ ip netns exec foo ip link set eth0 up
366 (namespace)$ ip netns exec bar ip link set eth0 up
367 (namespace)$ ip netns exec foo ip addr add 192.168.42.100/24 dev eth0
368 (namespace)$ ip netns exec bar ip addr add 192.168.42.101/24 dev eth0
369 (namespace)$ ip netns exec bar ping 192.168.42.100
370 However, this method does not work when you want to allow communication
374 across multiple slirp4netns instances. To allow communication across
375 multiple slirp4netns instances, you need to combine another network
376 stack such as vde_plug(1) with slirp4netns.
377 (host)$ vde_plug --daemon switch:///tmp/switch null://
380 (host)$ nsenter -t $(cat /tmp/pid-instance0) -U -n
381 (namespace-instance0)$ vde_plug --daemon vde:///tmp/switch tap://vde
382 (namespace-instance0)$ ip link set vde up
383 (namespace-instance0)$ ip addr add 192.168.42.100/24 dev vde
384 (namespace-instance0)$ exit
385 (host)$ nsenter -t $(cat /tmp/pid-instance1) -U -n
386 (namespace-instance1)$ vde_plug --daemon vde:///tmp/switch tap://vde
387 (namespace-instance1)$ ip link set vde up
388 (namespace-instance1)$ ip addr add 192.168.42.101/24 dev vde
389 (namespace-instance1)$ ping 192.168.42.100
390
395 VXLAN is known to work. See Usernetes project for the example of
396 multi-node rootless Kubernetes cluster with VXLAN:
397 https://github.com/rootless-containers/usernetes
398
402 Kernel 4.20 bumped up the default value of /proc/sys/net/ipv4/tcp_rmem
403 from 87380 to 131072. This is known to slow down slirp4netns port for‐
404 warding: https://github.com/rootless-containers/slirp4netns/issues/128.
405 As a workaround, you can adjust the value of
408 /proc/sys/net/ipv4/tcp_rmem inside the namespace. No real root privi‐
409 lege is needed to modify the file since kernel 4.15.
410 (host)$ nsenter -t $(cat /tmp/pid) -U -n -m
413 (namespace)$ c=$(cat /proc/sys/net/ipv4/tcp_rmem); echo $c | sed -e s/131072/87380/g > /proc/sys/net/ipv4/tcp_rmem
414
419 network_namespaces(7), user_namespaces(7), veth(4)
420
424 The slirp4netns command is available from https://github.com/root‐
425 less-containers/slirp4netns under GNU GENERAL PUBLIC LICENSE Version 2
426 (or later).
427Rootless Containers November 2020 SLIRP4NETNS(1)