blob: 543a24a3fa84629a8cff6129554e436368edbc53 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<?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> 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.
</para>
<para>
By default, <command>bwrap</command> creates a new user namespace for the sandbox.
Optionally it also sets up new ipc, pid, network and uts namespaces. The application
in the sandbox can be made to run with a different UID and GID.
</para>
<para>
<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>--share-user</option></term>
<listitem><para>Don't create a new user namespace</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>--uid <arg choice="plain">UID</arg></option></term>
<listitem><para>Use a custom user id in the sandbox (incompatible with <option>--share-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 (incompatible with <option>--share-user</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. Note that it is possible to refer to the same
destination or mount point multiple times. In such cases, the last option wins.
</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>--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>--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>--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>--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>--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>
</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>
|
