BWRAP(1) User Commands BWRAP(1) NAME bwrap - container setup utility SYNOPSIS bwrap [OPTION...] [COMMAND] DESCRIPTION bwrap is a unprivileged low-level sandboxing tool (optionally setuid on older distributions). You are unlikely to use it directly from the command- line, although that is possible. It works by creating a new, completely empty, filesystem namespace where the root is on a tmpfs that is invisible from the host, and which will be automatically cleaned up when the last process exits. You can then use com- mandline options to construct the root filesystem and process environment for the command to run in the namespace. By default, bwrap creates a new mount namespace for the sandbox. Optionally it also sets up new user, ipc, pid, network and uts namespaces (but note the user namespace is required if bwrap is not installed setuid root). The application in the sandbox can be made to run with a different UID and GID. If needed (e.g. when using a PID namespace) bwrap is running a minimal pid 1 process in the sandbox that is responsible for reaping zombies. It also detects when the initial application process (pid 2) dies and reports its exit status back to the original spawner. The pid 1 process exits to clean up the sandbox when there are no other processes in the sandbox left. OPTIONS .PP When options are used multiple times, the last option wins, unless otherwise specified. .PP General options: .PP --help Print help and exit .RE .PP --version Print version .RE .PP --args FD Parse nul-separated arguments from the given file de- scriptor. This option can be used multiple times to parse op- tions from multiple sources. .RE .PP --argv0 VALUE Set argv[0] to the value VALUE before running the program .RE .PP --level-prefix Prefix each line of diagnostic output with a numeric severity level enclosed in angle brackets. The severity levels used are based on the constants used by syslog(3): for example, <4> indicates a warning, be- cause LOG_WARNING has numeric value 4. Numbers smaller than 4 indicate fatal errors, and numbers larger than 4 indicate informational messages. These prefixes can be parsed by tools compatible with logger --prio-prefix (see logger(1)) or systemd-cat --level-prefix=1 (see systemd-cat(1)). .RE .PP Options related to kernel namespaces: .PP --unshare-user Create a new user namespace .RE .PP --unshare-user-try Create a new user namespace if possible else skip it .RE .PP --unshare-ipc Create a new ipc namespace .RE .PP --unshare-pid Create a new pid namespace .RE .PP --unshare-net Create a new network name- space .RE .PP --unshare-uts Create a new uts name- space .RE .PP --unshare-cgroup Create a new cgroup namespace .RE .PP --un- share-cgroup-try Create a new cgroup namespace if possible else skip it .RE .PP --unshare-all Unshare all possible name- spaces. Currently equivalent with: --unshare-user-try --unshare-ipc --un- share-pid --un- share-net --un- share-uts --un- share-cgroup-try .RE .PP --share-net Retain the network namespace, overriding an earlier --un- share-all or --unshare-net .RE .PP --userns FD Use an existing user name- space in- stead of creating a new one. The name- space must fulfil the permission require- ments for setns(), which gen- erally means that it must be a descen- dant of the currently active user namespace, owned by the same user. This is incom- patible with --un- share-user, and doesn't work in the setuid ver- sion of bubblewrap. .RE .PP --userns2 FD Af- ter setting up the new name- space, switch into the speci- fied name- space. For this to work the speci- fied name- space must be a de- scen- dant of the user name- space used for the setup, so this is only useful in com- bina- tion with --userns. This is use- ful be- cause some- times bub- blewrap itself creates nested user name- spaces (to work around some kernel issues) and --userns2 can be used to enter these. .RE .PP --dis- able-userns Pre- vent the process in the sand- box from cre- at- ing fur- ther user name- spaces, so that it can- not re- arrange the filesys- tem name- space or do other more com- plex name- space mod- i- fi- ca- tion. This is cur- rently im- ple- mented by set- ting the user.max_user_name- spaces sysctl to 1, and then en- ter- ing a nested user name- space which is un- able to raise that limit in the outer name- space. This op- tion re- quires --un- share-user, and doesn't work in the se- tuid ver- sion of bub- blewrap. .RE .PP --as- sert-userns-dis- abled Con- firm that the process in the sand- box has been pre- vented from cre- at- ing fur- ther user name- spaces, but with- out tak- ing any par- tic- u- lar ac- tion to pre- vent that. For ex- am- ple, this can be com- bined with --userns to check that the given user name- space has al- ready been set up to pre- vent the cre- ation of fur- ther user name- spaces. .RE .PP --pidns FD Use an ex- ist- ing pid name- space in- stead of cre- at- ing one. This is of- ten used with --userns, be- cause the pid name- space must be owned by the same user name- space that bwrap uses. Note that this can be com- bined with --un- share-pid, and in that case it means that the sand- box will be in its own pid name- space, which is a child of the passed in one. .RE .PP --uid UID Use a cus- tom user id in the sand- box (re- quires --un- share-user) .RE .PP --gid GID Use a cus- tom group id in the sand- box (re- quires --un- share-user) .RE .PP --host- name HOST- NAME Use a cus- tom host- name in the sand- box (re- quires --un- share-uts) .RE .PP Op- tions about en- vi- ron- ment setup: .PP --chdir DIR Change di- rec- tory to DIR .RE .PP --setenv VAR VALUE Set an en- vi- ron- ment vari- able .RE .PP --un- setenv VAR Un- set an en- vi- ron- ment vari- able .RE .PP --clearenv Un- set all en- vi- ron- ment vari- ables, ex- cept for PWD and any that are sub- se- quently set by --setenv .RE .PP Op- tions for mon- i- tor- ing the sand- box from the out- side: .PP --lock-file DEST Take a lock on DEST while the sand- box is run- ning. This op- tion can be used mul- ti- ple times to take locks on mul- ti- ple files. .RE .PP --sync-fd FD Keep this file de- scrip- tor open while the sand- box is run- ning .RE .PP Filesys- tem re- lated op- tions. These are all op- er- a- tions that mod- ify the filesys- tem di- rectly, or mounts stuff in the filesys- tem. These are ap- plied in the or- der they are given as ar- gu- ments. .PP Any miss- ing par- ent di- rec- to- ries that are re- quired to cre- ate a spec- i- fied des- ti- na- tion are au- to- mat- i- cally cre- ated as needed. Their per- mis- sions are nor- mally set to 0755 (rwxr-xr-x). How- ever, if a --perms op- tion is in ef- fect, and it sets the per- mis- sions for group or other to zero, then newly-cre- ated par- ent di- rec- to- ries will also have their cor- re- spond- ing per- mis- sion set to zero. --size mod- i- fies the size of the cre- ated mount when pre- ced- ing a --tmpfs ac- tion; --perms and --size can be com- bined. .PP --perms OC- TAL This op- tion does noth- ing on its own, and must be fol- lowed by one of the op- tions that it af- fects. It sets the per- mis- sions for the next op- er- a- tion to OC- TAL. Sub- se- quent op- er- a- tions are not af- fected: for ex- am- ple, --perms 0700 --tmpfs /a --tmpfs /b will mount /a with per- mis- sions 0700, then re- turn to the de- fault per- mis- sions for /b. Note that --perms and --size can be com- bined: --perms 0700 --size 10485760 --tmpfs /s will ap- ply per- mis- sions as well as a max- i- mum size to the cre- ated tmpfs. .RE .PP --size BYTES This op- tion does noth- ing on its own, and must be fol- lowed by --tmpfs. It sets the size in bytes for the next tmpfs. For ex- am- ple, --size 10485760 --tmpfs /tmp will cre- ate a tmpfs at /tmp of size 10MiB. Sub- se- quent op- er- a- tions are not af- fected: for ex- am- ple, --size 10485760 --tmpfs /a --tmpfs /b will mount /a with size 10MiB, then re- turn to the de- fault size for /b. Note that --perms and --size can be com- bined: --size 10485760 --perms 0700 --tmpfs /s will ap- ply per- mis- sions as well as a max- i- mum size to the cre- ated tmpfs. .RE .PP --bind SRC DEST Bind mount the host path SRC on DEST .RE .PP --bind-try SRC DEST Equal to --bind but ig- nores non-ex- is- tent SRC .RE .PP --dev-bind SRC DEST Bind mount the host path SRC on DEST, al- low- ing de- vice ac- cess .RE .PP --dev-bind-try SRC DEST Equal to --dev-bind but ig- nores non-ex- is- tent SRC .RE .PP --ro-bind SRC DEST Bind mount the host path SRC read- only on DEST .RE .PP --ro-bind-try SRC DEST Equal to --ro-bind but ig- nores non-ex- is- tent SRC .RE .PP --re- mount-ro DEST Re- mount the path DEST as read- only. It works only on the spec- i- fied mount point, with- out chang- ing any other mount point un- der the spec- i- fied path .RE .PP --over- lay-src SRC This op- tion does noth- ing on its own, and must be fol- lowed by one of the other over- lay op- tions. It spec- i- fies a host path from which files should be read if they aren't present in a higher layer. This op- tion can be used mul- ti- ple times to pro- vide mul- ti- ple sources. The sources are over- laid in the or- der given, with the first source on the com- mand line at the bot- tom of the stack: if a given path to be read ex- ists in more than one source, the file is read from the last such source spec- i- fied. (For read- ers fa- mil- iar with over- layfs, note that this is the re- verse of the or- der used by the ker- nel's low- erdir mount op- tion.) .RE .PP --over- lay RWSRC WORKDIR DEST .RE .PP --tmp-over- lay DEST .RE .PP --ro-over- lay DEST Use over- layfs to mount the host paths spec- i- fied by RWSRC and all im- me- di- ately pre- ced- ing --over- lay-src on DEST. DEST will con- tain the union of all the files in all the lay- ers. With --over- lay all writes will go to RWSRC. Reads will come pref- er- en- tially from RWSRC, and then from any --over- lay-src paths. WORKDIR must be an empty di- rec- tory on the same filesys- tem as RWSRC, and is used in- ter- nally by the ker- nel. With --tmp-over- lay all writes will go to the tmpfs that hosts the sand- box root, in a lo- ca- tion not ac- ces- si- ble from ei- ther the host or the child process. Writes will there- fore not be per- sisted across mul- ti- ple runs. With --ro-over- lay the filesys- tem will be mounted read-only. This op- tion re- quires at least two --over- lay-src to pre- cede it. None of these op- tions are avail- able in the se- tuid ver- sion of bub- blewrap. Us- ing --ro-over- lay or pro- vid- ing more than one --over- lay-src re- quires a Linux ker- nel ver- sion of 4.0 or later. Due to lim- i- ta- tions of over- layfs, no host di- rec- tory given via --over- lay-src or --over- lay may be an an- ces- tor of an- other, af- ter re- solv- ing sym- links. De- pend- ing on ver- sion, the Linux ker- nel may or may not en- force this, but if not then over- layfs's be- hav- ior is un- de- fined. For more in- for- ma- tion see the Over- lay Filesys- tem doc- u- men- ta- tion in the Linux ker- nel at https://www.ker- nel.org/doc/Doc- u- men- ta- tion/filesys- tems/over- layfs.txt .RE .PP --proc DEST Mount procfs on DEST .RE .PP --dev DEST Mount new de- vtmpfs on DEST .RE .PP --tmpfs DEST Mount new tmpfs on DEST. If the pre- vi- ous op- tion was --perms, it sets the mode of the tmpfs. Oth- er- wise, the tmpfs has mode 0755. If the pre- vi- ous op- tion was --size, it sets the size in bytes of the tmpfs. Oth- er- wise, the tmpfs has the de- fault size. .RE .PP --mqueue DEST Mount new mqueue on DEST .RE .PP --dir DEST Cre- ate a di- rec- tory at DEST. If the di- rec- tory al- ready ex- ists, its per- mis- sions are un- mod- i- fied, ig- nor- ing --perms (use --chmod if the per- mis- sions of an ex- ist- ing di- rec- tory need to be changed). If the di- rec- tory is newly cre- ated and the pre- vi- ous op- tion was --perms, it sets the mode of the di- rec- tory. Oth- er- wise, newly-cre- ated di- rec- to- ries have mode 0755. .RE .PP --file FD DEST Copy from the file de- scrip- tor FD to DEST. If the pre- vi- ous op- tion was --perms, it sets the mode of the new file. Oth- er- wise, the file has mode 0666 (note that this is not the same as --bind-data). .RE .PP --bind-data FD DEST Copy from the file de- scrip- tor FD to a file which is bind-mounted on DEST. If the pre- vi- ous op- tion was --perms, it sets the mode of the new file. Oth- er- wise, the file has mode 0600 (note that this is not the same as --file). .RE .PP --ro-bind-data FD DEST Copy from the file de- scrip- tor FD to a file which is bind-mounted read-only on DEST. If the pre- vi- ous op- tion was --perms, it sets the mode of the new file. Oth- er- wise, the file has mode 0600 (note that this is not the same as --file). .RE .PP --sym- link SRC DEST Cre- ate a sym- link at DEST with tar- get SRC. Since ver- sion 0.9.0, it is not con- sid- ered to be an er- ror if DEST al- ready ex- ists as a sym- bolic link and its tar- get is ex- actly SRC. Be- fore ver- sion 0.9.0, if DEST al- ready ex- isted, this would be treated as an er- ror (even if its tar- get was iden- ti- cal to SRC). .RE .PP --chmod OC- TAL PATH Set the per- mis- sions of PATH, which must al- ready ex- ist, to OC- TAL. .RE .PP Lock- down op- tions: .PP --sec- comp FD Load and use sec- comp rules from FD. The rules need to be in the form of a com- piled cBPF pro- gram, as gen- er- ated by sec- comp_ex- port_bpf. If this op- tion is given more than once, only the last one is used. Use --add-sec- comp-fd if mul- ti- ple sec- comp pro- grams are needed. .RE .PP --add-sec- comp-fd FD Load and use sec- comp rules from FD. The rules need to be in the form of a com- piled cBPF pro- gram, as gen- er- ated by sec- comp_ex- port_bpf. This op- tion can be re- peated, in which case all the sec- comp pro- grams will be loaded in the or- der given (note that the ker- nel will eval- u- ate them in re- verse or- der, so the last pro- gram on the bwrap com- mand-line is eval- u- ated first). All of them, ex- cept pos- si- bly the last, must al- low use of the PR_SET_SEC- COMP prctl. This op- tion can- not be com- bined with --sec- comp. .RE .PP --exec-la- bel LA- BEL Exec La- bel from the sand- box. On an SELinux sys- tem you can spec- ify the SELinux con- text for the sand- box process(s). .RE .PP --file-la- bel LA- BEL File la- bel for tem- po- rary sand- box con- tent. On an SELinux sys- tem you can spec- ify the SELinux con- text for the sand- box con- tent. .RE .PP --block-fd FD Block the sand- box on read- ing from FD un- til some data is avail- able. .RE .PP --userns-block-fd FD Do not ini- tial- ize the user name- space but wait on FD un- til it is ready. This al- low ex- ter- nal processes (like newuidmap/newgidmap) to setup the user name- space be- fore it is used by the sand- box process. .RE .PP --info-fd FD Write in- for- ma- tion in JSON for- mat about the sand- box to FD. .RE .PP --json-sta- tus-fd FD Mul- ti- ple JSON doc- u- ments are writ- ten to FD, one per line ("JSON lines" for- mat[1]). Each line is a sin- gle JSON ob- ject. Af- ter bwrap has started the child process in- side the sand- box, it writes an ob- ject with a child-pid mem- ber to the --json-sta- tus-fd (this du- pli- cates the older --info-fd). The cor- re- spond- ing value is the process ID of the child process in the pid name- space from which bwrap was run. If avail- able, the name- space IDs are also in- cluded in the ob- ject with the child-pid; again, this du- pli- cates the older --info-fd. When the child process in- side the sand- box ex- its, bwrap writes an ob- ject with an exit-code mem- ber, and then closes the --json-sta- tus-fd. The value cor- re- spond- ing to exit-code is the exit sta- tus of the child, in the usual shell en- cod- ing (n if it ex- ited nor- mally with sta- tus n, or 128+n if it was killed by sig- nal n). Other mem- bers may be added to those ob- jects in fu- ture ver- sions of bwrap, and other JSON ob- jects may be added be- fore or af- ter the cur- rent ob- jects, so read- ers must ig- nore mem- bers and ob- jects that they do not un- der- stand. .RE .PP --new-ses- sion Cre- ate a new ter- mi- nal ses- sion for the sand- box (calls set- sid()). This dis- con- nects the sand- box from the con- trol- ling ter- mi- nal which means the sand- box can't for in- stance in- ject in- put into the ter- mi- nal. Note: In a gen- eral sand- box, if you don't use --new-ses- sion, it is rec- om- mended to use sec- comp to dis- al- low the TI- OC- STI ioctl, oth- er- wise the ap- pli- ca- tion can feed key- board in- put to the ter- mi- nal which can e.g. lead to out-of-sand- box com- mand ex- e- cu- tion (see CVE-2017-5226). .RE .PP --die-with-par- ent En- sures child process (COM- MAND) dies when bwrap's par- ent dies. Kills (SIGKILL) all bwrap sand- box processes in se- quence from par- ent to child in- clud- ing COM- MAND process when bwrap or bwrap's par- ent dies. See prctl, PR_SET_PDEATH- SIG. .RE .PP --as-pid-1 Do not cre- ate a process with PID=1 in the sand- box to reap child processes. .RE .PP --cap-add CAP Add the spec- i- fied ca- pa- bil- ity CAP, e.g. CAP_DAC_READ_SEARCH, when run- ning as priv- i- leged user. It ac- cepts the spe- cial value ALL to add all the per- mit- ted caps. .RE .PP --cap-drop CAP Drop the spec- i- fied ca- pa- bil- ity when run- ning as priv- i- leged user. It ac- cepts the spe- cial value ALL to drop all the caps. By de- fault no caps are left in the sand- boxed process. The --cap-add and --cap-drop op- tions are processed in the or- der they are spec- i- fied on the com- mand line. Please be care- ful to the or- der they are spec- i- fied. .RE ENVIRONMENT .PP HOME Used as the cwd in the sandbox if --chdir has not been explicitly specified and the current cwd is not present inside the sandbox. The --setenv option can be used to override the value that is used here. .RE EXIT STATUS .PP The bwrap command returns the exit status of the initial application process (pid 2 in the sandbox). NOTES 1. "JSON lines" format https://jsonlines.org/ Containers BWRAP(1)