'\" t
.\"     Title: bwrap
.\"    Author: Alexander Larsson
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/24/2024
.\"    Manual: User Commands
.\"    Source: Project Atomic
.\"  Language: English
.\"
.TH "BWRAP" "1" "" "Project Atomic" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bwrap \- container setup utility
.SH "SYNOPSIS"
.HP \w'\fBbwrap\fR\ 'u
\fBbwrap\fR [\fIOPTION\fR...] [\fICOMMAND\fR]
.SH "DESCRIPTION"
.PP
\fBbwrap\fR
is a privileged helper for container setup\&. You are unlikely to use it directly from the commandline, although that is possible\&.
.PP
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\&.
.PP
By default,
\fBbwrap\fR
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\&.
.PP
If needed (e\&.g\&. when using a PID namespace)
\fBbwrap\fR
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\&.
.SH "OPTIONS"
.PP
When options are used multiple times, the last option wins, unless otherwise specified\&.
.PP
General options:
.PP
\fB\-\-help\fR
.RS 4
Print help and exit
.RE
.PP
\fB\-\-version\fR
.RS 4
Print version
.RE
.PP
\fB\-\-args \fR\fBFD\fR
.RS 4
Parse nul\-separated arguments from the given file descriptor\&. This option can be used multiple times to parse options from multiple sources\&.
.RE
.PP
Options related to kernel namespaces:
.PP
\fB\-\-unshare\-user\fR
.RS 4
Create a new user namespace
.RE
.PP
\fB\-\-unshare\-user\-try\fR
.RS 4
Create a new user namespace if possible else skip it
.RE
.PP
\fB\-\-unshare\-ipc\fR
.RS 4
Create a new ipc namespace
.RE
.PP
\fB\-\-unshare\-pid\fR
.RS 4
Create a new pid namespace
.RE
.PP
\fB\-\-unshare\-net\fR
.RS 4
Create a new network namespace
.RE
.PP
\fB\-\-unshare\-uts\fR
.RS 4
Create a new uts namespace
.RE
.PP
\fB\-\-unshare\-cgroup\fR
.RS 4
Create a new cgroup namespace
.RE
.PP
\fB\-\-unshare\-cgroup\-try\fR
.RS 4
Create a new cgroup namespace if possible else skip it
.RE
.PP
\fB\-\-unshare\-all\fR
.RS 4
Unshare all possible namespaces\&. Currently equivalent with:
\fB\-\-unshare\-user\-try\fR
\fB\-\-unshare\-ipc\fR
\fB\-\-unshare\-pid\fR
\fB\-\-unshare\-net\fR
\fB\-\-unshare\-uts\fR
\fB\-\-unshare\-cgroup\-try\fR
.RE
.PP
\fB\-\-userns \fR\fBFD\fR
.RS 4
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 decendant of the currently active user namespace, owned by the same user\&.
.sp
This is incompatible with \-\-unshare\-user, and doesn\*(Aqt work in the setuid version of bubblewrap\&.
.RE
.PP
\fB\-\-userns2 \fR\fBFD\fR
.RS 4
After setting up the new namespace, switch into the specified namespace\&. For this to work the specified namespace must be a decendant of the user namespace used for the setup, so this is only useful in combination with \-\-userns\&.
.sp
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\&.
.RE
.PP
\fB\-\-pidns \fR\fBFD\fR
.RS 4
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\&.
.sp
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\&.
.RE
.PP
\fB\-\-uid \fR\fBUID\fR
.RS 4
Use a custom user id in the sandbox (requires
\fB\-\-unshare\-user\fR)
.RE
.PP
\fB\-\-gid \fR\fBGID\fR
.RS 4
Use a custom group id in the sandbox (requires
\fB\-\-unshare\-user\fR)
.RE
.PP
\fB\-\-hostname \fR\fBHOSTNAME\fR
.RS 4
Use a custom hostname in the sandbox (requires
\fB\-\-unshare\-uts\fR)
.RE
.PP
Options about environment setup:
.PP
\fB\-\-chdir \fR\fBDIR\fR
.RS 4
Change directory to
DIR
.RE
.PP
\fB\-\-setenv \fR\fBVAR\fR\fB \fR\fBVALUE\fR
.RS 4
Set an environment variable
.RE
.PP
\fB\-\-unsetenv \fR\fBVAR\fR
.RS 4
Unset an environment variable
.RE
.PP
Options for monitoring the sandbox from the outside:
.PP
\fB\-\-lock\-file \fR\fBDEST\fR
.RS 4
Take a lock on
DEST
while the sandbox is running\&. This option can be used multiple times to take locks on multiple files\&.
.RE
.PP
\fB\-\-sync\-fd \fR\fBFD\fR
.RS 4
Keep this file descriptor open while the sandbox is running
.RE
.PP
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\&.
.PP
\fB\-\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Bind mount the host path
SRC
on
DEST
.RE
.PP
\fB\-\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Equal to
\fB\-\-bind\fR
but ignores non\-existent
SRC
.RE
.PP
\fB\-\-dev\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Bind mount the host path
SRC
on
DEST, allowing device access
.RE
.PP
\fB\-\-dev\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Equal to
\fB\-\-dev\-bind\fR
but ignores non\-existent
SRC
.RE
.PP
\fB\-\-ro\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Bind mount the host path
SRC
readonly on
DEST
.RE
.PP
\fB\-\-ro\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Equal to
\fB\-\-ro\-bind\fR
but ignores non\-existent
SRC
.RE
.PP
\fB\-\-remount\-ro \fR\fBDEST\fR
.RS 4
Remount the path
DEST
as readonly\&. It works only on the specified mount point, without changing any other mount point under the specified path
.RE
.PP
\fB\-\-proc \fR\fBDEST\fR
.RS 4
Mount procfs on
DEST
.RE
.PP
\fB\-\-dev \fR\fBDEST\fR
.RS 4
Mount new devtmpfs on
DEST
.RE
.PP
\fB\-\-tmpfs \fR\fBDEST\fR
.RS 4
Mount new tmpfs on
DEST
.RE
.PP
\fB\-\-mqueue \fR\fBDEST\fR
.RS 4
Mount new mqueue on
DEST
.RE
.PP
\fB\-\-dir \fR\fBDEST\fR
.RS 4
Create a directory at
DEST
.RE
.PP
\fB\-\-file \fR\fBFD\fR\fB \fR\fBDEST\fR
.RS 4
Copy from the file descriptor
FD
to
DEST
.RE
.PP
\fB\-\-bind\-data \fR\fBFD\fR\fB \fR\fBDEST\fR
.RS 4
Copy from the file descriptor
FD
to a file which is bind\-mounted on
DEST
.RE
.PP
\fB\-\-ro\-bind\-data \fR\fBFD\fR\fB \fR\fBDEST\fR
.RS 4
Copy from the file descriptor
FD
to a file which is bind\-mounted readonly on
DEST
.RE
.PP
\fB\-\-symlink \fR\fBSRC\fR\fB \fR\fBDEST\fR
.RS 4
Create a symlink at
DEST
with target
SRC
.RE
.PP
Lockdown options:
.PP
\fB\-\-seccomp \fR\fBFD\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-exec\-label \fR\fBLABEL\fR
.RS 4
Exec Label from the sandbox\&. On an SELinux system you can specify the SELinux context for the sandbox process(s)\&.
.RE
.PP
\fB\-\-file\-label \fR\fBLABEL\fR
.RS 4
File label for temporary sandbox content\&. On an SELinux system you can specify the SELinux context for the sandbox content\&.
.RE
.PP
\fB\-\-block\-fd \fR\fBFD\fR
.RS 4
Block the sandbox on reading from FD until some data is available\&.
.RE
.PP
\fB\-\-userns\-block\-fd \fR\fBFD\fR
.RS 4
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\&.
.RE
.PP
\fB\-\-info\-fd \fR\fBFD\fR
.RS 4
Write information in JSON format about the sandbox to FD\&.
.RE
.PP
\fB\-\-new\-session\fR
.RS 4
Create a new terminal session for the sandbox (calls setsid())\&. This disconnects the sandbox from the controlling terminal which means the sandbox can\*(Aqt for instance inject input into the terminal\&.
.sp
Note: In a general sandbox, if you don\*(Aqt use \-\-new\-session, it is recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise the application can feed keyboard input to the terminal\&.
.RE
.PP
\fB\-\-die\-with\-parent\fR
.RS 4
Ensures child process (COMMAND) dies when bwrap\*(Aqs parent dies\&. Kills (SIGKILL) all bwrap sandbox processes in sequence from parent to child including COMMAND process when bwrap or bwrap\*(Aqs parent dies\&. See prctl, PR_SET_PDEATHSIG\&.
.RE
.PP
\fB\-\-as\-pid\-1\fR
.RS 4
Do not create a process with PID=1 in the sandbox to reap child processes\&.
.RE
.PP
\fB\-\-cap\-add \fR\fBCAP\fR
.RS 4
Add the specified capability when running as privileged user\&. It accepts the special value ALL to add all the permitted caps\&.
.RE
.PP
\fB\-\-cap\-drop \fR\fBCAP\fR
.RS 4
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
\fB\-\-cap\-add\fR
and
\fB\-\-cap\-drop\fR
options are processed in the order they are specified on the command line\&. Please be careful to the order they are specified\&.
.RE
.SH "ENVIRONMENT"
.PP
\fBHOME\fR
.RS 4
Used as the cwd in the sandbox if
\fB\-\-chdir\fR
has not been explicitly specified and the current cwd is not present inside the sandbox\&. The
\fB\-\-setenv\fR
option can be used to override the value that is used here\&.
.RE
.SH "EXIT STATUS"
.PP
The
\fBbwrap\fR
command returns the exit status of the initial application process (pid 2 in the sandbox)\&.
