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 -h, --help (since v0.2.0) show help and exit
103 -v, --version (since v0.2.0) show version and exit
106
110 Terminal 1: Create user/network/mount namespaces
111 $ unshare --user --map-root-user --net --mount
114 unshared$ echo $$ > /tmp/pid
115 Terminal 2: Start slirp4netns
119 $ slirp4netns --configure --mtu=65520 $(cat /tmp/pid) tap0
122 starting slirp, MTU=65520
123 Terminal 1: Make sure tap0 is configured and connected to the Internet
127 unshared$ ip a
130 1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN group default qlen 1000
131 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
132 3: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
133 link/ether c2:28:0c:0e:29:06 brd ff:ff:ff:ff:ff:ff
134 inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
135 valid_lft forever preferred_lft forever
136 inet6 fe80::c028:cff:fe0e:2906/64 scope link
137 valid_lft forever preferred_lft forever
138 unshared$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
139 unshared$ mount --bind /tmp/resolv.conf /etc/resolv.conf
140 unshared$ curl https://example.com
141 Bind-mounting /etc/resolv.conf is only needed when /etc/resolv.conf on
145 the host refers to loopback addresses (127.0.0.X, typically because of
146 dnsmasq(8) or systemd-resolved.service(8)) that cannot be accessed from
147 the namespace.
148 If your /etc/resolv.conf on the host is managed by networkmanager(8) or
151 systemd-resolved.service(8), you might need to mount a new filesystem
152 on /etc instead, so as to prevent the new /etc/resolv.conf from being
153 unmounted unexpectedly when /etc/resolv.conf on the host is regener‐
154 ated.
155 unshared$ mkdir /tmp/a /tmp/b
158 unshared$ mount --rbind /etc /tmp/a
159 unshared$ mount --rbind /tmp/b /etc
160 unshared$ mkdir /etc/.ro
161 unshared$ mount --move /tmp/a /etc/.ro
162 unshared$ cd /etc
163 unshared$ for f in .ro/*; do ln -s $f $(basename $f); done
164 unshared$ rm resolv.conf
165 unshared$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
166 unshared$ curl https://example.com
167
172 To route ping packets, you need to set up net.ipv4.ping_group_range
173 properly as the root.
174 e.g.
177 $ sudo sh -c "echo 0 2147483647 > /proc/sys/net/ipv4/ping_group_range"
180
185 By default, ports listening on INADDR_LOOPBACK (127.0.0.1) on the host
186 are accessible from the child namespace via the gateway (default:
187 10.0.2.2). --disable-host-loopback can be used to prohibit connecting
188 to INADDR_LOOPBACK on the host.
189 However, a host loopback address might be still accessible via the
192 built-in DNS (default: 10.0.2.3) if /etc/resolv.conf on the host refers
193 to a loopback address. You may want to set up iptables for limiting
194 access to the built-in DNS in such a case.
195 unshared$ iptables -A OUTPUT -d 10.0.2.3 -p udp --dport 53 -j ACCEPT
198 unshared$ iptables -A OUTPUT -d 10.0.2.3 -j DROP
199
204 slirp4netns can provide QMP-like API server over an UNIX socket file:
205 $ slirp4netns --api-socket /tmp/slirp4netns.sock ...
208 add_hostfwd: Expose a port (IPv4 only)
212 $ 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}}'
215 $ echo -n $json | nc -U /tmp/slirp4netns.sock
216 { "return": {"id": 42}}
217 If host_addr is not specified, then it defaults to "0.0.0.0".
221 If guest_addr is not specified, then it will be set to the default
224 address that corresponds to --configure.
225 list_hostfwd: List exposed ports
228 $ json='{"execute": "list_hostfwd"}'
231 $ echo -n $json | nc -U /tmp/slirp4netns.sock
232 { "return": {"entries": [{"id": 42, "proto": "tcp", "host_addr": "0.0.0.0", "host_port": 8080, "guest_addr": "10.0.2.100", "guest_port": 80}]}}
233 remove_hostfwd: Remove an exposed port
237 $ json='{"execute": "remove_hostfwd", "arguments": {"id": 42}}'
240 $ echo -n $json | nc -U /tmp/slirp4netns.sock
241 { "return": {}}
242 Remarks:
246 · Client needs to shutdown(2) the socket with SHUT_WR after
249 sending every request. i.e. No support for keep-alive and
250 timeout.
251 · slirp4netns "stops the world" during processing API requests.
253 · A request must be less than 4096 bytes.
255 · JSON responses may contain error instead of return.
257
262 A user can define a network namespace path as opposed to the default
263 process ID:
264 $ slirp4netns --netns-type=path ... /path/to/netns tap0
267 Currently, the netns-type=TYPE argument supports path or pid args with
271 the default being pid.
272 Additionally, a --userns-path=PATH argument can be included to override
275 any user namespace path defaults
276 $ slirp4netns --netns-type=path --userns-path=/path/to/userns /path/to/netns tap0
279
284 Kernel 4.20 bumped up the default value of /proc/sys/net/ipv4/tcp_rmem
285 from 87380 to 131072. This is known to slow down slirp4netns port for‐
286 warding: https://github.com/rootless-containers/slirp4netns/issues/128.
287 As a workaround, you can adjust the value of
290 /proc/sys/net/ipv4/tcp_rmem inside the namespace. No real root privi‐
291 lege is needed to modify the file since kernel 4.15.
292 unshared$ c=$(cat /proc/sys/net/ipv4/tcp_rmem); echo $c | sed -e s/131072/87380/g > /proc/sys/net/ipv4/tcp_rmem
295
300 network_namespaces(7), user_namespaces(7), veth(4)
301
305 The slirp4netns command is available from https://github.com/root‐
306 less-containers/slirp4netns under GNU GENERAL PUBLIC LICENSE Version 2
307 (or later).
308Rootless Containers March 2020 SLIRP4NETNS(1)