File: bwrap.xml

package info (click to toggle)
bubblewrap 0.3.3-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 848 kB
  • sloc: ansic: 3,090; sh: 2,258; xml: 353; perl: 100; makefile: 66; python: 28
file content (365 lines) | stat: -rw-r--r-- 16,279 bytes parent folder | download
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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
<?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>--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>