slirp4netns: User-mode networking for unprivileged network namespaces
slirp4netns provides user-mode networking ("slirp") for unprivileged network namespaces.
- Motivation
- Projects using slirp4netns
- Maintenance policy
- Quick start
- Manual
- Benchmarks
- Install from source
- Acknowledgement
- License
Motivation
Starting with Linux 3.8, unprivileged users can create network_namespaces(7)
along with user_namespaces(7)
.
However, unprivileged network namespaces had not been very useful, because creating veth(4)
pairs across the host and network namespaces still requires the root privileges. (i.e. No internet connection)
slirp4netns allows connecting a network namespace to the Internet in a completely unprivileged way, by connecting a TAP device in a network namespace to the usermode TCP/IP stack ("slirp").
Projects using slirp4netns
Kubernetes distributions:
Container engines:
- Podman
- Buildah
- ctnr (via slirp-cni-plugin)
- Docker & Moby (optionally, via RootlessKit)
- containerd/nerdctl (optionally, via RootlessKit)
Tools:
Maintenance policy
Version | Status |
---|---|
v1.2.x | ✅ Active |
v1.1.x | End of Life (May 2, 2022) |
v1.0.x | End of Life (Jun 2, 2020) |
v0.4.x | End of Life (Sep 30, 2020) |
v0.3.x | End of Life (Mar 31, 2020) |
v0.2.x | End of Life (Aug 30, 2019) |
Early versions prior to v0.2.x | End of Life (Jan 5, 2019) |
See https://github.com/rootless-containers/slirp4netns/releases for the releases.
Security advisories
See https://github.com/rootless-containers/slirp4netns/security/advisories for the past security advisories.
Run slirp4netns --version
to check the version of the linked libslirp.
$ slirp4netns --version
slirp4netns version 1.1.8
commit: d361001f495417b880f20329121e3aa431a8f90f
libslirp: 4.4.0
SLIRP_CONFIG_VERSION_MAX: 3
libseccomp: 2.4.3
Quick start
Install
Statically linked binaries available for x86_64, aarch64, armv7l, s390x, ppc64le, and riscv64: https://github.com/rootless-containers/slirp4netns/releases
Also available as a package on almost all Linux distributions:
- RHEL/CentOS (since 7.7 and 8.0)
- Fedora (since 28)
- Arch Linux
- openSUSE (since Leap 15.0)
- SUSE Linux Enterprise (since 15)
- Debian GNU/Linux (since 10.0)
- Ubuntu (since 19.04)
- NixOS
- Gentoo Linux
- Slackware
- Void Linux
- Alpine Linux (since 3.14)
e.g.
$ sudo apt-get install slirp4netns
To install slirp4netns from the source, see Install from source.
Usage
Terminal 1: Create user/network/mount namespaces
(host)$ unshare --user --map-root-user --net --mount
(namespace)$ echo $$ > /tmp/pid
In this documentation, we use (host)$
as the prompt of the host shell, (namespace)$
as the prompt of the shell running in the namespaces.
If unshare
fails, try the following commands (known to be needed on Debian, Arch, and old CentOS 7.X):
(host)$ sudo sh -c 'echo "user.max_user_namespaces=28633" >> /etc/sysctl.d/userns.conf'
(host)$ [ -f /proc/sys/kernel/unprivileged_userns_clone ] && sudo sh -c 'echo "kernel.unprivileged_userns_clone=1" >> /etc/sysctl.d/userns.conf'
(host)$ sudo sysctl --system
Terminal 2: Start slirp4netns
(host)$ slirp4netns --configure --mtu=65520 --disable-host-loopback $(cat /tmp/pid) tap0
starting slirp, MTU=65520
...
Terminal 1: Make sure the tap0
is configured and connected to the Internet
(namespace)$ ip a
1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
3: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000
link/ether c2:28:0c:0e:29:06 brd ff:ff:ff:ff:ff:ff
inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0
valid_lft forever preferred_lft forever
inet6 fe80::c028:cff:fe0e:2906/64 scope link
valid_lft forever preferred_lft forever
(namespace)$ echo "nameserver 10.0.2.3" > /tmp/resolv.conf
(namespace)$ mount --bind /tmp/resolv.conf /etc/resolv.conf
(namespace)$ curl https://example.com
Manual
Manual: slirp4netns.1.md
- Description
- Options
- Example
- Routing ping packets
- API socket
- Defined namespace paths
- Outbound addresses
- Inter-namespace communication
- Inter-host communication
- Bugs
Benchmarks
iperf3 (netns -> host)
Aug 28, 2018, on RootlessKit Travis: rootless-containers/rootlesskit#16
Implementation | MTU=1500 | MTU=4000 | MTU=16384 | MTU=65520 |
---|---|---|---|---|
vde_plug | 763 Mbps | Unsupported | Unsupported | Unsupported |
VPNKit | 514 Mbps | 526 Mbps | 540 Mbps | Unsupported |
slirp4netns | 1.07 Gbps | 2.78 Gbps | 4.55 Gbps | 9.21 Gbps |
slirp4netns is faster than vde_plug and VPNKit because slirp4netns is optimized to avoid copying packets across the namespaces.
The latest revision of slirp4netns is regularly benchmarked (make benchmark
) on CI.
Install from source
Build dependencies (apt-get
):
$ sudo apt-get install libglib2.0-dev libslirp-dev libcap-dev libseccomp-dev
Build dependencies (dnf
):
$ sudo dnf install glib2-devel libslirp-devel libcap-devel libseccomp-devel
Installation steps:
$ ./autogen.sh
$ ./configure --prefix=/usr
$ make
$ sudo make install
- libslirp needs to be v4.1.0 or later.
- To build
slirp4netns
as a static binary, run./configure
withLDFLAGS=-static
. - If you set
--prefix
to$HOME
, you don't need to runmake install
withsudo
.
Acknowledgement
See vendor/README.md
.