bwrap (1) - Linux Manuals

It works by creating a new, completely empty, filesystem namespace where the root is on a tmpfs that is invisible from the host, and which will be automatically cleaned up when the last process exits. You can then use commandline options to construct the root filesystem and process environment for the command to run in the namespace.

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 note the user namespace is required if bwrap is not installed setuid 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 is running 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.

OPTIONS

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

General options:

--help

Print help and exit

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

Options related to kernel namespaces:

--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

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

This is incompatible with --unshare-user, and doesn't work in the setuid version of bubblewrap.

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

--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 VARVALUE

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

Filesystem related options. 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.

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

--bind SRCDEST

Bind mount the host path SRC on DEST

--bind-try SRCDEST

Equal to --bind but ignores non-existent SRC

--dev-bind SRCDEST

Bind mount the host path SRC on DEST, allowing device access

--dev-bind-try SRCDEST

Equal to --dev-bind but ignores non-existent SRC

--ro-bind SRCDEST

Bind mount the host path SRC readonly on DEST

--ro-bind-try SRCDEST

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

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

--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 FDDEST

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 FDDEST

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 FDDEST

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 SRCDEST

Create a symlink at DEST with target SRC

--chmod OCTALPATH

Set the permissions of PATH, which must already exist, to OCTAL.

Lockdown options:

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

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

--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. See prctl, PR_SET_PDEATHSIG.

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

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).