.\" Automatically generated by Pandoc 3.1.12.1
.\"
.TH "mkosi\-sandbox" "1" "" "" ""
.SH NAME
mkosi\-sandbox \[em] Run commands in a custom sandbox
.SH SYNOPSIS
\f[CR]mkosi\-sandbox [options\&...] command [arguments]\f[R]
.SH DESCRIPTION
\f[CR]mkosi\-sandbox\f[R] runs the given command in a custom sandbox.
The sandbox is configured by specifying command line options that
configure individual parts of the sandbox.
.PP
If no command is specified, \f[CR]mkosi\-sandbox\f[R] will start
\f[CR]bash\f[R] in the sandbox.
.PP
Note that this sandbox is not designed to be a security boundary.
Its intended purpose is to allow running commands in an isolated
environment so they are not affected by the host system.
.SH OPTIONS
.TP
\f[CR]\-\-tmpfs DST\f[R]
Mounts a new tmpfs at \f[CR]DST\f[R] in the sandbox.
.TP
\f[CR]\-\-dev DST\f[R]
Sets up a private \f[CR]/dev\f[R] at \f[CR]DST\f[R] in the sandbox.
This private \f[CR]/dev\f[R] will only contain the basic device nodes
required for a functioning sandbox (e.g.\ \f[CR]/dev/null\f[R]) and no
actual devices.
.TP
\f[CR]\-\-proc DST\f[R]
Mounts \f[CR]/proc\f[R] from the host at \f[CR]DST\f[R] in the sandbox.
.TP
\f[CR]\-\-dir DST\f[R]
Creates a directory and all missing parent directories at \f[CR]DST\f[R]
in the sandbox.
All directories are created with mode 755 unless the path ends with
\f[CR]/tmp\f[R] or \f[CR]/var/tmp\f[R] in which case it is created with
mode 1777.
.TP
\f[CR]\-\-bind SRC DST\f[R]
The source path \f[CR]SRC\f[R] is recursively bind mounted to
\f[CR]DST\f[R] in the sandbox.
The mountpoint is created in the sandbox if it does not yet exist.
Any missing parent directories in the sandbox are created as well.
.TP
\f[CR]\-\-bind\-try SRC DST\f[R]
Like \f[CR]\-\-bind\f[R], but doesn\[cq]t fail if the source path
doesn\[cq]t exist.
.TP
\f[CR]\-\-ro\-bind SRC DST\f[R]
Like \f[CR]\-\-bind\f[R], but does a recursive readonly bind mount.
.TP
\f[CR]\-\-ro\-bind\-try SRC DST\f[R]
Like \f[CR]\-\-bind\-try\f[R], but does a recursive readonly bind mount.
.TP
\f[CR]\-\-symlink SRC DST\f[R]
Creates a symlink at \f[CR]DST\f[R] in the sandbox pointing to
\f[CR]SRC\f[R].
If \f[CR]DST\f[R] already exists and is a file or symlink, a temporary
symlink is created and mounted on top of \f[CR]DST\f[R].
.TP
\f[CR]\-\-write DATA DST\f[R]
Writes the string from \f[CR]DATA\f[R] to \f[CR]DST\f[R] in the sandbox.
.TP
\f[CR]\-\-overlay\-lowerdir DIR\f[R]
Adds \f[CR]DIR\f[R] from the host as a new lower directory for the next
overlayfs mount.
.TP
\f[CR]\-\-overlay\-upperdir DIR\f[R]
Sets the upper directory for the next overlayfs mount to \f[CR]DIR\f[R]
from the host.
If set to \f[CR]tmpfs\f[R], the upperdir and workdir will be
subdirectories of a fresh tmpfs mount.
.TP
\f[CR]\-\-overlay\-workdir DIR\f[R]
Sets the working directory for the next overlayfs mount to
\f[CR]DIR\f[R] from the host.
.TP
\f[CR]\-\-overlay DST\f[R]
Mounts a new overlay filesystem at \f[CR]DST\f[R] in the sandbox.
The lower directories, upper directory and working directory are
specified using the \f[CR]\-\-overlay\-lowerdir\f[R],
\f[CR]\-\-overlay\-upperdir\f[R] and \f[CR]\-\-overlay\-workdir\f[R]
options respectively.
After each \f[CR]\-\-overlay\f[R] option is parsed, the other overlay
options are reset.
.TP
\f[CR]\-\-unsetenv NAME\f[R]
Unsets the \f[CR]NAME\f[R] environment variable in the sandbox.
.TP
\f[CR]\-\-setenv NAME VALUE\f[R]
Sets the \f[CR]NAME\f[R] environment variable to \f[CR]VALUE\f[R] in the
sandbox
.TP
\f[CR]\-\-chdir DIR\f[R]
Changes the working directory to \f[CR]DIR\f[R] in the sandbox.
.TP
\f[CR]\-\-same\-dir\f[R]
Changes to the working directory in the sandbox to the current working
directory that \f[CR]mkosi\-sandbox\f[R] is invoked in on the host.
.TP
\f[CR]\-\-become\-root\f[R]
Maps the current user to the root user in the sandbox.
If this option is not specified, the current user is mapped to itself in
the sandbox.
Regardless of whether this option is specified or not, the current user
will have a full set of ambient capabilities in the sandbox.
This includes \f[CR]CAP_SYS_ADMIN\f[R] which means that the invoked
process in the sandbox will be able to do bind mounts and other
operations.
.RS
.PP
If \f[CR]mkosi\-sandbox\f[R] is invoked as the root user, this option
won\[cq]t do anything.
.RE
.TP
\f[CR]\-\-suppress\-chown\f[R]
Specifying this option causes all calls to \f[CR]chown()\f[R] or similar
system calls to become a noop in the sandbox.
This is primarily useful when invoking package managers in the sandbox
which might try to \f[CR]chown()\f[R] files to different users or groups
which would fail unless \f[CR]mkosi\-sandbox\f[R] is invoked by a
privileged user.
.TP
\f[CR]\-\-unshare\-net\f[R]
Specifying this option makes \f[CR]mkosi\-sandbox\f[R] unshare a network
namespace if possible.
.TP
\f[CR]\-\-unshare\-ipc\f[R]
Specifying this option makes \f[CR]mkosi\-sandbox\f[R] unshare an IPC
namespace if possible.
.TP
\f[CR]\-\-exec\-fd FD\f[R]
The specified \f[CR]FD\f[R] will be closed when
\f[CR]mkosi\-sandbox\f[R] calls \f[CR]execvp()\f[R].
This is useful to wait until all setup logic has completed before
continuing execution in the parent process invoking
\f[CR]mkosi\-sandbox\f[R].
.TP
\f[CR]\-\-version\f[R]
Show package version.
.TP
\f[CR]\-\-help\f[R], \f[CR]\-h\f[R]
Show brief usage information.
.SH EXAMPLES
Start \f[CR]bash\f[R] in the current working directory in its own
network namespace as the current user.
.IP
.EX
mkosi\-sandbox \-\-bind / / \-\-same\-dir \-\-unshare\-net
.EE
.PP
Run \f[CR]id\f[R] as the root user in a sandbox with only
\f[CR]/usr\f[R] from the host plus the necessary symlinks to be able to
run commands.
.IP
.EX
mkosi\-sandbox \[rs]
    \-\-ro\-bind /usr /usr \[rs]
    \-\-symlink usr/bin /bin \[rs]
    \-\-symlink usr/bin /bin \[rs]
    \-\-symlink usr/lib /lib \[rs]
    \-\-symlink usr/lib64 /lib64 \[rs]
    \-\-symlink usr/sbin /sbin \[rs]
    \-\-dev /dev \[rs]
    \-\-proc /proc \[rs]
    \-\-tmpfs /tmp \[rs]
    \-\-become\-root \[rs]
    id
.EE
.SH SEE ALSO
\f[CR]mkosi(1)\f[R]