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 --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 decendant of the currently
86 active user namespace, owned by the same user.
87 This is incompatible with --unshare-user, and doesn't work in the
89 setuid version of bubblewrap.
90 --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 decendant of the user namespace used for the setup, so this is only
95 useful in combination with --userns.
96 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 --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 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 --uid UID
111 Use a custom user id in the sandbox (requires --unshare-user)
112 --gid GID
114 Use a custom group id in the sandbox (requires --unshare-user)
115 --hostname HOSTNAME
117 Use a custom hostname in the sandbox (requires --unshare-uts)
118 Options about environment setup:
120 --chdir DIR
122 Change directory to DIR
123 --setenv VAR VALUE
125 Set an environment variable
126 --unsetenv VAR
128 Unset an environment variable
129 Options for monitoring the sandbox from the outside:
131 --lock-file DEST
133 Take a lock on DEST while the sandbox is running. This option can
134 be used multiple times to take locks on multiple files.
135 --sync-fd FD
137 Keep this file descriptor open while the sandbox is running
138 Filesystem related options. These are all operations that modify the
140 filesystem directly, or mounts stuff in the filesystem. These are
141 applied in the order they are given as arguments. Any missing parent
142 directories that are required to create a specified destination are
143 automatically created as needed.
144 --bind SRC DEST
146 Bind mount the host path SRC on DEST
147 --bind-try SRC DEST
149 Equal to --bind but ignores non-existent SRC
150 --dev-bind SRC DEST
152 Bind mount the host path SRC on DEST, allowing device access
153 --dev-bind-try SRC DEST
155 Equal to --dev-bind but ignores non-existent SRC
156 --ro-bind SRC DEST
158 Bind mount the host path SRC readonly on DEST
159 --ro-bind-try SRC DEST
161 Equal to --ro-bind but ignores non-existent SRC
162 --remount-ro DEST
164 Remount the path DEST as readonly. It works only on the specified
165 mount point, without changing any other mount point under the
166 specified path
167 --proc DEST
169 Mount procfs on DEST
170 --dev DEST
172 Mount new devtmpfs on DEST
173 --tmpfs DEST
175 Mount new tmpfs on DEST
176 --mqueue DEST
178 Mount new mqueue on DEST
179 --dir DEST
181 Create a directory at DEST
182 --file FD DEST
184 Copy from the file descriptor FD to DEST
185 --bind-data FD DEST
187 Copy from the file descriptor FD to a file which is bind-mounted on
188 DEST
189 --ro-bind-data FD DEST
191 Copy from the file descriptor FD to a file which is bind-mounted
192 readonly on DEST
193 --symlink SRC DEST
195 Create a symlink at DEST with target SRC
196 Lockdown options:
198 --seccomp FD
200 Load and use seccomp rules from FD. The rules need to be in the
201 form of a compiled eBPF program, as generated by
202 seccomp_export_bpf.
203 --exec-label LABEL
205 Exec Label from the sandbox. On an SELinux system you can specify
206 the SELinux context for the sandbox process(s).
207 --file-label LABEL
209 File label for temporary sandbox content. On an SELinux system you
210 can specify the SELinux context for the sandbox content.
211 --block-fd FD
213 Block the sandbox on reading from FD until some data is available.
214 --userns-block-fd FD
216 Do not initialize the user namespace but wait on FD until it is
217 ready. This allow external processes (like newuidmap/newgidmap) to
218 setup the user namespace before it is used by the sandbox process.
219 --info-fd FD
221 Write information in JSON format about the sandbox to FD.
222 --new-session
224 Create a new terminal session for the sandbox (calls setsid()).
225 This disconnects the sandbox from the controlling terminal which
226 means the sandbox can't for instance inject input into the
227 terminal.
228 Note: In a general sandbox, if you don't use --new-session, it is
230 recommended to use seccomp to disallow the TIOCSTI ioctl, otherwise
231 the application can feed keyboard input to the terminal.
232 --die-with-parent
234 Ensures child process (COMMAND) dies when bwrap's parent dies.
235 Kills (SIGKILL) all bwrap sandbox processes in sequence from parent
236 to child including COMMAND process when bwrap or bwrap's parent
237 dies. See prctl, PR_SET_PDEATHSIG.
238 --as-pid-1
240 Do not create a process with PID=1 in the sandbox to reap child
241 processes.
242 --cap-add CAP
244 Add the specified capability when running as privileged user. It
245 accepts the special value ALL to add all the permitted caps.
246 --cap-drop CAP
248 Drop the specified capability when running as privileged user. It
249 accepts the special value ALL to drop all the caps. By default no
250 caps are left in the sandboxed process. The --cap-add and
251 --cap-drop options are processed in the order they are specified on
252 the command line. Please be careful to the order they are
253 specified.
254
256 HOME
257 Used as the cwd in the sandbox if --chdir has not been explicitly
258 specified and the current cwd is not present inside the sandbox.
259 The --setenv option can be used to override the value that is used
260 here.
261
263 The bwrap command returns the exit status of the initial application
264 process (pid 2 in the sandbox).
265Project Atomic BWRAP(1)