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