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 --pidns FD
106 Use an existing pid namespace instead of creating one. This is
107 often used with --userns, because the pid namespace must be owned
108 by the same user namespace that bwrap uses.
109 Note that this can be combined with --unshare-pid, and in that case
111 it means that the sandbox will be in its own pid namespace, which
112 is a child of the passed in one.
113 --uid UID
115 Use a custom user id in the sandbox (requires --unshare-user)
116 --gid GID
118 Use a custom group id in the sandbox (requires --unshare-user)
119 --hostname HOSTNAME
121 Use a custom hostname in the sandbox (requires --unshare-uts)
122 Options about environment setup:
124 --chdir DIR
126 Change directory to DIR
127 --setenv VAR VALUE
129 Set an environment variable
130 --unsetenv VAR
132 Unset an environment variable
133 --clearenv
135 Unset all environment variables, except for PWD and any that are
136 subsequently set by --setenv
137 Options for monitoring the sandbox from the outside:
139 --lock-file DEST
141 Take a lock on DEST while the sandbox is running. This option can
142 be used multiple times to take locks on multiple files.
143 --sync-fd FD
145 Keep this file descriptor open while the sandbox is running
146 Filesystem related options. These are all operations that modify the
148 filesystem directly, or mounts stuff in the filesystem. These are
149 applied in the order they are given as arguments.
150 Any missing parent directories that are required to create a specified
152 destination are automatically created as needed. Their permissions are
153 normally set to 0755 (rwxr-xr-x). However, if a --perms option is in
154 effect, and it sets the permissions for group or other to zero, then
155 newly-created parent directories will also have their corresponding
156 permission set to zero. --size modifies the size of the created mount
157 when preceding a --tmpfs action; --perms and --size can be combined.
158 --perms OCTAL
160 This option does nothing on its own, and must be followed by one of
161 the options that it affects. It sets the permissions for the next
162 operation to OCTAL. Subsequent operations are not affected: for
163 example, --perms 0700 --tmpfs /a --tmpfs /b will mount /a with
164 permissions 0700, then return to the default permissions for /b.
165 Note that --perms and --size can be combined: --perms 0700 --size
166 10485760 --tmpfs /s will apply permissions as well as a maximum
167 size to the created tmpfs.
168 --size BYTES
170 This option does nothing on its own, and must be followed by
171 --tmpfs. It sets the size in bytes for the next tmpfs. For example,
172 --size 10485760 --tmpfs /tmp will create a tmpfs at /tmp of size
173 10MiB. Subsequent operations are not affected: for example, --size
174 10485760 --tmpfs /a --tmpfs /b will mount /a with size 10MiB, then
175 return to the default size for /b. Note that --perms and --size can
176 be combined: --size 10485760 --perms 0700 --tmpfs /s will apply
177 permissions as well as a maximum size to the created tmpfs.
178 --bind SRC DEST
180 Bind mount the host path SRC on DEST
181 --bind-try SRC DEST
183 Equal to --bind but ignores non-existent SRC
184 --dev-bind SRC DEST
186 Bind mount the host path SRC on DEST, allowing device access
187 --dev-bind-try SRC DEST
189 Equal to --dev-bind but ignores non-existent SRC
190 --ro-bind SRC DEST
192 Bind mount the host path SRC readonly on DEST
193 --ro-bind-try SRC DEST
195 Equal to --ro-bind but ignores non-existent SRC
196 --remount-ro DEST
198 Remount the path DEST as readonly. It works only on the specified
199 mount point, without changing any other mount point under the
200 specified path
201 --proc DEST
203 Mount procfs on DEST
204 --dev DEST
206 Mount new devtmpfs on DEST
207 --tmpfs DEST
209 Mount new tmpfs on DEST. If the previous option was --perms, it
210 sets the mode of the tmpfs. Otherwise, the tmpfs has mode 0755. If
211 the previous option was --size, it sets the size in bytes of the
212 tmpfs. Otherwise, the tmpfs has the default size.
213 --mqueue DEST
215 Mount new mqueue on DEST
216 --dir DEST
218 Create a directory at DEST. If the directory already exists, its
219 permissions are unmodified, ignoring --perms (use --chmod if the
220 permissions of an existing directory need to be changed). If the
221 directory is newly created and the previous option was --perms, it
222 sets the mode of the directory. Otherwise, newly-created
223 directories have mode 0755.
224 --file FD DEST
226 Copy from the file descriptor FD to DEST. If the previous option
227 was --perms, it sets the mode of the new file. Otherwise, the file
228 has mode 0666 (note that this is not the same as --bind-data).
229 --bind-data FD DEST
231 Copy from the file descriptor FD to a file which is bind-mounted on
232 DEST. If the previous option was --perms, it sets the mode of the
233 new file. Otherwise, the file has mode 0600 (note that this is not
234 the same as --file).
235 --ro-bind-data FD DEST
237 Copy from the file descriptor FD to a file which is bind-mounted
238 read-only on DEST. If the previous option was --perms, it sets the
239 mode of the new file. Otherwise, the file has mode 0600 (note that
240 this is not the same as --file).
241 --symlink SRC DEST
243 Create a symlink at DEST with target SRC
244 --chmod OCTAL PATH
246 Set the permissions of PATH, which must already exist, to OCTAL.
247 Lockdown options:
249 --seccomp FD
251 Load and use seccomp rules from FD. The rules need to be in the
252 form of a compiled cBPF program, as generated by
253 seccomp_export_bpf. If this option is given more than once, only
254 the last one is used. Use --add-seccomp-fd if multiple seccomp
255 programs are needed.
256 --add-seccomp-fd FD
258 Load and use seccomp rules from FD. The rules need to be in the
259 form of a compiled cBPF program, as generated by
260 seccomp_export_bpf. This option can be repeated, in which case all
261 the seccomp programs will be loaded in the order given (note that
262 the kernel will evaluate them in reverse order, so the last program
263 on the bwrap command-line is evaluated first). All of them, except
264 possibly the last, must allow use of the PR_SET_SECCOMP prctl. This
265 option cannot be combined with --seccomp.
266 --exec-label LABEL
268 Exec Label from the sandbox. On an SELinux system you can specify
269 the SELinux context for the sandbox process(s).
270 --file-label LABEL
272 File label for temporary sandbox content. On an SELinux system you
273 can specify the SELinux context for the sandbox content.
274 --block-fd FD
276 Block the sandbox on reading from FD until some data is available.
277 --userns-block-fd FD
279 Do not initialize the user namespace but wait on FD until it is
280 ready. This allow external processes (like newuidmap/newgidmap) to
281 setup the user namespace before it is used by the sandbox process.
282 --info-fd FD
284 Write information in JSON format about the sandbox to FD.
285 --json-status-fd FD
287 Multiple JSON documents are written to FD, one per line ("JSON
288 lines" format[1]). Each line is a single JSON object. After bwrap
289 has started the child process inside the sandbox, it writes an
290 object with a child-pid member to the --json-status-fd (this
291 duplicates the older --info-fd). The corresponding value is the
292 process ID of the child process in the pid namespace from which
293 bwrap was run. If available, the namespace IDs are also included in
294 the object with the child-pid; again, this duplicates the older
295 --info-fd. When the child process inside the sandbox exits, bwrap
296 writes an object with an exit-code member, and then closes the
297 --json-status-fd. The value corresponding to exit-code is the exit
298 status of the child, in the usual shell encoding (n if it exited
299 normally with status n, or 128+n if it was killed by signal n).
300 Other members may be added to those objects in future versions of
301 bwrap, and other JSON objects may be added before or after the
302 current objects, so readers must ignore members and objects that
303 they do not understand.
304 --new-session
306 Create a new terminal session for the sandbox (calls setsid()).
307 This disconnects the sandbox from the controlling terminal which
308 means the sandbox can't for instance inject input into the
309 terminal.
310 Note: In a general sandbox, if you don't use --new-session, it is
312 recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise
313 the application can feed keyboard input to the terminal.
314 --die-with-parent
316 Ensures child process (COMMAND) dies when bwrap's parent dies.
317 Kills (SIGKILL) all bwrap sandbox processes in sequence from parent
318 to child including COMMAND process when bwrap or bwrap's parent
319 dies. See prctl, PR_SET_PDEATHSIG.
320 --as-pid-1
322 Do not create a process with PID=1 in the sandbox to reap child
323 processes.
324 --cap-add CAP
326 Add the specified capability when running as privileged user. It
327 accepts the special value ALL to add all the permitted caps.
328 --cap-drop CAP
330 Drop the specified capability when running as privileged user. It
331 accepts the special value ALL to drop all the caps. By default no
332 caps are left in the sandboxed process. The --cap-add and
333 --cap-drop options are processed in the order they are specified on
334 the command line. Please be careful to the order they are
335 specified.
336
338 HOME
339 Used as the cwd in the sandbox if --chdir has not been explicitly
340 specified and the current cwd is not present inside the sandbox.
341 The --setenv option can be used to override the value that is used
342 here.
343
345 The bwrap command returns the exit status of the initial application
346 process (pid 2 in the sandbox).
347
349 1. "JSON lines" format
350 https://jsonlines.org/
351Project Atomic BWRAP(1)