bwrap (1) - Linux Man Pages
bwrap: container setup utility
bwrap - container setup utility
- bwrap [OPTION...] [COMMAND]
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 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.
When options are used multiple times, the last option wins, unless otherwise specified.
- Print help and exit
- Print version
- 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:
- Create a new user namespace
- Create a new user namespace if possible else skip it
- Create a new ipc namespace
- Create a new pid namespace
- Create a new network namespace
- Create a new uts namespace
- Create a new cgroup namespace
- Create a new cgroup namespace if possible else skip it
- Unshare all possible namespaces. Currently equivalent with: --unshare-user-try --unshare-ipc --unshare-pid --unshare-net --unshare-uts --unshare-cgroup-try
- Use a custom user id in the sandbox (requires --unshare-user)
- Use a custom group id in the sandbox (requires --unshare-user)
- Use a custom hostname in the sandbox (requires --unshare-uts)
Options about environment setup:
- Change directory to DIR
- Set an environment variable
- Unset an environment variable
Options for monitoring the sandbox from the outside:
- Take a lock on DEST while the sandbox is running. This option can be used multiple times to take locks on multiple files.
- 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 mount the host path SRC on DEST
- Bind mount the host path SRC on DEST, allowing device access
- Bind mount the host path SRC readonly on 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
- Mount procfs on DEST
- Mount new devtmpfs on DEST
- Mount new tmpfs on DEST
- Mount new mqueue on DEST
- Create a directory at DEST
- Copy from the file descriptor FD to DEST
- Copy from the file descriptor FD to a file which is bind-mounted on DEST
- Copy from the file descriptor FD to a file which is bind-mounted readonly on DEST
- Create a symlink at DEST with target SRC
- 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 from the sandbox. On an SELinux system you can specify the SELinux context for the sandbox process(s).
- File label for temporary sandbox content. On an SELinux system you can specify the SELinux context for the sandbox content.
- Block the sandbox on reading from FD until some data is available.
- 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.
- Write information in JSON format about the sandbox to FD.
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.
- 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.
- Do not create a process with PID=1 in the sandbox to reap child processes.
- Add the specified capability when running as privileged user. It accepts the special value ALL to add all the permitted caps.
- 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.
- Used as the cwd in the sandbox if --cwd 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.
The bwrap command returns the exit status of the initial application process (pid 2 in the sandbox).