1 '\" t
2 .\" Title: bwrap
3 .\" Author: Alexander Larsson
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 09/22/2019
6 .\" Manual: User Commands
7 .\" Source: Project Atomic
8 .\" Language: English
9 .\"
10 .TH "BWRAP" "1" "" "Project Atomic" "User Commands"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30
31
32
33
34
35 .SH "NAME"
36 bwrap \- container setup utility
37
38 .SH "SYNOPSIS"
39 .HP \w'\fBbwrap\fR\ 'u
40
41 \fBbwrap\fR
42 [\fIOPTION\fR...]
43 [\fICOMMAND\fR]
44
45
46
47 .SH "DESCRIPTION"
48 .PP
49 \fBbwrap\fR
50 is a privileged helper for container setup\&. You are unlikely to use it directly from the commandline, although that is possible\&.
51 .PP
52 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\&.
53 .PP
54 By default,
55 \fBbwrap\fR
56 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\&.
57 .PP
58 If needed (e\&.g\&. when using a PID namespace)
59 \fBbwrap\fR
60 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\&.
61
62
63 .SH "OPTIONS"
64
65 .PP
66 When options are used multiple times, the last option wins, unless otherwise specified\&.
67
68 .PP
69 General options:
70
71
72
73 .PP
74 \fB\-\-help\fR
75 .RS 4
76
77
78 Print help and exit
79
80 .RE
81 .PP
82 \fB\-\-version\fR
83 .RS 4
84
85
86 Print version
87
88 .RE
89 .PP
90 \fB\-\-args \fR\fBFD\fR
91 .RS 4
92
93
94 Parse nul\-separated arguments from the given file descriptor\&. This option can be used multiple times to parse options from multiple sources\&.
95
96 .RE
97
98 .PP
99 Options related to kernel namespaces:
100
101
102
103 .PP
104 \fB\-\-unshare\-user\fR
105 .RS 4
106
107
108 Create a new user namespace
109
110 .RE
111 .PP
112 \fB\-\-unshare\-user\-try\fR
113 .RS 4
114
115
116 Create a new user namespace if possible else skip it
117
118 .RE
119 .PP
120 \fB\-\-unshare\-ipc\fR
121 .RS 4
122
123
124 Create a new ipc namespace
125
126 .RE
127 .PP
128 \fB\-\-unshare\-pid\fR
129 .RS 4
130
131
132 Create a new pid namespace
133
134 .RE
135 .PP
136 \fB\-\-unshare\-net\fR
137 .RS 4
138
139
140 Create a new network namespace
141
142 .RE
143 .PP
144 \fB\-\-unshare\-uts\fR
145 .RS 4
146
147
148 Create a new uts namespace
149
150 .RE
151 .PP
152 \fB\-\-unshare\-cgroup\fR
153 .RS 4
154
155
156 Create a new cgroup namespace
157
158 .RE
159 .PP
160 \fB\-\-unshare\-cgroup\-try\fR
161 .RS 4
162
163
164 Create a new cgroup namespace if possible else skip it
165
166 .RE
167 .PP
168 \fB\-\-unshare\-all\fR
169 .RS 4
170
171
172 Unshare all possible namespaces\&. Currently equivalent with:
173 \fB\-\-unshare\-user\-try\fR
174 \fB\-\-unshare\-ipc\fR
175 \fB\-\-unshare\-pid\fR
176 \fB\-\-unshare\-net\fR
177 \fB\-\-unshare\-uts\fR
178 \fB\-\-unshare\-cgroup\-try\fR
179
180 .RE
181 .PP
182 \fB\-\-uid \fR\fBUID\fR
183 .RS 4
184
185
186 Use a custom user id in the sandbox (requires
187 \fB\-\-unshare\-user\fR)
188
189 .RE
190 .PP
191 \fB\-\-gid \fR\fBGID\fR
192 .RS 4
193
194
195 Use a custom group id in the sandbox (requires
196 \fB\-\-unshare\-user\fR)
197
198 .RE
199 .PP
200 \fB\-\-hostname \fR\fBHOSTNAME\fR
201 .RS 4
202
203
204 Use a custom hostname in the sandbox (requires
205 \fB\-\-unshare\-uts\fR)
206
207 .RE
208
209 .PP
210 Options about environment setup:
211
212
213
214 .PP
215 \fB\-\-chdir \fR\fBDIR\fR
216 .RS 4
217
218
219 Change directory to
220 DIR
221
222 .RE
223 .PP
224 \fB\-\-setenv \fR\fBVAR\fR\fB \fR\fBVALUE\fR
225 .RS 4
226
227
228 Set an environment variable
229
230 .RE
231 .PP
232 \fB\-\-unsetenv \fR\fBVAR\fR
233 .RS 4
234
235
236 Unset an environment variable
237
238 .RE
239
240 .PP
241 Options for monitoring the sandbox from the outside:
242
243
244
245 .PP
246 \fB\-\-lock\-file \fR\fBDEST\fR
247 .RS 4
248
249
250 Take a lock on
251 DEST
252 while the sandbox is running\&. This option can be used multiple times to take locks on multiple files\&.
253
254 .RE
255 .PP
256 \fB\-\-sync\-fd \fR\fBFD\fR
257 .RS 4
258
259
260 Keep this file descriptor open while the sandbox is running
261
262 .RE
263
264 .PP
265 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\&.
266
267
268
269 .PP
270 \fB\-\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
271 .RS 4
272
273
274 Bind mount the host path
275 SRC
276 on
277 DEST
278
279 .RE
280 .PP
281 \fB\-\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
282 .RS 4
283
284
285 Equal to
286 \fB\-\-bind\fR
287 but ignores non\-existent
288 SRC
289
290 .RE
291 .PP
292 \fB\-\-dev\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
293 .RS 4
294
295
296 Bind mount the host path
297 SRC
298 on
299 DEST, allowing device access
300
301 .RE
302 .PP
303 \fB\-\-dev\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
304 .RS 4
305
306
307 Equal to
308 \fB\-\-dev\-bind\fR
309 but ignores non\-existent
310 SRC
311
312 .RE
313 .PP
314 \fB\-\-ro\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
315 .RS 4
316
317
318 Bind mount the host path
319 SRC
320 readonly on
321 DEST
322
323 .RE
324 .PP
325 \fB\-\-ro\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
326 .RS 4
327
328
329 Equal to
330 \fB\-\-ro\-bind\fR
331 but ignores non\-existent
332 SRC
333
334 .RE
335 .PP
336 \fB\-\-remount\-ro \fR\fBDEST\fR
337 .RS 4
338
339
340 Remount the path
341 DEST
342 as readonly\&. It works only on the specified mount point, without changing any other mount point under the specified path
343
344 .RE
345 .PP
346 \fB\-\-proc \fR\fBDEST\fR
347 .RS 4
348
349
350 Mount procfs on
351 DEST
352
353 .RE
354 .PP
355 \fB\-\-dev \fR\fBDEST\fR
356 .RS 4
357
358
359 Mount new devtmpfs on
360 DEST
361
362 .RE
363 .PP
364 \fB\-\-tmpfs \fR\fBDEST\fR
365 .RS 4
366
367
368 Mount new tmpfs on
369 DEST
370
371 .RE
372 .PP
373 \fB\-\-mqueue \fR\fBDEST\fR
374 .RS 4
375
376
377 Mount new mqueue on
378 DEST
379
380 .RE
381 .PP
382 \fB\-\-dir \fR\fBDEST\fR
383 .RS 4
384
385
386 Create a directory at
387 DEST
388
389 .RE
390 .PP
391 \fB\-\-file \fR\fBFD\fR\fB \fR\fBDEST\fR
392 .RS 4
393
394
395 Copy from the file descriptor
396 FD
397 to
398 DEST
399
400 .RE
401 .PP
402 \fB\-\-bind\-data \fR\fBFD\fR\fB \fR\fBDEST\fR
403 .RS 4
404
405
406 Copy from the file descriptor
407 FD
408 to a file which is bind\-mounted on
409 DEST
410
411 .RE
412 .PP
413 \fB\-\-ro\-bind\-data \fR\fBFD\fR\fB \fR\fBDEST\fR
414 .RS 4
415
416
417 Copy from the file descriptor
418 FD
419 to a file which is bind\-mounted readonly on
420 DEST
421
422 .RE
423 .PP
424 \fB\-\-symlink \fR\fBSRC\fR\fB \fR\fBDEST\fR
425 .RS 4
426
427
428 Create a symlink at
429 DEST
430 with target
431 SRC
432
433 .RE
434
435 .PP
436 Lockdown options:
437
438
439
440 .PP
441 \fB\-\-seccomp \fR\fBFD\fR
442 .RS 4
443
444
445 Load and use seccomp rules from
446 FD\&. The rules need to be in the form of a compiled eBPF program, as generated by seccomp_export_bpf\&.
447
448 .RE
449 .PP
450 \fB\-\-exec\-label \fR\fBLABEL\fR
451 .RS 4
452
453
454 Exec Label from the sandbox\&. On an SELinux system you can specify the SELinux context for the sandbox process(s)\&.
455
456 .RE
457 .PP
458 \fB\-\-file\-label \fR\fBLABEL\fR
459 .RS 4
460
461
462 File label for temporary sandbox content\&. On an SELinux system you can specify the SELinux context for the sandbox content\&.
463
464 .RE
465 .PP
466 \fB\-\-block\-fd \fR\fBFD\fR
467 .RS 4
468
469
470 Block the sandbox on reading from FD until some data is available\&.
471
472 .RE
473 .PP
474 \fB\-\-userns\-block\-fd \fR\fBFD\fR
475 .RS 4
476
477
478 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\&.
479
480 .RE
481 .PP
482 \fB\-\-info\-fd \fR\fBFD\fR
483 .RS 4
484
485
486 Write information in JSON format about the sandbox to FD\&.
487
488 .RE
489 .PP
490 \fB\-\-new\-session\fR
491 .RS 4
492
493
494 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\&.
495 .sp
496 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\&.
497
498 .RE
499 .PP
500 \fB\-\-die\-with\-parent\fR
501 .RS 4
502
503
504 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\&.
505
506 .RE
507 .PP
508 \fB\-\-as\-pid\-1\fR
509 .RS 4
510
511
512 Do not create a process with PID=1 in the sandbox to reap child processes\&.
513
514 .RE
515 .PP
516 \fB\-\-cap\-add \fR\fBCAP\fR
517 .RS 4
518
519
520 Add the specified capability when running as privileged user\&. It accepts the special value ALL to add all the permitted caps\&.
521
522 .RE
523 .PP
524 \fB\-\-cap\-drop \fR\fBCAP\fR
525 .RS 4
526
527
528 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
529 \fB\-\-cap\-add\fR
530 and
531 \fB\-\-cap\-drop\fR
532 options are processed in the order they are specified on the command line\&. Please be careful to the order they are specified\&.
533
534 .RE
535
536
537 .SH "ENVIRONMENT"
538
539
540
541
542
543 .PP
544 \fBHOME\fR
545 .RS 4
546
547
548 Used as the cwd in the sandbox if
549 \fB\-\-chdir\fR
550 has not been explicitly specified and the current cwd is not present inside the sandbox\&. The
551 \fB\-\-setenv\fR
552 option can be used to override the value that is used here\&.
553
554 .RE
555
556
557 .SH "EXIT STATUS"
558
559
560
561 .PP
562 The
563 \fBbwrap\fR
564 command returns the exit status of the initial application process (pid 2 in the sandbox)\&.
|
