slirp4netns(1)

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|PATH 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  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
50
51       -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
55
56       -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
62
63       -m, --mtu=MTU (since v0.2.0) specify MTU (max=65521).
64
65
66       -6, --enable-ipv6 (since v0.2.0, EXPERIMENTAL) enable IPv6
67
68
69       -a, --api-socket (since v0.3.0) API socket path
70
71
72       --cidr (since v0.3.0) specify CIDR, e.g. 10.0.2.0/24
73
74
75       --disable-host-loopback   (since   v0.3.0)   prohibit   connecting   to
76       127.0.0.1:* on the host namespace
77
78
79       --netns-type=TYPE   (since   v0.4.0)  specify  network  namespace  type
80       ([path|pid], default=pid)
81
82
83       --userns-path=PATH (since v0.4.0) specify user namespace path
84
85
86       --create-sandbox (since v0.4.0, EXPERIMENTAL) when running  as  a  root
87       (either on the host, or in a user namespace), create a new mount names‐
88       pace where only /etc and /run are mounted from the  host  and  all  the
89       capabilities except CAP_NET_BIND_SERVICE are dropped.
90
91
92       -h, --help (since v0.2.0) show help and exit
93
94
95       -v, --version (since v0.2.0) show version and exit
96
97
98

EXAMPLE

100       Terminal 1: Create user/network/mount namespaces
101
102
103              $ unshare --user --map-root-user --net --mount
104              unshared$ echo $$ > /tmp/pid
105
106
107
108       Terminal 2: Start slirp4netns
109
110
111              $ slirp4netns --configure --mtu=65520 $(cat /tmp/pid) tap0
112              starting slirp, MTU=65520
113
114
115
116       Terminal 1: Make sure tap0 is configured and connected to the Internet
117
118
119              unshared$ ip a
120              1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN group default qlen 1000
121                  link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
122              3: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
123                  link/ether c2:28:0c:0e:29:06 brd ff:ff:ff:ff:ff:ff
124                  inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
125                     valid_lft forever preferred_lft forever
126                  inet6 fe80::c028:cff:fe0e:2906/64 scope link
127                     valid_lft forever preferred_lft forever
128              unshared$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
129              unshared$ mount --bind /tmp/resolv.conf /etc/resolv.conf
130              unshared$ curl https://example.com
131
132
133
134       Bind-mounting  /etc/resolv.conf is only needed when /etc/resolv.conf on
135       the host refers to loopback addresses (127.0.0.X, typically because  of
136       dnsmasq(8) or systemd-resolved.service(8)) that cannot be accessed from
137       the namespace.
138
139
140       If your /etc/resolv.conf on the host is managed by networkmanager(8) or
141       systemd-resolved.service(8),  you  might need to mount a new filesystem
142       on /etc instead, so as to prevent the new /etc/resolv.conf  from  being
143       unmounted  unexpectedly  when  /etc/resolv.conf on the host is regener‐
144       ated.
145
146
147              unshared$ mkdir /tmp/a /tmp/b
148              unshared$ mount --rbind /etc /tmp/a
149              unshared$ mount --rbind /tmp/b /etc
150              unshared$ mkdir /etc/.ro
151              unshared$ mount --move /tmp/a /etc/.ro
152              unshared$ cd /etc
153              unshared$ for f in .ro/*; do ln -s $f $(basename $f); done
154              unshared$ rm resolv.conf
155              unshared$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
156              unshared$ curl https://example.com
157
158
159
160

ROUTING PING PACKETS

162       To route ping packets, you need  to  set  up  net.ipv4.ping_group_range
163       properly as the root.
164
165
166       e.g.
167
168
169              $ sudo sh -c "echo 0   2147483647  > /proc/sys/net/ipv4/ping_group_range"
170
171
172
173

FILTERING CONNECTIONS

175       By  default, ports listening on INADDR_LOOPBACK (127.0.0.1) on the host
176       are accessible from the  child  namespace  via  the  gateway  (default:
177       10.0.2.2).   --disable-host-loopback can be used to prohibit connecting
178       to INADDR_LOOPBACK on the host.
179
180
181       However, a host loopback address might  be  still  accessible  via  the
182       built-in DNS (default: 10.0.2.3) if /etc/resolv.conf on the host refers
183       to a loopback address.  You may want to set up  iptables  for  limiting
184       access to the built-in DNS in such a case.
185
186
187              unshared$ iptables -A OUTPUT -d 10.0.2.3 -p udp --dport 53 -j ACCEPT
188              unshared$ iptables -A OUTPUT -d 10.0.2.3 -j DROP
189
190
191
192

API SOCKET

194       slirp4netns can provide QMP-like API server over an UNIX socket file:
195
196
197              $ slirp4netns --api-socket /tmp/slirp4netns.sock ...
198
199
200
201       add_hostfwd: Expose a port (IPv4 only)
202
203
204              $ 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}}'
205              $ echo -n $json | nc -U /tmp/slirp4netns.sock
206              { "return": {"id": 42}}
207
208
209
210       If host_addr is not specified, then it defaults to "0.0.0.0".
211
212
213       If  guest_addr  is  not  specified,  then it will be set to the default
214       address that corresponds to --configure.
215
216
217       list_hostfwd: List exposed ports
218
219
220              $ json='{"execute": "list_hostfwd"}'
221              $ echo -n $json | nc -U /tmp/slirp4netns.sock
222              { "return": {"entries": [{"id": 42, "proto": "tcp", "host_addr": "0.0.0.0", "host_port": 8080, "guest_addr": "10.0.2.100", "guest_port": 80}]}}
223
224
225
226       remove_hostfwd: Remove an exposed port
227
228
229              $ json='{"execute": "remove_hostfwd", "arguments": {"id": 42}}'
230              $ echo -n $json | nc -U /tmp/slirp4netns.sock
231              { "return": {}}
232
233
234
235       Remarks:
236
237
238              · Client needs to shutdown(2)  the  socket  with  SHUT_WR  after
239                sending  every  request.   i.e.  No support for keep-alive and
240                timeout.
241
242              · slirp4netns "stops the world" during processing API requests.
243
244              · A request must be less than 4096 bytes.
245
246              · JSON responses may contain error instead of return.
247
248
249
250

DEFINED NAMESPACE PATHS

252       A user can define a network namespace path as opposed  to  the  default
253       process ID:
254
255
256              $ slirp4netns --netns-type=path ... /path/to/netns tap0
257
258
259
260       Currently,  the netns-type=TYPE argument supports path or pid args with
261       the default being pid.
262
263
264       Additionally, a --userns-path=PATH argument can be included to override
265       any user namespace path defaults
266
267
268              $ slirp4netns --netns-type=path --userns-path=/path/to/userns /path/to/netns tap0
269
270
271
272

AVAILABILITY

279       The  slirp4netns  command  is  available  from https://github.com/root‐
280       less-containers/slirp4netns under GNU GENERAL PUBLIC LICENSE Version 2.
281
282
283
284Rootless Containers                July 2018                    SLIRP4NETNS(1)