1BWRAP(1) User Commands BWRAP(1)
2
3
4
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
15 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
21 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
27 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
38 General options:
39
40 --help
41 Print help and exit
42
43 --version
44 Print version
45
46 --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
51 Options related to kernel namespaces:
52
53 --unshare-user
54 Create a new user namespace
55
56 --unshare-user-try
57 Create a new user namespace if possible else skip it
58
59 --unshare-ipc
60 Create a new ipc namespace
61
62 --unshare-pid
63 Create a new pid namespace
64
65 --unshare-net
66 Create a new network namespace
67
68 --unshare-uts
69 Create a new uts namespace
70
71 --unshare-cgroup
72 Create a new cgroup namespace
73
74 --unshare-cgroup-try
75 Create a new cgroup namespace if possible else skip it
76
77 --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
82 --userns FD
83 Use an existing user namespace instead of creating a new one. The
84 namespace must fulfil the permission requirements for setns(),
85 which generally means that it must be a descendant of the currently
86 active user namespace, owned by the same user.
87
88 This is incompatible with --unshare-user, and doesn't work in the
89 setuid version of bubblewrap.
90
91 --userns2 FD
92 After setting up the new namespace, switch into the specified
93 namespace. For this to work the specified namespace must be a
94 descendant of the user namespace used for the setup, so this is
95 only useful in combination with --userns.
96
97 This is useful because sometimes bubblewrap itself creates nested
98 user namespaces (to work around some kernel issues) and --userns2
99 can be used to enter these.
100
101 --pidns FD
102 Use an existing pid namespace instead of creating one. This is
103 often used with --userns, because the pid namespace must be owned
104 by the same user namespace that bwrap uses.
105
106 Note that this can be combined with --unshare-pid, and in that case
107 it means that the sandbox will be in its own pid namespace, which
108 is a child of the passed in one.
109
110 --uid UID
111 Use a custom user id in the sandbox (requires --unshare-user)
112
113 --gid GID
114 Use a custom group id in the sandbox (requires --unshare-user)
115
116 --hostname HOSTNAME
117 Use a custom hostname in the sandbox (requires --unshare-uts)
118
119 Options about environment setup:
120
121 --chdir DIR
122 Change directory to DIR
123
124 --setenv VAR VALUE
125 Set an environment variable
126
127 --unsetenv VAR
128 Unset an environment variable
129
130 --clearenv
131 Unset all environment variables, except for PWD and any that are
132 subsequently set by --setenv
133
134 Options for monitoring the sandbox from the outside:
135
136 --lock-file DEST
137 Take a lock on DEST while the sandbox is running. This option can
138 be used multiple times to take locks on multiple files.
139
140 --sync-fd FD
141 Keep this file descriptor open while the sandbox is running
142
143 Filesystem related options. These are all operations that modify the
144 filesystem directly, or mounts stuff in the filesystem. These are
145 applied in the order they are given as arguments.
146
147 Any missing parent directories that are required to create a specified
148 destination are automatically created as needed. Their permissions are
149 normally set to 0755 (rwxr-xr-x). However, if a --perms option is in
150 effect, and it sets the permissions for group or other to zero, then
151 newly-created parent directories will also have their corresponding
152 permission set to zero.
153
154 --perms OCTAL
155 This option does nothing on its own, and must be followed by one of
156 the options that it affects. It sets the permissions for the next
157 operation to OCTAL. Subsequent operations are not affected: for
158 example, --perms 0700 --tmpfs /a --tmpfs /b will mount /a with
159 permissions 0700, then return to the default permissions for /b.
160
161 --bind SRC DEST
162 Bind mount the host path SRC on DEST
163
164 --bind-try SRC DEST
165 Equal to --bind but ignores non-existent SRC
166
167 --dev-bind SRC DEST
168 Bind mount the host path SRC on DEST, allowing device access
169
170 --dev-bind-try SRC DEST
171 Equal to --dev-bind but ignores non-existent SRC
172
173 --ro-bind SRC DEST
174 Bind mount the host path SRC readonly on DEST
175
176 --ro-bind-try SRC DEST
177 Equal to --ro-bind but ignores non-existent SRC
178
179 --remount-ro DEST
180 Remount the path DEST as readonly. It works only on the specified
181 mount point, without changing any other mount point under the
182 specified path
183
184 --proc DEST
185 Mount procfs on DEST
186
187 --dev DEST
188 Mount new devtmpfs on DEST
189
190 --tmpfs DEST
191 Mount new tmpfs on DEST. If the previous option was --perms, it
192 sets the mode of the tmpfs. Otherwise, the tmpfs has mode 0755.
193
194 --mqueue DEST
195 Mount new mqueue on DEST
196
197 --dir DEST
198 Create a directory at DEST. If the directory already exists, its
199 permissions are unmodified, ignoring --perms (use --chmod if the
200 permissions of an existing directory need to be changed). If the
201 directory is newly created and the previous option was --perms, it
202 sets the mode of the directory. Otherwise, newly-created
203 directories have mode 0755.
204
205 --file FD DEST
206 Copy from the file descriptor FD to DEST. If the previous option
207 was --perms, it sets the mode of the new file. Otherwise, the file
208 has mode 0666 (note that this is not the same as --bind-data).
209
210 --bind-data FD DEST
211 Copy from the file descriptor FD to a file which is bind-mounted on
212 DEST. If the previous option was --perms, it sets the mode of the
213 new file. Otherwise, the file has mode 0600 (note that this is not
214 the same as --file).
215
216 --ro-bind-data FD DEST
217 Copy from the file descriptor FD to a file which is bind-mounted
218 read-only on DEST. If the previous option was --perms, it sets the
219 mode of the new file. Otherwise, the file has mode 0600 (note that
220 this is not the same as --file).
221
222 --symlink SRC DEST
223 Create a symlink at DEST with target SRC
224
225 --chmod OCTAL PATH
226 Set the permissions of PATH, which must already exist, to OCTAL.
227
228 Lockdown options:
229
230 --seccomp FD
231 Load and use seccomp rules from FD. The rules need to be in the
232 form of a compiled cBPF program, as generated by
233 seccomp_export_bpf.
234
235 --exec-label LABEL
236 Exec Label from the sandbox. On an SELinux system you can specify
237 the SELinux context for the sandbox process(s).
238
239 --file-label LABEL
240 File label for temporary sandbox content. On an SELinux system you
241 can specify the SELinux context for the sandbox content.
242
243 --block-fd FD
244 Block the sandbox on reading from FD until some data is available.
245
246 --userns-block-fd FD
247 Do not initialize the user namespace but wait on FD until it is
248 ready. This allow external processes (like newuidmap/newgidmap) to
249 setup the user namespace before it is used by the sandbox process.
250
251 --info-fd FD
252 Write information in JSON format about the sandbox to FD.
253
254 --new-session
255 Create a new terminal session for the sandbox (calls setsid()).
256 This disconnects the sandbox from the controlling terminal which
257 means the sandbox can't for instance inject input into the
258 terminal.
259
260 Note: In a general sandbox, if you don't use --new-session, it is
261 recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise
262 the application can feed keyboard input to the terminal.
263
264 --die-with-parent
265 Ensures child process (COMMAND) dies when bwrap's parent dies.
266 Kills (SIGKILL) all bwrap sandbox processes in sequence from parent
267 to child including COMMAND process when bwrap or bwrap's parent
268 dies. See prctl, PR_SET_PDEATHSIG.
269
270 --as-pid-1
271 Do not create a process with PID=1 in the sandbox to reap child
272 processes.
273
274 --cap-add CAP
275 Add the specified capability when running as privileged user. It
276 accepts the special value ALL to add all the permitted caps.
277
278 --cap-drop CAP
279 Drop the specified capability when running as privileged user. It
280 accepts the special value ALL to drop all the caps. By default no
281 caps are left in the sandboxed process. The --cap-add and
282 --cap-drop options are processed in the order they are specified on
283 the command line. Please be careful to the order they are
284 specified.
285
287 HOME
288 Used as the cwd in the sandbox if --chdir has not been explicitly
289 specified and the current cwd is not present inside the sandbox.
290 The --setenv option can be used to override the value that is used
291 here.
292
294 The bwrap command returns the exit status of the initial application
295 process (pid 2 in the sandbox).
296
297
298
299Project Atomic BWRAP(1)