User namespace requirements

Flatpak uses bubblewrap (bwrap) to set up its sandbox environment. Depending on how Flatpak was configured for your operating system, it can either use a system copy of the bubblewrap executable (usually /usr/bin/bwrap), or its own included copy of bubblewrap (usually /usr/libexec/flatpak-bwrap).

There are two ways this can work.

Unprivileged bubblewrap

This is the preferred mode for modern operating systems. The kernel must allow unprivileged users to create new user namespaces.

This mode is available in most recent operating systems in their default configuration, including:

• all recent versions of Ubuntu, Fedora, etc.
• Debian version 11 or newer, in its default configuration
• Red Hat Enterprise Linux version 8 or newer, in its default configuration
• Arch Linux with the default linux kernel and the bubblewrap package

If you are designing an operating system or tuning system parameters, the requirements for this mode are:

• The bwrap or flatpak-bwrap executable must not be setuid root: its permissions should usually be -rwxr-xr-x (0755).
• The kernel must have at least CONFIG_USER_NS=y enabled. Other namespace features like CONFIG_PID_NS=y are recommended.
• sysctl parameters that limit namespace creation, such as user.max_user_namespaces and user.max_mnt_namespaces (/proc/sys/user/max_user_namespaces and so on) must be set to a sufficiently large value. The default value is usually suitable: it depends on available RAM and is usually in the tens of thousands.
• If the kernel has been patched to add a kernel.unprivileged_userns_clone sysctl (/proc/sys/kernel/unprivileged_userns_clone), then that option must be set to 1.

Setuid bubblewrap

This mode is a fallback for older operating systems where the kernel either does not support user namespaces, or has been configured to disallow their use by unprivileged users.

This mode is not recommended, and some Flatpak apps and features will not work. In particular, this affects anything that needs flatpak-spawn --share-pids or flatpak-spawn --expose-pids, including Chromium and Steam. We expect that increasingly many Flatpak apps will require unprivileged bubblewrap in future.

Only a few operating systems are known to need this:

• Debian version 10 or older (including Debian derivatives like SteamOS 2, but not Ubuntu)
• Red Hat Enterprise Linux (RHEL) version 7 or older
• Arch Linux with the non-default linux-hardened kernel in its default configuration

This is a security trade-off. Disallowing unprivileged use of user namespaces reduces the kernel's attack surface, which mitigates some attacks; but it also disallows some sandboxing techniques, which prevents other attacks from being mitigated. Making bwrap or flatpak-bwrap setuid root also carries some risk: an attacker might be able to exploit vulnerabilities in bwrap to achieve root privilege escalation.

To use this mode, the bwrap or flatpak-bwrap executable must be setuid root. Its permissions should usually be -rwsr-xr-x (04755), owned by root:root. On Arch Linux and its derivatives, installing the bubblewrap-suid package provides this.

Changing from setuid to unprivileged

If you are using an operating system where bwrap is setuid by default, it is possible to reconfigure it to use the recommended unprivileged mode instead:

• echo kernel.unprivileged_userns_clone=1 | sudo tee /etc/sysctl.d/50-bubblewrap.conf
• sudo sysctl -w kernel.unprivileged_userns_clone=1
• Make the bwrap executable non-setuid:
  • If you are using a Debian-based system: sudo dpkg-statoverride --update --add root root 0755 /usr/bin/bwrap
  • If you are using an Arch Linux-based system: install the bubblewrap package instead of bubblewrap-suid
  • If you are using Gentoo: disable the suid USE flag for the bubblewrap package
  • Otherwise: sudo chmod u-s /usr/bin/bwrap (you will need to repeat this every time you upgrade bubblewrap)
• systemctl --user restart flatpak-portal.service, or log out and back in