1BWRAP(1) User Commands BWRAP(1)
2
6 bwrap - container setup utility
7
9 bwrap [OPTION...] [COMMAND]
10
12 bwrap is a privileged helper for container setup. You are unlikely to
13 use it directly from the commandline, although that is possible.
14 It works by creating a new, completely empty, filesystem namespace
16 where the root is on a tmpfs that is invisible from the host, and which
17 will be automatically cleaned up when the last process exits. You can
18 then use commandline options to construct the root filesystem and
19 process environment for the command to run in the namespace.
20 By default, bwrap creates a new mount namespace for the sandbox.
22 Optionally it also sets up new user, ipc, pid, network and uts
23 namespaces (but note the user namespace is required if bwrap is not
24 installed setuid root). The application in the sandbox can be made to
25 run with a different UID and GID.
26 If needed (e.g. when using a PID namespace) bwrap is running a minimal
28 pid 1 process in the sandbox that is responsible for reaping zombies.
29 It also detects when the initial application process (pid 2) dies and
30 reports its exit status back to the original spawner. The pid 1 process
31 exits to clean up the sandbox when there are no other processes in the
32 sandbox left.
33
35 When options are used multiple times, the last option wins, unless
36 otherwise specified.
37 General options:
39 --help
41 Print help and exit
42 --version
44 Print version
45 --args FD
47 Parse nul-separated arguments from the given file descriptor. This
48 option can be used multiple times to parse options from multiple
49 sources.
50 Options related to kernel namespaces:
52 --unshare-user
54 Create a new user namespace
55 --unshare-user-try
57 Create a new user namespace if possible else skip it
58 --unshare-ipc
60 Create a new ipc namespace
61 --unshare-pid
63 Create a new pid namespace
64 --unshare-net
66 Create a new network namespace
67 --unshare-uts
69 Create a new uts namespace
70 --unshare-cgroup
72 Create a new cgroup namespace
73 --unshare-cgroup-try
75 Create a new cgroup namespace if possible else skip it
76 --unshare-all
78 Unshare all possible namespaces. Currently equivalent with:
79 --unshare-user-try --unshare-ipc --unshare-pid --unshare-net
80 --unshare-uts --unshare-cgroup-try
81 --share-net
83 Retain the network namespace, overriding an earlier --unshare-all
84 or --unshare-net
85 --userns FD
87 Use an existing user namespace instead of creating a new one. The
88 namespace must fulfil the permission requirements for setns(),
89 which generally means that it must be a descendant of the currently
90 active user namespace, owned by the same user.
91 This is incompatible with --unshare-user, and doesn't work in the
93 setuid version of bubblewrap.
94 --userns2 FD
96 After setting up the new namespace, switch into the specified
97 namespace. For this to work the specified namespace must be a
98 descendant of the user namespace used for the setup, so this is
99 only useful in combination with --userns.
100 This is useful because sometimes bubblewrap itself creates nested
102 user namespaces (to work around some kernel issues) and --userns2
103 can be used to enter these.
104 --disable-userns
106 Prevent the process in the sandbox from creating further user
107 namespaces, so that it cannot rearrange the filesystem namespace or
108 do other more complex namespace modification. This is currently
109 implemented by setting the user.max_user_namespaces sysctl to 1,
110 and then entering a nested user namespace which is unable to raise
111 that limit in the outer namespace. This option requires
112 --unshare-user, and doesn't work in the setuid version of
113 bubblewrap.
114 --assert-userns-disabled
116 Confirm that the process in the sandbox has been prevented from
117 creating further user namespaces, but without taking any particular
118 action to prevent that. For example, this can be combined with
119 --userns to check that the given user namespace has already been
120 set up to prevent the creation of further user namespaces.
121 --pidns FD
123 Use an existing pid namespace instead of creating one. This is
124 often used with --userns, because the pid namespace must be owned
125 by the same user namespace that bwrap uses.
126 Note that this can be combined with --unshare-pid, and in that case
128 it means that the sandbox will be in its own pid namespace, which
129 is a child of the passed in one.
130 --uid UID
132 Use a custom user id in the sandbox (requires --unshare-user)
133 --gid GID
135 Use a custom group id in the sandbox (requires --unshare-user)
136 --hostname HOSTNAME
138 Use a custom hostname in the sandbox (requires --unshare-uts)
139 Options about environment setup:
141 --chdir DIR
143 Change directory to DIR
144 --setenv VAR VALUE
146 Set an environment variable
147 --unsetenv VAR
149 Unset an environment variable
150 --clearenv
152 Unset all environment variables, except for PWD and any that are
153 subsequently set by --setenv
154 Options for monitoring the sandbox from the outside:
156 --lock-file DEST
158 Take a lock on DEST while the sandbox is running. This option can
159 be used multiple times to take locks on multiple files.
160 --sync-fd FD
162 Keep this file descriptor open while the sandbox is running
163 Filesystem related options. These are all operations that modify the
165 filesystem directly, or mounts stuff in the filesystem. These are
166 applied in the order they are given as arguments.
167 Any missing parent directories that are required to create a specified
169 destination are automatically created as needed. Their permissions are
170 normally set to 0755 (rwxr-xr-x). However, if a --perms option is in
171 effect, and it sets the permissions for group or other to zero, then
172 newly-created parent directories will also have their corresponding
173 permission set to zero. --size modifies the size of the created mount
174 when preceding a --tmpfs action; --perms and --size can be combined.
175 --perms OCTAL
177 This option does nothing on its own, and must be followed by one of
178 the options that it affects. It sets the permissions for the next
179 operation to OCTAL. Subsequent operations are not affected: for
180 example, --perms 0700 --tmpfs /a --tmpfs /b will mount /a with
181 permissions 0700, then return to the default permissions for /b.
182 Note that --perms and --size can be combined: --perms 0700 --size
183 10485760 --tmpfs /s will apply permissions as well as a maximum
184 size to the created tmpfs.
185 --size BYTES
187 This option does nothing on its own, and must be followed by
188 --tmpfs. It sets the size in bytes for the next tmpfs. For example,
189 --size 10485760 --tmpfs /tmp will create a tmpfs at /tmp of size
190 10MiB. Subsequent operations are not affected: for example, --size
191 10485760 --tmpfs /a --tmpfs /b will mount /a with size 10MiB, then
192 return to the default size for /b. Note that --perms and --size can
193 be combined: --size 10485760 --perms 0700 --tmpfs /s will apply
194 permissions as well as a maximum size to the created tmpfs.
195 --bind SRC DEST
197 Bind mount the host path SRC on DEST
198 --bind-try SRC DEST
200 Equal to --bind but ignores non-existent SRC
201 --dev-bind SRC DEST
203 Bind mount the host path SRC on DEST, allowing device access
204 --dev-bind-try SRC DEST
206 Equal to --dev-bind but ignores non-existent SRC
207 --ro-bind SRC DEST
209 Bind mount the host path SRC readonly on DEST
210 --ro-bind-try SRC DEST
212 Equal to --ro-bind but ignores non-existent SRC
213 --remount-ro DEST
215 Remount the path DEST as readonly. It works only on the specified
216 mount point, without changing any other mount point under the
217 specified path
218 --proc DEST
220 Mount procfs on DEST
221 --dev DEST
223 Mount new devtmpfs on DEST
224 --tmpfs DEST
226 Mount new tmpfs on DEST. If the previous option was --perms, it
227 sets the mode of the tmpfs. Otherwise, the tmpfs has mode 0755. If
228 the previous option was --size, it sets the size in bytes of the
229 tmpfs. Otherwise, the tmpfs has the default size.
230 --mqueue DEST
232 Mount new mqueue on DEST
233 --dir DEST
235 Create a directory at DEST. If the directory already exists, its
236 permissions are unmodified, ignoring --perms (use --chmod if the
237 permissions of an existing directory need to be changed). If the
238 directory is newly created and the previous option was --perms, it
239 sets the mode of the directory. Otherwise, newly-created
240 directories have mode 0755.
241 --file FD DEST
243 Copy from the file descriptor FD to DEST. If the previous option
244 was --perms, it sets the mode of the new file. Otherwise, the file
245 has mode 0666 (note that this is not the same as --bind-data).
246 --bind-data FD DEST
248 Copy from the file descriptor FD to a file which is bind-mounted on
249 DEST. If the previous option was --perms, it sets the mode of the
250 new file. Otherwise, the file has mode 0600 (note that this is not
251 the same as --file).
252 --ro-bind-data FD DEST
254 Copy from the file descriptor FD to a file which is bind-mounted
255 read-only on DEST. If the previous option was --perms, it sets the
256 mode of the new file. Otherwise, the file has mode 0600 (note that
257 this is not the same as --file).
258 --symlink SRC DEST
260 Create a symlink at DEST with target SRC
261 --chmod OCTAL PATH
263 Set the permissions of PATH, which must already exist, to OCTAL.
264 Lockdown options:
266 --seccomp FD
268 Load and use seccomp rules from FD. The rules need to be in the
269 form of a compiled cBPF program, as generated by
270 seccomp_export_bpf. If this option is given more than once, only
271 the last one is used. Use --add-seccomp-fd if multiple seccomp
272 programs are needed.
273 --add-seccomp-fd FD
275 Load and use seccomp rules from FD. The rules need to be in the
276 form of a compiled cBPF program, as generated by
277 seccomp_export_bpf. This option can be repeated, in which case all
278 the seccomp programs will be loaded in the order given (note that
279 the kernel will evaluate them in reverse order, so the last program
280 on the bwrap command-line is evaluated first). All of them, except
281 possibly the last, must allow use of the PR_SET_SECCOMP prctl. This
282 option cannot be combined with --seccomp.
283 --exec-label LABEL
285 Exec Label from the sandbox. On an SELinux system you can specify
286 the SELinux context for the sandbox process(s).
287 --file-label LABEL
289 File label for temporary sandbox content. On an SELinux system you
290 can specify the SELinux context for the sandbox content.
291 --block-fd FD
293 Block the sandbox on reading from FD until some data is available.
294 --userns-block-fd FD
296 Do not initialize the user namespace but wait on FD until it is
297 ready. This allow external processes (like newuidmap/newgidmap) to
298 setup the user namespace before it is used by the sandbox process.
299 --info-fd FD
301 Write information in JSON format about the sandbox to FD.
302 --json-status-fd FD
304 Multiple JSON documents are written to FD, one per line ("JSON
305 lines" format[1]). Each line is a single JSON object. After bwrap
306 has started the child process inside the sandbox, it writes an
307 object with a child-pid member to the --json-status-fd (this
308 duplicates the older --info-fd). The corresponding value is the
309 process ID of the child process in the pid namespace from which
310 bwrap was run. If available, the namespace IDs are also included in
311 the object with the child-pid; again, this duplicates the older
312 --info-fd. When the child process inside the sandbox exits, bwrap
313 writes an object with an exit-code member, and then closes the
314 --json-status-fd. The value corresponding to exit-code is the exit
315 status of the child, in the usual shell encoding (n if it exited
316 normally with status n, or 128+n if it was killed by signal n).
317 Other members may be added to those objects in future versions of
318 bwrap, and other JSON objects may be added before or after the
319 current objects, so readers must ignore members and objects that
320 they do not understand.
321 --new-session
323 Create a new terminal session for the sandbox (calls setsid()).
324 This disconnects the sandbox from the controlling terminal which
325 means the sandbox can't for instance inject input into the
326 terminal.
327 Note: In a general sandbox, if you don't use --new-session, it is
329 recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise
330 the application can feed keyboard input to the terminal.
331 --die-with-parent
333 Ensures child process (COMMAND) dies when bwrap's parent dies.
334 Kills (SIGKILL) all bwrap sandbox processes in sequence from parent
335 to child including COMMAND process when bwrap or bwrap's parent
336 dies. See prctl, PR_SET_PDEATHSIG.
337 --as-pid-1
339 Do not create a process with PID=1 in the sandbox to reap child
340 processes.
341 --cap-add CAP
343 Add the specified capability when running as privileged user. It
344 accepts the special value ALL to add all the permitted caps.
345 --cap-drop CAP
347 Drop the specified capability when running as privileged user. It
348 accepts the special value ALL to drop all the caps. By default no
349 caps are left in the sandboxed process. The --cap-add and
350 --cap-drop options are processed in the order they are specified on
351 the command line. Please be careful to the order they are
352 specified.
353
355 HOME
356 Used as the cwd in the sandbox if --chdir has not been explicitly
357 specified and the current cwd is not present inside the sandbox.
358 The --setenv option can be used to override the value that is used
359 here.
360
362 The bwrap command returns the exit status of the initial application
363 process (pid 2 in the sandbox).
364
366 1. "JSON lines" format
367 https://jsonlines.org/
368Project Atomic BWRAP(1)