1SLIRP4NETNS(1) User Commands SLIRP4NETNS(1)
2
6 slirp4netns - User-mode networking for unprivileged network namespaces
7
11 slirp4netns [OPTION]... PID 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 interface. IP will be set to 10.0.2.100
46 (network address + 100) by default. IPv6 will be set to a random
47 address.
48 -e, --exit-fd=FD specify the FD for terminating slirp4netns.
51 -r, --ready-fd=FD specify the FD to write to when the network is con‐
54 figured.
55 -m, --mtu=MTU specify MTU (max=65521).
58 --cidr (since v0.3.0) specify CIDR, e.g. 10.0.2.0/24
61 --disable-host-loopback (since v0.3.0) prohibit connecting to
64 127.0.0.1:* on the host namespace
65 -a, --api-socket (since v0.3.0) API socket path
68 -6, --enable-ipv6 enable IPv6 (experimental).
71 -h, --help show help and exit
74 -v, --version show version and exit
77
81 Terminal 1: Create user/network/mount namespaces
82 $ unshare --user --map-root-user --net --mount
85 unshared$ echo $$ > /tmp/pid
86 Terminal 2: Start slirp4netns
90 $ slirp4netns --configure --mtu=65520 $(cat /tmp/pid) tap0
93 starting slirp, MTU=65520
94 Terminal 1: Make sure tap0 is configured and connected to the Internet
98 unshared$ ip a
101 1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN group default qlen 1000
102 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
103 3: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
104 link/ether c2:28:0c:0e:29:06 brd ff:ff:ff:ff:ff:ff
105 inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
106 valid_lft forever preferred_lft forever
107 inet6 fe80::c028:cff:fe0e:2906/64 scope link
108 valid_lft forever preferred_lft forever
109 unshared$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
110 unshared$ mount --bind /tmp/resolv.conf /etc/resolv.conf
111 unshared$ curl https://example.com
112 Bind-mounting /etc/resolv.conf is only needed when /etc/resolv.conf on
116 the host refers to loopback addresses (127.0.0.X, typically because of
117 dnsmasq(8) or systemd-resolved.service(8)) that cannot be accessed from
118 the namespace.
119 If your /etc/resolv.conf on the host is managed by networkmanager(8) or
122 systemd-resolved.service(8), you might need to mount a new filesystem
123 on /etc instead, so as to prevent the new /etc/resolv.conf from being
124 unmounted unexpectedly when /etc/resolv.conf on the host is regener‐
125 ated.
126 unshared$ mkdir /tmp/a /tmp/b
129 unshared$ mount --rbind /etc /tmp/a
130 unshared$ mount --rbind /tmp/b /etc
131 unshared$ mkdir /etc/.ro
132 unshared$ mount --move /tmp/a /etc/.ro
133 unshared$ cd /etc
134 unshared$ for f in .ro/*; do ln -s $f $(basename $f); done
135 unshared$ rm resolv.conf
136 unshared$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
137 unshared$ curl https://example.com
138
143 To route ping packets, you need to set up net.ipv4.ping_group_range
144 properly as the root.
145 e.g.
148 $ sudo sh -c "echo 0 2147483647 > /proc/sys/net/ipv4/ping_group_range"
151
156 By default, ports listening on INADDR_LOOPBACK (127.0.0.1) on the host
157 are accessible from the child namespace via the gateway (default:
158 10.0.2.2). --disable-host-loopback can be used to prohibit connecting
159 to INADDR_LOOPBACK on the host.
160 However, a host loopback address might be still accessible via the
163 built-in DNS (default: 10.0.2.3) if /etc/resolv.conf on the host refers
164 to a loopback address. You may want to set up iptables for limiting
165 access to the built-in DNS in such a case.
166 unshared$ iptables -A OUTPUT -d 10.0.2.3 -p udp --dport 53 -j ACCEPT
169 unshared$ iptables -A OUTPUT -d 10.0.2.3 -j DROP
170
175 slirp4netns can provide QMP-like API server over an UNIX socket file:
176 $ slirp4netns --api-socket /tmp/slirp4netns.sock ...
179 add_hostfwd: Expose a port (IPv4 only)
183 $ 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}}'
186 $ echo -n $json | nc -U /tmp/slirp4netns.sock
187 { "return": {"id": 42}}
188 If host_addr is not specified, then it defaults to "0.0.0.0".
192 If guest_addr is not specified, then it will be set to the default
195 address that corresponds to --configure.
196 list_hostfwd: List exposed ports
199 $ json='{"execute": "list_hostfwd"}'
202 $ echo -n $json | nc -U /tmp/slirp4netns.sock
203 { "return": {"entries": [{"id": 42, "proto": "tcp", "host_addr": "0.0.0.0", "host_port": 8080, "guest_addr": "10.0.2.100", "guest_port": 80}]}}
204 remove_hostfwd: Remove an exposed port
208 $ json='{"execute": "remove_hostfwd", "arguments": {"id": 42}}'
211 $ echo -n $json | nc -U /tmp/slirp4netns.sock
212 { "return": {}}
213 Remarks:
217 · Client needs to shutdown the socket with SHUT_WR after sending
220 every request. i.e. No support for keep-alive and timeout.
221 · slirp4netns "stops the world" during processing API requests.
223 · A request must be less than 4095 bytes.
225 · JSON responses may contain error instead of return.
227
232 network_namespaces(7), user_namespaces(7), veth(4)
233
237 The slirp4netns command is available from ⟨https://github.com/rootless-
238 containers/slirp4netns⟩ under GNU GENERAL PUBLIC LICENSE Version 2.
239Rootless Containers July 2018 SLIRP4NETNS(1)