bubblewrap kernel requirements
==============================

bubblewrap can be used by various parts of the system to run
partially-trusted programs in a sandboxed environment where their impact
on system security is reduced. For example:

- Flatpak uses bubblewrap to run partially-trusted, user-installable
  apps in a sandboxed environment.

- libgnome-desktop uses bubblewrap to run thumbnailers in a sandboxed
  environment, so that if there are security flaws in an image decoder
  used by a thumbnailer, the process of generating thumbnails for a
  maliciously crafted image cannot be used to attack the rest of the
  system.

bubblewrap can also be used to run trusted programs in a different
environment, for example with different shared libraries available:

- Flatpak uses bubblewrap to run apps with a predictable library stack
  that does not match the rest of the system, even if those apps are
  trusted and so do not need to be sandboxed for security.

- Steam uses bubblewrap to run some games with a predictable library
  stack that does not match the rest of the system.

The necessary capabilities to do this can be obtained in one of two
ways:

- On kernels where unprivileged users can create new user namespaces,
  bubblewrap's bwrap executable can be an ordinary unprivileged program.

- On kernels where this is not possible, bubblewrap will not work unless
  the /usr/bin/bwrap executable is setuid root. Some bubblewrap and Flatpak
  features will not work in this configuration for security reasons.

Newer Debian kernels (Linux 5.10 and newer; Debian 11 and newer)
----------------------------------------------------------------

Debian kernels since 5.10 allow unprivileged users to create new user
namespaces. The bwrap executable can be made non-setuid on these kernels.

By default, the bubblewrap package in Debian no longer installs a setuid
root /usr/bin/bwrap executable.

Ubuntu kernels (Ubuntu 18.04 and newer)
---------------------------------------

Ubuntu kernels also allow unprivileged users to create new user
namespaces. The bwrap executable can be made non-setuid on these kernels,
and the Ubuntu bubblewrap package does not install a setuid executable.

Older Debian kernels (Linux 5.9 and older; Debian 10 and older)
---------------------------------------------------------------

Debian kernels older than 5.10 have support for user namespaces, but
that feature is disabled by default to reduce the kernel's attack
surface.

The bubblewrap package contains configuration in
/usr/lib/sysctl.d/50-bubblewrap.conf to enable user namespaces
(see "Enabling kernel.unprivileged_userns_clone", below).

If this is not desired, system administrators can copy that file
to /etc/sysctl.d/50-bubblewrap.conf and modify it to disable unprivileged
creation of user namespaces, then make bubblewrap setuid root so that it
still works as intended (see "Making bubblewrap setuid root", below).

Custom and third-party kernels
------------------------------

If you compile your own kernel, you will need at least
CONFIG_NAMESPACES=y and preferably CONFIG_USER_NS=y.

If you do not have CONFIG_UTS_NS=y, CONFIG_IPC_NS=y, CONFIG_USER_NS=y,
CONFIG_PID_NS=y and CONFIG_NET_NS=y, then the corresponding bubblewrap
features will not work.

Configuring kernel.unprivileged_userns_clone
--------------------------------------------

This Debian-specific sysctl parameter controls whether unprivileged
users are allowed to create new user namespaces.

If it is set to 0, some attacks against the kernel are made more difficult,
which can increase security. However, some user-space software will not
be able to create a sandboxed environment or will have to rely on a
setuid version of bubblewrap to create a sandboxed environment, which
reduces security. The value of this sysctl parameter is a trade-off
between different security risks.

If this parameter is set to 0, bubblewrap and Flatpak will not work unless
bwrap is made setuid root (see "Making bubblewrap setuid root" below).

The default is 1 for Debian kernels that are version 5.10 or newer,
1 for Ubuntu kernels, or 0 for older Debian kernels. The bubblewrap
package contains configuration in /usr/lib/sysctl.d/50-bubblewrap.conf
to set this parameter to 1 during system startup.

If this is not desired, system administrators can copy
/usr/lib/sysctl.d/50-bubblewrap.conf to /etc/sysctl.d/50-bubblewrap.conf
and modify it to disable unprivileged creation of user namespaces, then
make bubblewrap setuid root so that it still works as intended (see
"Making bubblewrap setuid root", below).

You can view the current setting with:

    cat /proc/sys/kernel/unprivileged_userns_clone

and temporarily set it to 1 (until the next reboot) with:

    sudo sysctl -w kernel.unprivileged_userns_clone=1

Configuring the maximum number of namespaces per user
-----------------------------------------------------

The number of user namespaces per user is limited. The default limit
depends on the amount of RAM available.

Setting this limit to 0 is the recommended way to disable user namespace
creation if this is required as a security hardening measure. bubblewrap
will not work with this limit set to 0, unless it is setuid root (see
"Configuring whether bubblewrap is setuid root" below).

The limit is given by the user.max_user_namespaces sysctl parameter.

You can view the current setting with:

    cat /proc/sys/user/max_user_namespaces

and temporarily set it to a value (until the next reboot) with a
command like:

    sudo sysctl -w user.max_user_namespaces=1000

To set it to a value during system startup, create a file in /etc/sysctl.d
containing a line like this:

    user.max_user_namespaces=1000

Configuring whether bubblewrap is setuid root
---------------------------------------------

To use bubblewrap with kernel.unprivileged_userns_clone set to 0
or user.max_user_namespaces set to 0, it is necessary to make the bwrap
executable setuid root. This gives it the necessary capabilities to set
up containers even when run by an otherwise unprivileged user, and is the
configuration normally used in Debian 10.

This can be a security risk: if there are bugs in bubblewrap, it might be
possible for an unprivileged user to get root privileges by running a
setuid version of the bwrap executable. CVE-2020-5291 and CVE-2016-8659
are examples of bugs that had this effect in the past. However, it allows
the kernel to be configured to disallow creation of user namespaces by
unprivileged users, which prevents attacks like CVE-2016-3135 from being
carried out against the kernel. This is a trade-off between different
security risks.

To avoid other attacks, some Flatpak and bubblewrap features are not
available when bwrap is setuid root, and the absence of those features
is known to break some Flatpak apps. For example, the Flatpak app for
the Chromium web browser will not work with a setuid bwrap executable.

To check whether the bwrap executable will be made setuid root after
the next upgrade, use this command:

    dpkg-statoverride --list /usr/bin/bwrap

To force the bwrap executable to be setuid root, use these commands:

    sudo dpkg-statoverride --quiet --remove /usr/bin/bwrap
    sudo dpkg-statoverride --update --add root root 4755 /usr/bin/bwrap
