601 lines
12 KiB
Groff
601 lines
12 KiB
Groff
'\" t
|
|
.\" Title: bwrap
|
|
.\" Author: Alexander Larsson
|
|
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
|
|
.\" Date: 04/25/2020
|
|
.\" 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)\&.
|
|
|
|
|
|
|