SYNOPSIS

bwrap [OPTION...] [COMMAND]

DESCRIPTION

bwrap

is a privileged helper for container setup. You are unlikely to use it directly from the commandline, although that is possible.

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 exists. 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 user namespace for the sandbox. Optionally it also sets up new ipc, pid, network and uts namespaces. 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:

--share-user

Don't create a new user namespace

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

--uid UID

Use a custom user id in the sandbox (incompatible with --share-user)

--gid GID

Use a custom group id in the sandbox (incompatible with --share-user)

Options about environment setup:

--chdir DIR

Change directory to DIR

--setenv VAR VALUE

Set an environment variable

--unsetenv VAR

Unset an environment variable

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.

--bind SRC DEST

Bind mount the host path SRC on DEST

--dev-bind SRC DEST

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

--ro-bind SRC DEST

Bind mount the host path SRC readonly on DEST

--proc DEST

Mount procfs on DEST

--dev DEST

Mount new devtmpfs on DEST

--tmpfs DEST

Mount new tmpfs on DEST

--mqueue DEST

Mount new mqueue on DEST

--dir DEST

Create a directory at DEST

--file FD DEST

Copy from the file descriptor FD to DEST

--bind-data FD DEST

Copy from the file descriptor FD to a file which is bind-mounted on DEST

--symlink SRC DEST

Create a symlink at DEST with target SRC

Lockdown options:

--seccomp FD

Load and use seccomp rules from FD. The rules need to be in the form of a compiled eBPF program, as generated by seccomp_export_bpf.

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