| 1 |
.\" Automatically generated by Pandoc 3.1.11.1 |
| 2 |
.\" |
| 3 |
.TH "mkosi\-sandbox" "1" "" "" "" |
| 4 |
.SH NAME |
| 5 |
mkosi\-sandbox \[em] Run commands in a custom sandbox |
| 6 |
.SH SYNOPSIS |
| 7 |
\f[CR]mkosi\-sandbox [options\&...] command [arguments]\f[R] |
| 8 |
.SH DESCRIPTION |
| 9 |
\f[CR]mkosi\-sandbox\f[R] runs the given command in a custom sandbox. |
| 10 |
The sandbox is configured by specifying command line options that |
| 11 |
configure individual parts of the sandbox. |
| 12 |
.PP |
| 13 |
If no command is specified, \f[CR]mkosi\-sandbox\f[R] will start |
| 14 |
\f[CR]bash\f[R] in the sandbox. |
| 15 |
.PP |
| 16 |
Note that this sandbox is not designed to be a security boundary. |
| 17 |
Its intended purpose is to allow running commands in an isolated |
| 18 |
environment so they are not affected by the host system. |
| 19 |
.SH OPTIONS |
| 20 |
.TP |
| 21 |
\f[CR]\-\-tmpfs DST\f[R] |
| 22 |
Mounts a new tmpfs at \f[CR]DST\f[R] in the sandbox. |
| 23 |
.TP |
| 24 |
\f[CR]\-\-dev DST\f[R] |
| 25 |
Sets up a private \f[CR]/dev\f[R] at \f[CR]DST\f[R] in the sandbox. |
| 26 |
This private \f[CR]/dev\f[R] will only contain the basic device nodes |
| 27 |
required for a functioning sandbox (e.g.\ \f[CR]/dev/null\f[R]) and no |
| 28 |
actual devices. |
| 29 |
.TP |
| 30 |
\f[CR]\-\-proc DST\f[R] |
| 31 |
Mounts \f[CR]/proc\f[R] from the host at \f[CR]DST\f[R] in the sandbox. |
| 32 |
.TP |
| 33 |
\f[CR]\-\-dir DST\f[R] |
| 34 |
Creates a directory and all missing parent directories at \f[CR]DST\f[R] |
| 35 |
in the sandbox. |
| 36 |
All directories are created with mode 755 unless the path ends with |
| 37 |
\f[CR]/tmp\f[R] or \f[CR]/var/tmp\f[R] in which case it is created with |
| 38 |
mode 1777. |
| 39 |
.TP |
| 40 |
\f[CR]\-\-bind SRC DST\f[R] |
| 41 |
The source path \f[CR]SRC\f[R] is recursively bind mounted to |
| 42 |
\f[CR]DST\f[R] in the sandbox. |
| 43 |
The mountpoint is created in the sandbox if it does not yet exist. |
| 44 |
Any missing parent directories in the sandbox are created as well. |
| 45 |
.TP |
| 46 |
\f[CR]\-\-bind\-try SRC DST\f[R] |
| 47 |
Like \f[CR]\-\-bind\f[R], but doesn\[cq]t fail if the source path |
| 48 |
doesn\[cq]t exist. |
| 49 |
.TP |
| 50 |
\f[CR]\-\-ro\-bind SRC DST\f[R] |
| 51 |
Like \f[CR]\-\-bind\f[R], but does a recursive readonly bind mount. |
| 52 |
.TP |
| 53 |
\f[CR]\-\-ro\-bind\-try SRC DST\f[R] |
| 54 |
Like \f[CR]\-\-bind\-try\f[R], but does a recursive readonly bind mount. |
| 55 |
.TP |
| 56 |
\f[CR]\-\-symlink SRC DST\f[R] |
| 57 |
Creates a symlink at \f[CR]DST\f[R] in the sandbox pointing to |
| 58 |
\f[CR]SRC\f[R]. |
| 59 |
If \f[CR]DST\f[R] already exists and is a file or symlink, a temporary |
| 60 |
symlink is created and mounted on top of \f[CR]DST\f[R]. |
| 61 |
.TP |
| 62 |
\f[CR]\-\-write DATA DST\f[R] |
| 63 |
Writes the string from \f[CR]DATA\f[R] to \f[CR]DST\f[R] in the sandbox. |
| 64 |
.TP |
| 65 |
\f[CR]\-\-overlay\-lowerdir DIR\f[R] |
| 66 |
Adds \f[CR]DIR\f[R] from the host as a new lower directory for the next |
| 67 |
overlayfs mount. |
| 68 |
.TP |
| 69 |
\f[CR]\-\-overlay\-upperdir DIR\f[R] |
| 70 |
Sets the upper directory for the next overlayfs mount to \f[CR]DIR\f[R] |
| 71 |
from the host. |
| 72 |
If set to \f[CR]tmpfs\f[R], the upperdir and workdir will be |
| 73 |
subdirectories of a fresh tmpfs mount. |
| 74 |
.TP |
| 75 |
\f[CR]\-\-overlay\-workdir DIR\f[R] |
| 76 |
Sets the working directory for the next overlayfs mount to |
| 77 |
\f[CR]DIR\f[R] from the host. |
| 78 |
.TP |
| 79 |
\f[CR]\-\-overlay DST\f[R] |
| 80 |
Mounts a new overlay filesystem at \f[CR]DST\f[R] in the sandbox. |
| 81 |
The lower directories, upper directory and working directory are |
| 82 |
specified using the \f[CR]\-\-overlay\-lowerdir\f[R], |
| 83 |
\f[CR]\-\-overlay\-upperdir\f[R] and \f[CR]\-\-overlay\-workdir\f[R] |
| 84 |
options respectively. |
| 85 |
After each \f[CR]\-\-overlay\f[R] option is parsed, the other overlay |
| 86 |
options are reset. |
| 87 |
.TP |
| 88 |
\f[CR]\-\-unsetenv NAME\f[R] |
| 89 |
Unsets the \f[CR]NAME\f[R] environment variable in the sandbox. |
| 90 |
.TP |
| 91 |
\f[CR]\-\-setenv NAME VALUE\f[R] |
| 92 |
Sets the \f[CR]NAME\f[R] environment variable to \f[CR]VALUE\f[R] in the |
| 93 |
sandbox |
| 94 |
.TP |
| 95 |
\f[CR]\-\-chdir DIR\f[R] |
| 96 |
Changes the working directory to \f[CR]DIR\f[R] in the sandbox. |
| 97 |
.TP |
| 98 |
\f[CR]\-\-same\-dir\f[R] |
| 99 |
Changes to the working directory in the sandbox to the current working |
| 100 |
directory that \f[CR]mkosi\-sandbox\f[R] is invoked in on the host. |
| 101 |
.TP |
| 102 |
\f[CR]\-\-become\-root\f[R] |
| 103 |
Maps the current user to the root user in the sandbox. |
| 104 |
If this option is not specified, the current user is mapped to itself in |
| 105 |
the sandbox. |
| 106 |
Regardless of whether this option is specified or not, the current user |
| 107 |
will have a full set of ambient capabilities in the sandbox. |
| 108 |
This includes \f[CR]CAP_SYS_ADMIN\f[R] which means that the invoked |
| 109 |
process in the sandbox will be able to do bind mounts and other |
| 110 |
operations. |
| 111 |
.RS |
| 112 |
.PP |
| 113 |
If \f[CR]mkosi\-sandbox\f[R] is invoked as the root user, this option |
| 114 |
won\[cq]t do anything. |
| 115 |
.RE |
| 116 |
.TP |
| 117 |
\f[CR]\-\-suppress\-chown\f[R] |
| 118 |
Specifying this option causes all calls to \f[CR]chown()\f[R] or similar |
| 119 |
system calls to become a noop in the sandbox. |
| 120 |
This is primarily useful when invoking package managers in the sandbox |
| 121 |
which might try to \f[CR]chown()\f[R] files to different users or groups |
| 122 |
which would fail unless \f[CR]mkosi\-sandbox\f[R] is invoked by a |
| 123 |
privileged user. |
| 124 |
.TP |
| 125 |
\f[CR]\-\-unshare\-net\f[R] |
| 126 |
Specifying this option makes \f[CR]mkosi\-sandbox\f[R] unshare a network |
| 127 |
namespace if possible. |
| 128 |
.TP |
| 129 |
\f[CR]\-\-unshare\-ipc\f[R] |
| 130 |
Specifying this option makes \f[CR]mkosi\-sandbox\f[R] unshare an IPC |
| 131 |
namespace if possible. |
| 132 |
.TP |
| 133 |
\f[CR]\-\-exec\-fd FD\f[R] |
| 134 |
The specified \f[CR]FD\f[R] will be closed when |
| 135 |
\f[CR]mkosi\-sandbox\f[R] calls \f[CR]execvp()\f[R]. |
| 136 |
This is useful to wait until all setup logic has completed before |
| 137 |
continuing execution in the parent process invoking |
| 138 |
\f[CR]mkosi\-sandbox\f[R]. |
| 139 |
.TP |
| 140 |
\f[CR]\-\-version\f[R] |
| 141 |
Show package version. |
| 142 |
.TP |
| 143 |
\f[CR]\-\-help\f[R], \f[CR]\-h\f[R] |
| 144 |
Show brief usage information. |
| 145 |
.SH EXAMPLES |
| 146 |
Start \f[CR]bash\f[R] in the current working directory in its own |
| 147 |
network namespace as the current user. |
| 148 |
.IP |
| 149 |
.EX |
| 150 |
mkosi\-sandbox \-\-bind / / \-\-same\-dir \-\-unshare\-net |
| 151 |
.EE |
| 152 |
.PP |
| 153 |
Run \f[CR]id\f[R] as the root user in a sandbox with only |
| 154 |
\f[CR]/usr\f[R] from the host plus the necessary symlinks to be able to |
| 155 |
run commands. |
| 156 |
.IP |
| 157 |
.EX |
| 158 |
mkosi\-sandbox \[rs] |
| 159 |
\-\-ro\-bind /usr /usr \[rs] |
| 160 |
\-\-symlink usr/bin /bin \[rs] |
| 161 |
\-\-symlink usr/bin /bin \[rs] |
| 162 |
\-\-symlink usr/lib /lib \[rs] |
| 163 |
\-\-symlink usr/lib64 /lib64 \[rs] |
| 164 |
\-\-symlink usr/sbin /sbin \[rs] |
| 165 |
\-\-dev /dev \[rs] |
| 166 |
\-\-proc /proc \[rs] |
| 167 |
\-\-tmpfs /tmp \[rs] |
| 168 |
\-\-become\-root \[rs] |
| 169 |
id |
| 170 |
.EE |
| 171 |
.SH SEE ALSO |
| 172 |
\f[CR]mkosi(1)\f[R] |