381 lines
17 KiB
XML
381 lines
17 KiB
XML
|
<?xml version="1.0"?>
|
||
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
||
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
|
||
|
|
]>
|
||
|
|
<refentry id="bwrap">
|
||
|
|
|
||
|
|
<refentryinfo>
|
||
|
|
<title>bwrap</title>
|
||
|
|
<productname>Project Atomic</productname>
|
||
|
|
<authorgroup>
|
||
|
|
<author>
|
||
|
|
<contrib>Developer</contrib>
|
||
|
|
<firstname>Alexander</firstname>
|
||
|
|
<surname>Larsson</surname>
|
||
|
|
</author>
|
||
|
|
<author>
|
||
|
|
<contrib>Developer</contrib>
|
||
|
|
<firstname>Colin</firstname>
|
||
|
|
<surname>Walters</surname>
|
||
|
|
</author>
|
||
|
|
</authorgroup>
|
||
|
|
</refentryinfo>
|
||
|
|
|
||
|
|
<refmeta>
|
||
|
|
<refentrytitle>bwrap</refentrytitle>
|
||
|
|
<manvolnum>1</manvolnum>
|
||
|
|
<refmiscinfo class="manual">User Commands</refmiscinfo>
|
||
|
|
</refmeta>
|
||
|
|
|
||
|
|
<refnamediv>
|
||
|
|
<refname>bwrap</refname>
|
||
|
|
<refpurpose>container setup utility</refpurpose>
|
||
|
|
</refnamediv>
|
||
|
|
|
||
|
|
<refsynopsisdiv>
|
||
|
|
<cmdsynopsis>
|
||
|
|
<command>bwrap</command>
|
||
|
|
<arg choice="opt" rep="repeat"><replaceable>OPTION</replaceable></arg>
|
||
|
|
<arg choice="opt"><replaceable>COMMAND</replaceable></arg>
|
||
|
|
</cmdsynopsis>
|
||
|
|
</refsynopsisdiv>
|
||
|
|
|
||
|
|
<refsect1><title>Description</title>
|
||
|
|
<para>
|
||
|
|
<command>bwrap</command> is a privileged helper for container setup. You
|
||
|
|
are unlikely to use it directly from the commandline, although that is possible.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
By default, <command>bwrap</command> 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.
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If needed (e.g. when using a PID namespace) <command>bwrap</command>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
<refsect1><title>Options</title>
|
||
|
|
<para>
|
||
|
|
When options are used multiple times, the last option wins, unless otherwise
|
||
|
|
specified.
|
||
|
|
</para>
|
||
|
|
<para>General options:</para>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--help</option></term>
|
||
|
|
<listitem><para>Print help and exit</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--version</option></term>
|
||
|
|
<listitem><para>Print version</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--args <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Parse nul-separated arguments from the given file descriptor.
|
||
|
|
This option can be used multiple times to parse options from
|
||
|
|
multiple sources.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
<para>Options related to kernel namespaces:</para>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-user</option></term>
|
||
|
|
<listitem><para>Create a new user namespace</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-user-try</option></term>
|
||
|
|
<listitem><para>Create a new user namespace if possible else skip it</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-ipc</option></term>
|
||
|
|
<listitem><para>Create a new ipc namespace</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-pid</option></term>
|
||
|
|
<listitem><para>Create a new pid namespace</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-net</option></term>
|
||
|
|
<listitem><para>Create a new network namespace</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-uts</option></term>
|
||
|
|
<listitem><para>Create a new uts namespace</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-cgroup</option></term>
|
||
|
|
<listitem><para>Create a new cgroup namespace</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-cgroup-try</option></term>
|
||
|
|
<listitem><para>Create a new cgroup namespace if possible else skip it</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unshare-all</option></term>
|
||
|
|
<listitem><para>Unshare all possible namespaces. Currently equivalent with: <option>--unshare-user-try</option> <option>--unshare-ipc</option> <option>--unshare-pid</option> <option>--unshare-net</option> <option>--unshare-uts</option> <option>--unshare-cgroup-try</option></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--userns <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>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. </para>
|
||
|
|
<para>This is incompatible with --unshare-user, and doesn't work in the setuid version of bubblewrap.</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--userns2 <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>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.</para>
|
||
|
|
<para>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.</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--pidns <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>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. </para>
|
||
|
|
<para>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.</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--uid <arg choice="plain">UID</arg></option></term>
|
||
|
|
<listitem><para>Use a custom user id in the sandbox (requires <option>--unshare-user</option>)</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--gid <arg choice="plain">GID</arg></option></term>
|
||
|
|
<listitem><para>Use a custom group id in the sandbox (requires <option>--unshare-user</option>)</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--hostname <arg choice="plain">HOSTNAME</arg></option></term>
|
||
|
|
<listitem><para>Use a custom hostname in the sandbox (requires <option>--unshare-uts</option>)</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
<para>Options about environment setup:</para>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--chdir <arg choice="plain">DIR</arg></option></term>
|
||
|
|
<listitem><para>Change directory to <arg choice="plain">DIR</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--setenv <arg choice="plain">VAR</arg> <arg choice="plain">VALUE</arg></option></term>
|
||
|
|
<listitem><para>Set an environment variable</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--unsetenv <arg choice="plain">VAR</arg></option></term>
|
||
|
|
<listitem><para>Unset an environment variable</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
<para>Options for monitoring the sandbox from the outside:</para>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--lock-file <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Take a lock on <arg choice="plain">DEST</arg> while the sandbox is running.
|
||
|
|
This option can be used multiple times to take locks on multiple files.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--sync-fd <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>Keep this file descriptor open while the sandbox is running</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
<para>
|
||
|
|
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.
|
||
|
|
</para>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--bind <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Bind mount the host path <arg choice="plain">SRC</arg> on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--bind-try <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Equal to <option>--bind</option> but ignores non-existent <arg choice="plain">SRC</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--dev-bind <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Bind mount the host path <arg choice="plain">SRC</arg> on <arg choice="plain">DEST</arg>, allowing device access</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--dev-bind-try <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Equal to <option>--dev-bind</option> but ignores non-existent <arg choice="plain">SRC</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--ro-bind <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Bind mount the host path <arg choice="plain">SRC</arg> readonly on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--ro-bind-try <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Equal to <option>--ro-bind</option> but ignores non-existent <arg choice="plain">SRC</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--remount-ro <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Remount the path <arg choice="plain">DEST</arg> as readonly. It works only on the specified mount point, without changing any other mount point under the specified path</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--proc <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Mount procfs on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--dev <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Mount new devtmpfs on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--tmpfs <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Mount new tmpfs on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--mqueue <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Mount new mqueue on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--dir <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Create a directory at <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--file <arg choice="plain">FD</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Copy from the file descriptor <arg choice="plain">FD</arg> to <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--bind-data <arg choice="plain">FD</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Copy from the file descriptor <arg choice="plain">FD</arg> to a file which is bind-mounted on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--ro-bind-data <arg choice="plain">FD</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Copy from the file descriptor <arg choice="plain">FD</arg> to a file which is bind-mounted readonly on <arg choice="plain">DEST</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--symlink <arg choice="plain">SRC</arg> <arg choice="plain">DEST</arg></option></term>
|
||
|
|
<listitem><para>Create a symlink at <arg choice="plain">DEST</arg> with target <arg choice="plain">SRC</arg></para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
<para>Lockdown options:</para>
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--seccomp <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Load and use seccomp rules from <arg choice="plain">FD</arg>.
|
||
|
|
The rules need to be in the form of a compiled eBPF program,
|
||
|
|
as generated by seccomp_export_bpf.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--exec-label <arg choice="plain">LABEL</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Exec Label from the sandbox. On an SELinux system you can specify the SELinux
|
||
|
|
context for the sandbox process(s).
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--file-label <arg choice="plain">LABEL</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
File label for temporary sandbox content. On an SELinux system you can specify
|
||
|
|
the SELinux context for the sandbox content.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--block-fd <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Block the sandbox on reading from FD until some data is available.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--userns-block-fd <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
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.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--info-fd <arg choice="plain">FD</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Write information in JSON format about the sandbox to FD.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--new-session</option></term>
|
||
|
|
<listitem><para>
|
||
|
|
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.
|
||
|
|
</para><para>
|
||
|
|
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.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--die-with-parent</option></term>
|
||
|
|
<listitem><para>
|
||
|
|
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.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--as-pid-1</option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Do not create a process with PID=1 in the sandbox to reap child processes.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--cap-add <arg choice="plain">CAP</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
Add the specified capability when running as privileged user. It accepts
|
||
|
|
the special value ALL to add all the permitted caps.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
<varlistentry>
|
||
|
|
<term><option>--cap-drop <arg choice="plain">CAP</arg></option></term>
|
||
|
|
<listitem><para>
|
||
|
|
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
|
||
|
|
<option>--cap-add</option> and <option>--cap-drop</option>
|
||
|
|
options are processed in the order they are specified on the
|
||
|
|
command line. Please be careful to the order they are specified.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
<refsect1>
|
||
|
|
<title>Environment</title>
|
||
|
|
|
||
|
|
<variablelist>
|
||
|
|
<varlistentry>
|
||
|
|
<term><envar>HOME</envar></term>
|
||
|
|
<listitem><para>
|
||
|
|
Used as the cwd in the sandbox if <option>--chdir</option> has not been
|
||
|
|
explicitly specified and the current cwd is not present inside the sandbox.
|
||
|
|
The <option>--setenv</option> option can be used to override the value
|
||
|
|
that is used here.
|
||
|
|
</para></listitem>
|
||
|
|
</varlistentry>
|
||
|
|
</variablelist>
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
<refsect1>
|
||
|
|
<title>Exit status</title>
|
||
|
|
|
||
|
|
<para>
|
||
|
|
The <command>bwrap</command> command returns the exit status of the
|
||
|
|
initial application process (pid 2 in the sandbox).
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
|
||
|
|
</refentry>
|