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