Bubblewrap Container

The bubblewrap container uses the bubblewrap utility to create a new kernel namespace and runs the requested binary in this sandbox isolated from the rest of the system. This is the base technology used in the Linux Flatpak ecosystem. See the Bubblewrap Container Example for an example setup with test applications.

At least bubblewrap version 0.5 needs to be installed on the target system. Using the latest upstream release is recommended though.

The bubblewrap container is built as a plugin and loaded, but not enabled by default. It can be configured in the application manager's config file using its unique ID: bubblewrap:

containers:
  bubblewrap:
    sharedNamespaces: [ '-all', '+net' ]
    bindMountHome: yes
    configuration:
      symlink:
        usr/lib: '/lib'
        usr/lib64: '/lib64'
        usr/bin: [ '/bin', '/sbin' ]
      ro-bind:
        /usr/bin: '/usr/bin'
        /usr/lib: '/usr/lib'
        /etc: '/etc'
        /usr/share/fonts: '/usr/share/fonts'
        /usr/share/fontconfig: '/usr/share/fontconfig'
        /usr/share/ca-certificates: '/usr/share/ca-certificates'
        /sys/dev/char: '/sys/dev/char'
        ${CONFIG_DIR}/imports: '${CONFIG_DIR}/imports'
      ro-bind-try:
        /usr/lib64: '/usr/lib64'
        '/sys/devices/pci0000:00': '/sys/devices/pci0000:00'
        /usr/share/glvnd/egl_vendor.d: '/usr/share/glvnd/egl_vendor.d'
        /usr/share/X11/xkb: '/usr/share/X11/xkb'
        /run/resolvconf: '/run/resolvconf'
      dev: '/dev'
      dev-bind:
        /dev/dri: '/dev/dri'
      tmpfs:
        /tmp
      proc:
        /proc

The bubblewrap container accepts the following configuration settings:

Settings Name	Type	Description
`bwrap-location`	string	The path to the `bwrap` binary. If no path is configured the standard `$PATH` is used to find the executable.
`configuration`	object	A two-stage mapping object to configure the sandboxing of the plugin. The top-level `keys` are translated into options passed to the bubblewrap binary. The values themselves are used as arguments for those options. Here is an example configuration: configuration: symlink: usr/lib: '/lib' usr/lib64: '/lib64' usr/bin: [ '/bin', '/sbin' ] ro-bind: /usr/bin: '/usr/bin' /usr/lib: '/usr/lib' /usr/lib64: '/usr/lib64'
`bindMountHome`	bool	Mounts the whole Home directory of the current user into the container. This can be used for development purposes. (default: false)
`sharedNamespaces`	list<string>	This gives you fine-grained control over the shared kernel namespaces that are (not) shared with the container. The following namespaces are supported: `all, net, user, ipc, pid, net, uts, cgroup`. Each entry has to be prefixed with + or - to indicate whether the namespace should be shared or not. The first entry has to be `all` and sets the baseline: you can unshare all and then share specific namespaces (`-all, +pid, +ipc`), or you can share all and then unshare individual namespaces (`+all, -net`). (default: `-all`)
`networkSetupScript`	string	The path to a shell script, that is executed when the container starts and stops in order to correctly setup and shutdown networking for the container. See the Bubblewrap Container Example for an example script. Note: You most likely want to have the network namespace shared, if you set this option: `sharedNamespaces: [ '-all', '+net' ]`
`unshareNetwork`	string	Deprecated. Please use `sharedNamespaces` and `networkSetupScript` instead.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.