Provided by: bubblewrap_0.8.0-2_amd64 bug

NAME

       bwrap - container setup utility

SYNOPSIS

       bwrap [OPTION...] [COMMAND]

DESCRIPTION

       bwrap is a privileged helper for container setup. You are unlikely to use it directly from
       the commandline, 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 commandline 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

       When options are used multiple times, the last option wins, unless otherwise specified.

       General options:

       --help
           Print help and exit

       --version
           Print version

       --args FD
           Parse nul-separated arguments from the given file descriptor. This option can be used
           multiple times to parse options from multiple sources.

       Options related to kernel namespaces:

       --unshare-user
           Create a new user namespace

       --unshare-user-try
           Create a new user namespace if possible else skip it

       --unshare-ipc
           Create a new ipc namespace

       --unshare-pid
           Create a new pid namespace

       --unshare-net
           Create a new network namespace

       --unshare-uts
           Create a new uts namespace

       --unshare-cgroup
           Create a new cgroup namespace

       --unshare-cgroup-try
           Create a new cgroup namespace if possible else skip it

       --unshare-all
           Unshare all possible namespaces. Currently equivalent with: --unshare-user-try
           --unshare-ipc --unshare-pid --unshare-net --unshare-uts --unshare-cgroup-try

       --share-net
           Retain the network namespace, overriding an earlier --unshare-all or --unshare-net

       --userns FD
           Use an existing user namespace instead of creating a new one. The namespace must
           fulfil the permission requirements for setns(), which generally means that it must be
           a descendant of the currently active user namespace, owned by the same user.

           This is incompatible with --unshare-user, and doesn't work in the setuid version of
           bubblewrap.

       --userns2 FD
           After setting up the new namespace, switch into the specified namespace. For this to
           work the specified namespace must be a descendant of the user namespace used for the
           setup, so this is only useful in combination with --userns.

           This is useful because sometimes bubblewrap itself creates nested user namespaces (to
           work around some kernel issues) and --userns2 can be used to enter these.

       --disable-userns
           Prevent the process in the sandbox from creating further user namespaces, so that it
           cannot rearrange the filesystem namespace or do other more complex namespace
           modification. This is currently implemented by setting the user.max_user_namespaces
           sysctl to 1, and then entering a nested user namespace which is unable to raise that
           limit in the outer namespace. This option requires --unshare-user, and doesn't work in
           the setuid version of bubblewrap.

       --assert-userns-disabled
           Confirm that the process in the sandbox has been prevented from creating further user
           namespaces, but without taking any particular action to prevent that. For example,
           this can be combined with --userns to check that the given user namespace has already
           been set up to prevent the creation of further user namespaces.

       --pidns FD
           Use an existing pid namespace instead of creating one. This is often used with
           --userns, because the pid namespace must be owned by the same user namespace that
           bwrap uses.

           Note that this can be combined with --unshare-pid, and in that case it means that the
           sandbox will be in its own pid namespace, which is a child of the passed in one.

       --uid UID
           Use a custom user id in the sandbox (requires --unshare-user)

       --gid GID
           Use a custom group id in the sandbox (requires --unshare-user)

       --hostname HOSTNAME
           Use a custom hostname in the sandbox (requires --unshare-uts)

       Options about environment setup:

       --chdir DIR
           Change directory to DIR

       --setenv VAR VALUE
           Set an environment variable

       --unsetenv VAR
           Unset an environment variable

       --clearenv
           Unset all environment variables, except for PWD and any that are subsequently set by
           --setenv

       Options for monitoring the sandbox from the outside:

       --lock-file DEST
           Take a lock on DEST while the sandbox is running. This option can be used multiple
           times to take locks on multiple files.

       --sync-fd FD
           Keep this file descriptor open while the sandbox is running

       Filesystem related options. These are all operations that modify the filesystem directly,
       or mounts stuff in the filesystem. These are applied in the order they are given as
       arguments.

       Any missing parent directories that are required to create a specified destination are
       automatically created as needed. Their permissions are normally set to 0755 (rwxr-xr-x).
       However, if a --perms option is in effect, and it sets the permissions for group or other
       to zero, then newly-created parent directories will also have their corresponding
       permission set to zero.  --size modifies the size of the created mount when preceding a
       --tmpfs action; --perms and --size can be combined.

       --perms OCTAL
           This option does nothing on its own, and must be followed by one of the options that
           it affects. It sets the permissions for the next operation to OCTAL. Subsequent
           operations are not affected: for example, --perms 0700 --tmpfs /a --tmpfs /b will
           mount /a with permissions 0700, then return to the default permissions for /b. Note
           that --perms and --size can be combined: --perms 0700 --size 10485760 --tmpfs /s will
           apply permissions as well as a maximum size to the created tmpfs.

       --size BYTES
           This option does nothing on its own, and must be followed by --tmpfs. It sets the size
           in bytes for the next tmpfs. For example, --size 10485760 --tmpfs /tmp will create a
           tmpfs at /tmp of size 10MiB. Subsequent operations are not affected: for example,
           --size 10485760 --tmpfs /a --tmpfs /b will mount /a with size 10MiB, then return to
           the default size for /b. Note that --perms and --size can be combined: --size 10485760
           --perms 0700 --tmpfs /s will apply permissions as well as a maximum size to the
           created tmpfs.

       --bind SRC DEST
           Bind mount the host path SRC on DEST

       --bind-try SRC DEST
           Equal to --bind but ignores non-existent SRC

       --dev-bind SRC DEST
           Bind mount the host path SRC on DEST, allowing device access

       --dev-bind-try SRC DEST
           Equal to --dev-bind but ignores non-existent SRC

       --ro-bind SRC DEST
           Bind mount the host path SRC readonly on DEST

       --ro-bind-try SRC DEST
           Equal to --ro-bind but ignores non-existent SRC

       --remount-ro DEST
           Remount the path DEST as readonly. It works only on the specified mount point, without
           changing any other mount point under the specified path

       --proc DEST
           Mount procfs on DEST

       --dev DEST
           Mount new devtmpfs on DEST

       --tmpfs DEST
           Mount new tmpfs on DEST. If the previous option was --perms, it sets the mode of the
           tmpfs. Otherwise, the tmpfs has mode 0755. If the previous option was --size, it sets
           the size in bytes of the tmpfs. Otherwise, the tmpfs has the default size.

       --mqueue DEST
           Mount new mqueue on DEST

       --dir DEST
           Create a directory at DEST. If the directory already exists, its permissions are
           unmodified, ignoring --perms (use --chmod if the permissions of an existing directory
           need to be changed). If the directory is newly created and the previous option was
           --perms, it sets the mode of the directory. Otherwise, newly-created directories have
           mode 0755.

       --file FD DEST
           Copy from the file descriptor FD to DEST. If the previous option was --perms, it sets
           the mode of the new file. Otherwise, the file has mode 0666 (note that this is not the
           same as --bind-data).

       --bind-data FD DEST
           Copy from the file descriptor FD to a file which is bind-mounted on DEST. If the
           previous option was --perms, it sets the mode of the new file. Otherwise, the file has
           mode 0600 (note that this is not the same as --file).

       --ro-bind-data FD DEST
           Copy from the file descriptor FD to a file which is bind-mounted read-only on DEST. If
           the previous option was --perms, it sets the mode of the new file. Otherwise, the file
           has mode 0600 (note that this is not the same as --file).

       --symlink SRC DEST
           Create a symlink at DEST with target SRC

       --chmod OCTAL PATH
           Set the permissions of PATH, which must already exist, to OCTAL.

       Lockdown options:

       --seccomp FD
           Load and use seccomp rules from FD. The rules need to be in the form of a compiled
           cBPF program, as generated by seccomp_export_bpf. If this option is given more than
           once, only the last one is used. Use --add-seccomp-fd if multiple seccomp programs are
           needed.

       --add-seccomp-fd FD
           Load and use seccomp rules from FD. The rules need to be in the form of a compiled
           cBPF program, as generated by seccomp_export_bpf. This option can be repeated, in
           which case all the seccomp programs will be loaded in the order given (note that the
           kernel will evaluate them in reverse order, so the last program on the bwrap
           command-line is evaluated first). All of them, except possibly the last, must allow
           use of the PR_SET_SECCOMP prctl. This option cannot be combined with --seccomp.

       --exec-label LABEL
           Exec Label from the sandbox. On an SELinux system you can specify the SELinux context
           for the sandbox process(s).

       --file-label LABEL
           File label for temporary sandbox content. On an SELinux system you can specify the
           SELinux context for the sandbox content.

       --block-fd FD
           Block the sandbox on reading from FD until some data is available.

       --userns-block-fd FD
           Do not initialize the user namespace but wait on FD until it is ready. This allow
           external processes (like newuidmap/newgidmap) to setup the user namespace before it is
           used by the sandbox process.

       --info-fd FD
           Write information in JSON format about the sandbox to FD.

       --json-status-fd FD
           Multiple JSON documents are written to FD, one per line ("JSON lines" format[1]). Each
           line is a single JSON object. After bwrap has started the child process inside the
           sandbox, it writes an object with a child-pid member to the --json-status-fd (this
           duplicates the older --info-fd). The corresponding value is the process ID of the
           child process in the pid namespace from which bwrap was run. If available, the
           namespace IDs are also included in the object with the child-pid; again, this
           duplicates the older --info-fd. When the child process inside the sandbox exits, bwrap
           writes an object with an exit-code member, and then closes the --json-status-fd. The
           value corresponding to exit-code is the exit status of the child, in the usual shell
           encoding (n if it exited normally with status n, or 128+n if it was killed by signal
           n). Other members may be added to those objects in future versions of bwrap, and other
           JSON objects may be added before or after the current objects, so readers must ignore
           members and objects that they do not understand.

       --new-session
           Create a new terminal session for the sandbox (calls setsid()). This disconnects the
           sandbox from the controlling terminal which means the sandbox can't for instance
           inject input into the terminal.

           Note: In a general sandbox, if you don't use --new-session, it is recommended to use
           seccomp to disallow the TIOCSTI ioctl, otherwise the application can feed keyboard
           input to the terminal.

       --die-with-parent
           Ensures child process (COMMAND) dies when bwrap's parent dies. Kills (SIGKILL) all
           bwrap sandbox processes in sequence from parent to child including COMMAND process
           when bwrap or bwrap's parent dies. See prctl, PR_SET_PDEATHSIG.

       --as-pid-1
           Do not create a process with PID=1 in the sandbox to reap child processes.

       --cap-add CAP
           Add the specified capability when running as privileged user. It accepts the special
           value ALL to add all the permitted caps.

       --cap-drop CAP
           Drop the specified capability when running as privileged user. It accepts the special
           value ALL to drop all the caps. By default no caps are left in the sandboxed process.
           The --cap-add and --cap-drop options are processed in the order they are specified on
           the command line. Please be careful to the order they are specified.

ENVIRONMENT

       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.

EXIT STATUS

       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/