1 '\" t
2 .\" Title: bwrap
3 .\" Author: Alexander Larsson
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 04/25/2020
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\-\-userns \fR\fBFD\fR
183 .RS 4
184
185
186 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\&.
187 .sp
188
189 This is incompatible with \-\-unshare\-user, and doesn\*(Aqt work in the setuid version of bubblewrap\&.
190
191 .RE
192 .PP
193 \fB\-\-userns2 \fR\fBFD\fR
194 .RS 4
195
196
197 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\&.
198 .sp
199
200 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\&.
201
202 .RE
203 .PP
204 \fB\-\-pidns \fR\fBFD\fR
205 .RS 4
206
207
208 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\&.
209 .sp
210
211 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\&.
212
213 .RE
214 .PP
215 \fB\-\-uid \fR\fBUID\fR
216 .RS 4
217
218
219 Use a custom user id in the sandbox (requires
220 \fB\-\-unshare\-user\fR)
221
222 .RE
223 .PP
224 \fB\-\-gid \fR\fBGID\fR
225 .RS 4
226
227
228 Use a custom group id in the sandbox (requires
229 \fB\-\-unshare\-user\fR)
230
231 .RE
232 .PP
233 \fB\-\-hostname \fR\fBHOSTNAME\fR
234 .RS 4
235
236
237 Use a custom hostname in the sandbox (requires
238 \fB\-\-unshare\-uts\fR)
239
240 .RE
241
242 .PP
243 Options about environment setup:
244
245
246
247 .PP
248 \fB\-\-chdir \fR\fBDIR\fR
249 .RS 4
250
251
252 Change directory to
253 DIR
254
255 .RE
256 .PP
257 \fB\-\-setenv \fR\fBVAR\fR\fB \fR\fBVALUE\fR
258 .RS 4
259
260
261 Set an environment variable
262
263 .RE
264 .PP
265 \fB\-\-unsetenv \fR\fBVAR\fR
266 .RS 4
267
268
269 Unset an environment variable
270
271 .RE
272
273 .PP
274 Options for monitoring the sandbox from the outside:
275
276
277
278 .PP
279 \fB\-\-lock\-file \fR\fBDEST\fR
280 .RS 4
281
282
283 Take a lock on
284 DEST
285 while the sandbox is running\&. This option can be used multiple times to take locks on multiple files\&.
286
287 .RE
288 .PP
289 \fB\-\-sync\-fd \fR\fBFD\fR
290 .RS 4
291
292
293 Keep this file descriptor open while the sandbox is running
294
295 .RE
296
297 .PP
298 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\&.
299
300
301
302 .PP
303 \fB\-\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
304 .RS 4
305
306
307 Bind mount the host path
308 SRC
309 on
310 DEST
311
312 .RE
313 .PP
314 \fB\-\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
315 .RS 4
316
317
318 Equal to
319 \fB\-\-bind\fR
320 but ignores non\-existent
321 SRC
322
323 .RE
324 .PP
325 \fB\-\-dev\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
326 .RS 4
327
328
329 Bind mount the host path
330 SRC
331 on
332 DEST, allowing device access
333
334 .RE
335 .PP
336 \fB\-\-dev\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
337 .RS 4
338
339
340 Equal to
341 \fB\-\-dev\-bind\fR
342 but ignores non\-existent
343 SRC
344
345 .RE
346 .PP
347 \fB\-\-ro\-bind \fR\fBSRC\fR\fB \fR\fBDEST\fR
348 .RS 4
349
350
351 Bind mount the host path
352 SRC
353 readonly on
354 DEST
355
356 .RE
357 .PP
358 \fB\-\-ro\-bind\-try \fR\fBSRC\fR\fB \fR\fBDEST\fR
359 .RS 4
360
361
362 Equal to
363 \fB\-\-ro\-bind\fR
364 but ignores non\-existent
365 SRC
366
367 .RE
368 .PP
369 \fB\-\-remount\-ro \fR\fBDEST\fR
370 .RS 4
371
372
373 Remount the path
374 DEST
375 as readonly\&. It works only on the specified mount point, without changing any other mount point under the specified path
376
377 .RE
378 .PP
379 \fB\-\-proc \fR\fBDEST\fR
380 .RS 4
381
382
383 Mount procfs on
384 DEST
385
386 .RE
387 .PP
388 \fB\-\-dev \fR\fBDEST\fR
389 .RS 4
390
391
392 Mount new devtmpfs on
393 DEST
394
395 .RE
396 .PP
397 \fB\-\-tmpfs \fR\fBDEST\fR
398 .RS 4
399
400
401 Mount new tmpfs on
402 DEST
403
404 .RE
405 .PP
406 \fB\-\-mqueue \fR\fBDEST\fR
407 .RS 4
408
409
410 Mount new mqueue on
411 DEST
412
413 .RE
414 .PP
415 \fB\-\-dir \fR\fBDEST\fR
416 .RS 4
417
418
419 Create a directory at
420 DEST
421
422 .RE
423 .PP
424 \fB\-\-file \fR\fBFD\fR\fB \fR\fBDEST\fR
425 .RS 4
426
427
428 Copy from the file descriptor
429 FD
430 to
431 DEST
432
433 .RE
434 .PP
435 \fB\-\-bind\-data \fR\fBFD\fR\fB \fR\fBDEST\fR
436 .RS 4
437
438
439 Copy from the file descriptor
440 FD
441 to a file which is bind\-mounted on
442 DEST
443
444 .RE
445 .PP
446 \fB\-\-ro\-bind\-data \fR\fBFD\fR\fB \fR\fBDEST\fR
447 .RS 4
448
449
450 Copy from the file descriptor
451 FD
452 to a file which is bind\-mounted readonly on
453 DEST
454
455 .RE
456 .PP
457 \fB\-\-symlink \fR\fBSRC\fR\fB \fR\fBDEST\fR
458 .RS 4
459
460
461 Create a symlink at
462 DEST
463 with target
464 SRC
465
466 .RE
467
468 .PP
469 Lockdown options:
470
471
472
473 .PP
474 \fB\-\-seccomp \fR\fBFD\fR
475 .RS 4
476
477
478 Load and use seccomp rules from
479 FD\&. The rules need to be in the form of a compiled eBPF program, as generated by seccomp_export_bpf\&.
480
481 .RE
482 .PP
483 \fB\-\-exec\-label \fR\fBLABEL\fR
484 .RS 4
485
486
487 Exec Label from the sandbox\&. On an SELinux system you can specify the SELinux context for the sandbox process(s)\&.
488
489 .RE
490 .PP
491 \fB\-\-file\-label \fR\fBLABEL\fR
492 .RS 4
493
494
495 File label for temporary sandbox content\&. On an SELinux system you can specify the SELinux context for the sandbox content\&.
496
497 .RE
498 .PP
499 \fB\-\-block\-fd \fR\fBFD\fR
500 .RS 4
501
502
503 Block the sandbox on reading from FD until some data is available\&.
504
505 .RE
506 .PP
507 \fB\-\-userns\-block\-fd \fR\fBFD\fR
508 .RS 4
509
510
511 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\&.
512
513 .RE
514 .PP
515 \fB\-\-info\-fd \fR\fBFD\fR
516 .RS 4
517
518
519 Write information in JSON format about the sandbox to FD\&.
520
521 .RE
522 .PP
523 \fB\-\-new\-session\fR
524 .RS 4
525
526
527 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\&.
528 .sp
529 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\&.
530
531 .RE
532 .PP
533 \fB\-\-die\-with\-parent\fR
534 .RS 4
535
536
537 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\&.
538
539 .RE
540 .PP
541 \fB\-\-as\-pid\-1\fR
542 .RS 4
543
544
545 Do not create a process with PID=1 in the sandbox to reap child processes\&.
546
547 .RE
548 .PP
549 \fB\-\-cap\-add \fR\fBCAP\fR
550 .RS 4
551
552
553 Add the specified capability when running as privileged user\&. It accepts the special value ALL to add all the permitted caps\&.
554
555 .RE
556 .PP
557 \fB\-\-cap\-drop \fR\fBCAP\fR
558 .RS 4
559
560
561 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
562 \fB\-\-cap\-add\fR
563 and
564 \fB\-\-cap\-drop\fR
565 options are processed in the order they are specified on the command line\&. Please be careful to the order they are specified\&.
566
567 .RE
568
569
570 .SH "ENVIRONMENT"
571
572
573
574
575
576 .PP
577 \fBHOME\fR
578 .RS 4
579
580
581 Used as the cwd in the sandbox if
582 \fB\-\-chdir\fR
583 has not been explicitly specified and the current cwd is not present inside the sandbox\&. The
584 \fB\-\-setenv\fR
585 option can be used to override the value that is used here\&.
586
587 .RE
588
589
590 .SH "EXIT STATUS"
591
592
593
594 .PP
595 The
596 \fBbwrap\fR
597 command returns the exit status of the initial application process (pid 2 in the sandbox)\&.
|
