knowledge/technology/applications/utilities/bubblewrap.md

obj	repo	arch-wiki	rev
application	https://github.com/containers/bubblewrap	https://wiki.archlinux.org//title/Bubblewrap	2025-01-09

Bubblewrap

Bubblewrap is a lightweight sandbox application used by Flatpak and other container tools. It has a small installation footprint and minimal resource requirements. Notable features include support for cgroup/IPC/mount/network/PID/user/UTS namespaces and seccomp filtering. Note that bubblewrap drops all capabilities within a sandbox and that child tasks cannot gain greater privileges than its parent.

Configuration

Bubblewrap can be called directly from the command-line and/or within shell scripts as part of a complex wrapper.

A no-op bubblewrap invocation is as follows:

bwrap --dev-bind / / bash

This will spawn a Bash process which should behave exactly as outside a sandbox in most cases. If a sandboxed program misbehaves, you may want to start from the above no-op invocation, and work your way towards a more secure configuration step-by-step.

Desktop entries

Leverage Bubblewrap within desktop entries:

• Bind as read-write the entire host / directory to / in the sandbox
• Re-bind as read-only the /var and /etc directories in the sandbox
• Mount a new devtmpfs filesystem to /dev in the sandbox
• Create a tmpfs filesystem over the sandboxed /run directory
• Disable network access by creating new network namespace

[Desktop Entry]
Name=nano Editor
Exec=bwrap --bind / / --dev /dev --tmpfs /run --unshare-net  st -e nano -o . %f
Type=Application
MimeType=text/plain;

Note

: --dev /dev is required to write to /dev/pty

Options

Usage: bwrap [optiosn] [command]

Option	Description
--args FD	Parse nul-separated arguments from the given file descriptor. This option can be used multiple times to parse options from multiple sources.
--argv0 VALUE	Set argv[0] to the value VALUE before running the program
--unshare-user	Create a new user namespace
--unshare-user-try	Create a new user namespace if possible else skip it
--unshare-ipc	Create a new ipc namespace
--unshare-pid	Create a new pid namespace
--unshare-net	Create a new network namespace
--unshare-uts	Create a new uts namespace
--unshare-cgroup	Create a new cgroup namespace
--unshare-cgroup-try	Create a new cgroup namespace if possible else skip it
--unshare-all	Unshare all possible namespaces. Currently equivalent with: --unshare-user-try --unshare-ipc --unshare-pid --unshare-net --unshare-uts --unshare-cgroup-try
--share-net	Retain the network namespace, overriding an earlier --unshare-all or --unshare-net
--userns FD	Use an existing user namespace instead of creating a new one. The namespace must fulfil the permission requirements for setns(), which generally means that it must be a descendant of the currently active user namespace, owned by the same user.
--disable-userns	Prevent the process in the sandbox from creating further user namespaces, so that it cannot rearrange the filesystem namespace or do other more complex namespace modification.
--assert-userns-disabled	Confirm that the process in the sandbox has been prevented from creating further user namespaces, but without taking any particular action to prevent that. For example, this can be combined with --userns to check that the given user namespace has already been set up to prevent the creation of further user namespaces.
--pidns FD	Use an existing pid namespace instead of creating one. This is often used with --userns, because the pid namespace must be owned by the same user namespace that bwrap uses.
--uid UID	Use a custom user id in the sandbox (requires --unshare-user)
--gid GID	Use a custom group id in the sandbox (requires --unshare-user)
--hostname HOSTNAME	Use a custom hostname in the sandbox (requires --unshare-uts)
--chdir DIR	Change directory to DIR
--setenv VAR VALUE	Set an environment variable
--unsetenv VAR	Unset an environment variable
--clearenv	Unset all environment variables, except for PWD and any that are subsequently set by --setenv
--lock-file DEST	Take a lock on DEST while the sandbox is running. This option can be used multiple times to take locks on multiple files.
--sync-fd FD	Keep this file descriptor open while the sandbox is running
--perms OCTAL	This option does nothing on its own, and must be followed by one of the options that it affects. It sets the permissions for the next operation to OCTAL. Subsequent operations are not affected: for example, --perms 0700 --tmpfs /a --tmpfs /b will mount /a with permissions 0700, then return to the default permissions for /b. Note that --perms and --size can be combined: --perms 0700 --size 10485760 --tmpfs /s will apply permissions as well as a maximum size to the created tmpfs.
--size BYTES	This option does nothing on its own, and must be followed by --tmpfs. It sets the size in bytes for the next tmpfs. For example, --size 10485760 --tmpfs /tmp will create a tmpfs at /tmp of size 10MiB. Subsequent operations are not affected.
--bind SRC DEST	Bind mount the host path SRC on DEST
--bind-try SRC DEST	Equal to --bind but ignores non-existent SRC
--dev-bind SRC DEST	Bind mount the host path SRC on DEST, allowing device access
--dev-bind-try SRC DEST	Equal to --dev-bind but ignores non-existent SRC
--ro-bind SRC DEST	Bind mount the host path SRC readonly on DEST
--ro-bind-try SRC DEST	Equal to --ro-bind but ignores non-existent SRC
--remount-ro DEST	Remount the path DEST as readonly. It works only on the specified mount point, without changing any other mount point under the specified path
--overlay-src SRC	This option does nothing on its own, and must be followed by one of the other overlay options. It specifies a host path from which files should be read if they aren't present in a higher layer.
--overlay RWSRC WORKDIR DEST, --tmp-overlay DEST, --ro-overlay DEST	Use overlayfs to mount the host paths specified by RWSRC and all immediately preceding --overlay-src on DEST. DEST will contain the union of all the files in all the layers. With --overlay all writes will go to RWSRC. Reads will come preferentially from RWSRC, and then from any --overlay-src paths. WORKDIR must be an empty directory on the same filesystem as RWSRC, and is used internally by the kernel. With --tmp-overlay all writes will go to the tmpfs that hosts the sandbox root, in a location not accessible from either the host or the child process. Writes will therefore not be persisted across multiple runs. With --ro-overlay the filesystem will be mounted read-only. This option requires at least two --overlay-src to precede it.
--proc DEST	Mount procfs on DEST
--dev DEST	Mount new devtmpfs on DEST
--tmpfs DEST	Mount new tmpfs on DEST. If the previous option was --perms, it sets the mode of the tmpfs. Otherwise, the tmpfs has mode 0755. If the previous option was --size, it sets the size in bytes of the tmpfs. Otherwise, the tmpfs has the default size.
--mqueue DEST	Mount new mqueue on DEST
--dir DEST	Create a directory at DEST. If the directory already exists, its permissions are unmodified, ignoring --perms (use --chmod if the permissions of an existing directory need to be changed). If the directory is newly created and the previous option was --perms, it sets the mode of the directory. Otherwise, newly-created directories have mode 0755.
--file FD DEST	Copy from the file descriptor FD to DEST. If the previous option was --perms, it sets the mode of the new file. Otherwise, the file has mode 0666 (note that this is not the same as --bind-data).
--bind-data FD DEST	Copy from the file descriptor FD to a file which is bind-mounted on DEST. If the previous option was --perms, it sets the mode of the new file. Otherwise, the file has mode 0600 (note that this is not the same as --file).
--ro-bind-data FD DEST	Copy from the file descriptor FD to a file which is bind-mounted read-only on DEST. If the previous option was --perms, it sets the mode of the new file. Otherwise, the file has mode 0600 (note that this is not the same as --file).
--symlink SRC DEST	Create a symlink at DEST with target SRC.
--chmod OCTAL PATH	Set the permissions of PATH, which must already exist, to OCTAL.
--seccomp FD	Load and use seccomp rules from FD. The rules need to be in the form of a compiled cBPF program, as generated by seccomp_export_bpf. If this option is given more than once, only the last one is used. Use --add-seccomp-fd if multiple seccomp programs are needed.
--add-seccomp-fd FD	Load and use seccomp rules from FD. The rules need to be in the form of a compiled cBPF program, as generated by seccomp_export_bpf. This option can be repeated, in which case all the seccomp programs will be loaded in the order given (note that the kernel will evaluate them in reverse order, so the last program on the bwrap command-line is evaluated first). All of them, except possibly the last, must allow use of the PR_SET_SECCOMP prctl. This option cannot be combined with --seccomp.
--exec-label LABEL	Exec Label from the sandbox. On an SELinux system you can specify the SELinux context for the sandbox process(s).
--file-label LABEL	File label for temporary sandbox content. On an SELinux system you can specify the SELinux context for the sandbox content.
--block-fd FD	Block the sandbox on reading from FD until some data is available.
--userns-block-fd FD	Do not initialize the user namespace but wait on FD until it is ready. This allow external processes (like newuidmap/newgidmap) to setup the user namespace before it is used by the sandbox process.
--info-fd FD	Write information in JSON format about the sandbox to FD.
--json-status-fd FD	Multiple JSON documents are written to FD, one per line.
--new-session	Create a new terminal session for the sandbox (calls setsid()). This disconnects the sandbox from the controlling terminal which means the sandbox can't for instance inject input into the terminal. Note: In a general sandbox, if you don't use --new-session, it is recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise the application can feed keyboard input to the terminal which can e.g. lead to out-of-sandbox command execution.
--die-with-parent	Ensures child process (COMMAND) dies when bwrap's parent dies. Kills (SIGKILL) all bwrap sandbox processes in sequence from parent to child including COMMAND process when bwrap or bwrap's parent dies.
--as-pid-1	Do not create a process with PID=1 in the sandbox to reap child processes.
--cap-add CAP	Add the specified capability CAP, e.g. CAP_DAC_READ_SEARCH, when running as privileged user. It accepts the special value ALL to add all the permitted caps.
--cap-drop CAP	Drop the specified capability when running as privileged user. It accepts the special value ALL to drop all the caps. By default no caps are left in the sandboxed process. The --cap-add and --cap-drop options are processed in the order they are specified on the command line. Please be careful to the order they are specified.