slirp4netns provides user-mode networking ("slirp") for unprivileged network namespaces.

• Motivation
• Projects using slirp4netns
• Maintenance policy
• Quick start
  • Install
  • Usage
• Manual
• Benchmarks
  • iperf3 (netns -> host)
• Install from source
• Acknowledgement
• License

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").

Kubernetes distributions:

• Usernetes (via RootlessKit)
• k3s (via RootlessKit)

Container engines:

• Podman
• Buildah
• ctnr (via slirp-cni-plugin)
• Docker & Moby (optionally, via RootlessKit)
• containerd/nerdctl (optionally, via RootlessKit)

Tools:

• RootlessKit
• become-root
• slirp-cni-plugin

See https://github.com/rootless-containers/slirp4netns/releases for the releases.

See https://github.com/rootless-containers/slirp4netns/security/advisories for the past security advisories.

⚠️ We had been collecting the vulnerabilities of QEMU/libslirp in this slirp4netns repo until the end of 2020, as the slirp4netns releases prior to v1.0.0 were always statically linked with a specific version of QEMU/libslirp. Starting with 2021, the vulnerabilities of libslirp are no longer collected in this slirp4netns repo, as slirp4netns >= v1.0.0 can be linked with an arbitrary version of libslirp.

$ slirp4netns --version
slirp4netns version 1.1.8
commit: d361001f495417b880f20329121e3aa431a8f90f
libslirp: 4.4.0
SLIRP_CONFIG_VERSION_MAX: 3
libseccomp: 2.4.3

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.

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: slirp4netns.1.md

• Description
• Options
• Example
• Routing ping packets
• API socket
• Defined namespace paths
• Outbound addresses
• Inter-namespace communication
• Inter-host communication
• Bugs

Aug 28, 2018, on RootlessKit Travis: rootless-containers/rootlesskit#16

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.

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 with LDFLAGS=-static.
• If you set --prefix to $HOME, you don't need to run make install with sudo.

See vendor/README.md.

GPL-2.0-or-later