1BWRAP(1)                         User Commands                        BWRAP(1)
2
3
4

NAME

6       bwrap - container setup utility
7

SYNOPSIS

9       bwrap [OPTION...] [COMMAND]
10

DESCRIPTION

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

OPTIONS

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

ENVIRONMENT

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

EXIT STATUS

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)
Impressum