BWRAP(1)

📦
version 0.13.1 · 18 versions
, in arch rolling

💖 BWRAP(1) 💖

Manual name: bwrap · section: User Commands 🫶

✨ NAME ✨

bwrap — container setup utility 🛠️

🦋 SYNOPSIS 🦋

bwrap [OPTION...] [COMMAND]

🌈 DESCRIPTION 🌈

okay so bwrap is an unprivileged low-level sandboxing tool. bestie, you're probably not gonna use it straight from the commandline every day, but you can — it's totally possible. 💅

It works by making a brand-new, completely empty filesystem namespace where the root lives on a tmpfs that the host can't see, and that whole thing gets automatically cleaned up when the last process exits. ✨ Then you use commandline options to build the root filesystem and the process environment for the command that's gonna run in that namespace. It's giving custom tiny universe energy. 🌌

By default, bwrap creates a new mount namespace for the sandbox. Optionally it also sets up new user, ipc, pid, network and uts namespaces — but heads up, the user namespace is required if bwrap is not run as root. The application in the sandbox can be made to run with a different UID and GID. 👑

If needed (e.g. when using a PID namespace), bwrap runs a minimal pid 1 process in the sandbox that is responsible for reaping zombies. It also detects when the initial application process (pid 2) dies and reports its exit status back to the original spawner. The pid 1 process exits to clean up the sandbox when there are no other processes in the sandbox left. no cap, that little pid 1 is doing main character cleanup duty. 🧹

💅 OPTIONS 💅

When options are used multiple times, the last option wins, unless otherwise specified.

An empty string is not a valid path, so options that take a path reject it with an error. 🚨

🎀 General options 🎀

  • --help — print help and exit. cute, quick, done. ✨
  • --version — print version. 🏷️
  • --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. 🎀
  • --level-prefix — prefix each line of diagnostic output with a numeric severity level enclosed in angle brackets. The severity levels used are based on the constants used by syslog(3): for example, <4> indicates a warning, because LOG_WARNING has numeric value 4. Numbers smaller than 4 indicate fatal errors, and numbers larger than 4 indicate informational messages. These prefixes can be parsed by tools compatible with logger --prio-prefix (see logger(1)) or systemd-cat --level-prefix=1 (see systemd-cat(1)). 🪵
  • --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. 🔑
  • --userns2 FD — after setting up the new namespace, switch into the specified namespace. For this to work the specified namespace must be a descendant of the user namespace used for the setup, so this is only useful in combination with --userns.

This is useful because sometimes bubblewrap itself creates nested user namespaces (to work around some kernel issues) and --userns2 can be used to enter these. 🌀

  • --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. This is currently implemented by setting the user.max_user_namespaces sysctl to 1, and then entering a nested user namespace which is unable to raise that limit in the outer namespace. This option requires --unshare-user. 🔒
  • --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.

Note that this can be combined with --unshare-pid, and in that case it means that the sandbox will be in its own pid namespace, which is a child of the passed in one. 🧸

  • --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). 🏷️

🌸 Options about environment setup 🌸

  • --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. 🧼

🦋 Options for monitoring the sandbox from the outside 🦋

  • --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. 📡

These are all operations that modify the filesystem directly, or mounts stuff in the filesystem. These are applied in the order they are given as arguments. 🧚

Any missing parent directories that are required to create a specified destination are automatically created as needed. Their permissions are normally set to 0755 (rwxr-xr-x). However, if a --perms option is in effect, and it sets the permissions for group or other to zero, then newly-created parent directories will also have their corresponding permission set to zero. --size modifies the size of the created mount when preceding a --tmpfs action; --perms and --size can be combined. ✨

  • --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: for example, --size 10485760 --tmpfs /a --tmpfs /b will mount /a with size 10MiB, then return to the default size for /b. Note that --perms and --size can be combined: --size 10485760 --perms 0700 --tmpfs /s will apply permissions as well as a maximum size to the created tmpfs. 📏
  • --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.

This option can be used multiple times to provide multiple sources. The sources are overlaid in the order given, with the first source on the command line at the bottom of the stack: if a given path to be read exists in more than one source, the file is read from the last such source specified. 🥞

(For readers familiar with overlayfs, note that this is the reverse of the order used by the kernel's lowerdir mount option.) 🙃

  • --overlay RWSRC WORKDIR DEST — writable overlay vibes: writes go to RWSRC, reads prefer RWSRC, then the --overlay-src paths. WORKDIR must be an empty directory on the same filesystem as RWSRC, and is used internally by the kernel. 🧁
  • --tmp-overlay DEST — overlay where writes 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. 🫧
  • --ro-overlay DEST — overlay mounted read-only. This option requires at least two --overlay-src to precede it. 🧊

All three overlay options 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. 🌈

Using --ro-overlay or providing more than one --overlay-src requires a Linux kernel version of 4.0 or later. 🐧

overlayfs limitation alert 🚨 due to limitations of overlayfs, no host directory given via --overlay-src or --overlay may be an ancestor of another, after resolving symlinks. Depending on version, the Linux kernel may or may not enforce this, but if not then overlayfs's behavior is undefined.

For more information see the Overlay Filesystem documentation in the Linux kernel at https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt. 📚

  • --proc DEST — mount procfs on DEST. 🗂️
  • --dev DEST — mount new devtmpfs on DEST. 🎛️
  • --tmpfs DEST — mounts a brand-new tmpfs at DEST 💖 if the option right before it was --perms, that sets the mode of the tmpfs (cute!). Otherwise the tmpfs gets mode 0755. And if the previous option was --size, that sets the size in bytes of the tmpfs. Otherwise it just rocks the default size, no cap ✨
  • --mqueue DEST — mounts a fresh mqueue at DEST 🎀
  • --dir DEST — makes a directory at DEST 🦋 real talk though: if the directory already exists, its permissions stay unmodified and --perms gets straight-up ignored (use --chmod if you actually need to change perms on a directory that's already there, iykyk). If it's newly created and the previous option was --perms, that sets the mode. Otherwise newly-created directories get mode 0755. periodt 💅
  • --file FD DEST — copies from the file descriptor FD to DEST 🌸 if the previous option was --perms, it sets the mode of the new file. Otherwise the file gets mode 0666 (and yes, note that this is not the same as --bind-data, don't @ me 😭)
  • --bind-data FD DEST — copies 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 gets mode 0600 (note that this is not the same as --file, they're literally different beasts 🫶)
  • --ro-bind-data FD DEST — copies 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 gets mode 0600 (again: note that this is not the same as --file ⭐)
  • --symlink SRC DEST — creates a symlink at DEST with target SRC 💜

Since version 0.9.0, it is not considered an error if DEST already exists as a symbolic link and its target is exactly SRC 🎉

Before version 0.9.0, if DEST already existed, this would be treated as an error — even if its target was identical to SRC 💀 historic L tbh

  • --chmod OCTAL PATH — sets the permissions of PATH (which must already exist, no exceptions bestie) to OCTAL 🌈

🔒 Lockdown options 🔒

  • --seccomp FD — loads and uses 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 (rude but true 🙈). Use --add-seccomp-fd if multiple seccomp programs are needed.
  • --add-seccomp-fd FD — loads and uses seccomp rules from FD ✨ rules need to be a compiled cBPF program, as generated by seccomp_export_bpf. This option can be repeated, in which case all the seccomp programs get loaded in the order given — though heads up, the kernel evaluates 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. Also: 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). iconic.
  • --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 — blocks the sandbox on reading from FD until some data is available ⏳ (the sandbox is literally waiting on you, main character energy)
  • --userns-block-fd FD — does not initialize the user namespace but waits on FD until it is ready 🦋 this lets external processes (like newuidmap/newgidmap) set up the user namespace before it gets used by the sandbox process. teamwork fr fr.
  • --info-fd FD — writes information in JSON format about the sandbox to FD 🌸
  • --json-status-fd FD — multiple JSON documents are written to FD, one per line ("JSON lines" format[1] ✨). Each line is a single JSON object. After bwrap has started the child process inside the sandbox, it writes an object with a child-pid member to the --json-status-fd (this duplicates the older --info-fd). The corresponding value is the process ID of the child process in the pid namespace from which bwrap was run. If available, the namespace IDs are also included in the object with the child-pid; again, this duplicates the older --info-fd. When the child process inside the sandbox exits, bwrap writes an object with an exit-code member, and then closes the --json-status-fd. The value corresponding to exit-code is the exit status of the child, in the usual shell encoding (n if it exited normally with status n, or 128+n if it was killed by signal n) 🧮 Other members may be added to those objects in future versions of bwrap, and other JSON objects may be added before or after the current objects — so readers must ignore members and objects that they do not understand. no cap, forward-compatible or bust 💜
  • --new-session — creates 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 (see CVE-2017-5226). that one is genuinely scary, don't skip it 💀
  • --die-with-parent — ensures the child process (COMMAND) dies when bwrap's parent dies 🪦 it kills (SIGKILL) all bwrap sandbox processes in sequence from parent to child, including the COMMAND process, when bwrap or bwrap's parent dies. See prctl, PR_SET_PDEATHSIG. loyal to the end fr 🫶
  • --as-pid-1 — does not create a process with PID=1 in the sandbox to reap child processes 🙈 (so yes, you have to deal with the zombie reaping, good luck bestie)
  • --cap-add CAP — adds 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 — drops 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 — so please be careful about the order they are specified in ⚠️ (order matters, that's the whole vibe)
  • --not-a-security-boundary — declares that this invocation of bwrap is not intended to create a security boundary between the sandbox and the host system 🚧 when this option is given, certain non-fatal sandbox setup failures (such as a subdirectory remount failing because an automounter did not respond in time) will produce a warning and be skipped, rather than causing bwrap to exit with an error. In future releases of bubblewrap the effect of this option might be extended to make other sandbox setup operations non-fatal 👀

This option is intended for callers such as xdg-dbus-proxy or Steam that use bwrap to adjust the filesystem layout for a process, but do not rely on it to create a security boundary 🎮

Other operations that are fundamental to establishing the sandbox (creating namespaces, pivot_root, dropping capabilities) will still cause a hard failure regardless of this option 💀 so no, this isn't a magic "ignore everything" button, bestie.

🌸 ENVIRONMENT 🌸

  • HOME — used as the cwd in the sandbox if --chdir has not been explicitly specified and the current cwd is not present inside the sandbox 🏠 the --setenv option can be used to override the value that is used here 💖

✨ EXIT STATUS ✨

The bwrap command returns the exit status of the initial application process (pid 2 in the sandbox) 🫶 so like, whatever your app said on the way out is what bwrap echoes back. periodt.

📝 NOTES 📝

  1. "JSON lines" format https://jsonlines.org/ 🔗

and that's a wrap on the bwrap(1) page, bestie 🎀 source is the Containers section, page BWRAP(1) — go forth and sandbox responsibly, mwah 💅✨🦋

📦 where this page comes from