mirror of
https://github.com/projectatomic/bubblewrap.git
synced 2026-02-06 00:45:49 +01:00
75c2d94de8
This allows you to reuse an existing user namespace to set up all the other namespaces, entering that instead of creating a new one. The reason you want to do this is that you can then also reuse other namespaces that are owned by the user namespace. Typically you use this to partially re-enter a previoulsy created bubblewrap sandbox. This also adds --userns2 which is similar to --userns, but this is switched into at the end instead of the start. Bubblewrap sometimes creates nested such user namespaces[1], and to be able to reuse such a setup we need to similarly reuse both namespaces via --userns2. Technically using setns() is probably safe even in the privileged case, because we got passed in a file descriptor to the namespace, and that can only be gotten if you have ptrace permissions against the target, and then you could do whatever to the namespace anyway. However, for practical reasons this isn't useable for bwrap, because (as described in a comment in acquire_privs()) setuid mode causes root to own the namespaces that it creates. So as you will not be able to access these namespaces for reuse anyway, its best to disable it (in case of unexpected security issues). [1] This is to work around an issue with mounting devpts without uid 0 mapped in the user namespace, where the outer namespace owns all the other namespaces but the inner one has the right mappings.
376 lines
17 KiB
XML
376 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>--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>
|