1SLIRP4NETNS(1)                   User Commands                  SLIRP4NETNS(1)
2
3
4

NAME

6       slirp4netns - User-mode networking for unprivileged network namespaces
7
8
9

SYNOPSIS

11       slirp4netns [OPTION]... PID TAPNAME
12
13
14

DESCRIPTION

16       slirp4netns  provides user-mode networking ("slirp") for network names‐
17       paces.
18
19
20       Unlike veth(4), slirp4netns does not require the root privileges on the
21       host.
22
23
24       Default configuration:
25
26
27              · MTU:               1500
28
29              · CIDR:              10.0.2.0/24
30
31              · Gateway/Host:      10.0.2.2    (network address + 2)
32
33              · DNS:               10.0.2.3    (network address + 3)
34
35              · IPv6 CIDR:         fd00::/64
36
37              · IPv6 Gateway/Host: fd00::2
38
39              · IPv6 DNS:          fd00::3
40
41
42
43

OPTIONS

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
49
50       -e, --exit-fd=FD specify the FD for terminating slirp4netns.
51
52
53       -r,  --ready-fd=FD  specify the FD to write to when the network is con‐
54       figured.
55
56
57       -m, --mtu=MTU specify MTU (max=65521).
58
59
60       --cidr (since v0.3.0) specify CIDR, e.g. 10.0.2.0/24
61
62
63       --disable-host-loopback   (since   v0.3.0)   prohibit   connecting   to
64       127.0.0.1:* on the host namespace
65
66
67       -a, --api-socket (since v0.3.0) API socket path
68
69
70       -6, --enable-ipv6 enable IPv6 (experimental).
71
72
73       -h, --help show help and exit
74
75
76       -v, --version show version and exit
77
78
79

EXAMPLE

81       Terminal 1: Create user/network/mount namespaces
82
83
84              $ unshare --user --map-root-user --net --mount
85              unshared$ echo $$ > /tmp/pid
86
87
88
89       Terminal 2: Start slirp4netns
90
91
92              $ slirp4netns --configure --mtu=65520 $(cat /tmp/pid) tap0
93              starting slirp, MTU=65520
94
95
96
97       Terminal 1: Make sure tap0 is configured and connected to the Internet
98
99
100              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
113
114
115       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
120
121       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
127
128              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
139
140
141

ROUTING PING PACKETS

143       To route ping packets, you need  to  set  up  net.ipv4.ping_group_range
144       properly as the root.
145
146
147       e.g.
148
149
150              $ sudo sh -c "echo 0   2147483647  > /proc/sys/net/ipv4/ping_group_range"
151
152
153
154

FILTERING CONNECTIONS

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
161
162       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
167
168              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
171
172
173

API SOCKET

175       slirp4netns can provide QMP-like API server over an UNIX socket file:
176
177
178              $ slirp4netns --api-socket /tmp/slirp4netns.sock ...
179
180
181
182       add_hostfwd: Expose a port (IPv4 only)
183
184
185              $ 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
189
190
191       If host_addr is not specified, then it defaults to "0.0.0.0".
192
193
194       If  guest_addr  is  not  specified,  then it will be set to the default
195       address that corresponds to --configure.
196
197
198       list_hostfwd: List exposed ports
199
200
201              $ 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
205
206
207       remove_hostfwd: Remove an exposed port
208
209
210              $ json='{"execute": "remove_hostfwd", "arguments": {"id": 42}}'
211              $ echo -n $json | nc -U /tmp/slirp4netns.sock
212              { "return": {}}
213
214
215
216       Remarks:
217
218
219              · Client needs to shutdown the socket with SHUT_WR after sending
220                every request.  i.e. No support for keep-alive and timeout.
221
222              · slirp4netns "stops the world" during processing API requests.
223
224              · A request must be less than 4095 bytes.
225
226              · JSON responses may contain error instead of return.
227
228
229
230

SEE ALSO

232       network_namespaces(7), user_namespaces(7), veth(4)
233
234
235

AVAILABILITY

237       The slirp4netns command is available from https://github.com/rootless-
238       containers/slirp4netns⟩ under GNU GENERAL PUBLIC LICENSE Version 2.
239
240
241
242Rootless Containers                July 2018                    SLIRP4NETNS(1)
Impressum