| 1 |
.\" Automatically generated by Pandoc 3.9.0.2 |
| 2 |
.\" |
| 3 |
.TH "mkosi\-sandbox" "1" "" "" |
| 4 |
.SH NAME |
| 5 |
mkosi\-sandbox \(em Run commands in a custom sandbox |
| 6 |
.SH SYNOPSIS |
| 7 |
\f[B]mkosi\-sandbox [options\&...] |
| 8 |
command [arguments]\f[R] |
| 9 |
.SH DESCRIPTION |
| 10 |
\f[B]mkosi\-sandbox\f[R] runs the given command in a custom sandbox. |
| 11 |
The sandbox is configured by specifying command line options that |
| 12 |
configure individual parts of the sandbox. |
| 13 |
.PP |
| 14 |
If no command is specified, \f[B]mkosi\-sandbox\f[R] will start |
| 15 |
\f[B]bash\f[R] in the sandbox. |
| 16 |
.PP |
| 17 |
Note that this sandbox is not designed to be a security boundary. |
| 18 |
Its intended purpose is to allow running commands in an isolated |
| 19 |
environment so they are not affected by the host system. |
| 20 |
.PP |
| 21 |
It is possible to use \f[B]mkosi\-sandbox\f[R] to create an in process |
| 22 |
sandbox for python applications by importing it as a module and invoking |
| 23 |
its main function with only options. |
| 24 |
No command line to execute is needed in this case. |
| 25 |
As an example: |
| 26 |
.IP |
| 27 |
.EX |
| 28 |
\f[B]import\f[R] mkosi.sandbox |
| 29 |
|
| 30 |
mkosi.sandbox.main([\(dq\-\-become\-root\(dq]) |
| 31 |
print(os.getuid()) |
| 32 |
.EE |
| 33 |
.PP |
| 34 |
Only the \f[B]main\f[R] function can be invoked. |
| 35 |
Invoking any other functions from \f[B]mkosi.sandbox\f[R] is not |
| 36 |
supported and may break in future versions. |
| 37 |
.SH OPTIONS |
| 38 |
.TP |
| 39 |
\f[B]\-\-tmpfs DST\f[R] |
| 40 |
Mounts a new tmpfs at \f[B]DST\f[R] in the sandbox. |
| 41 |
.TP |
| 42 |
\f[B]\-\-dev DST\f[R] |
| 43 |
Sets up a private \f[B]/dev\f[R] at \f[B]DST\f[R] in the sandbox. |
| 44 |
This private \f[B]/dev\f[R] will only contain the basic device nodes |
| 45 |
required for a functioning sandbox (e.g.\ \f[B]/dev/null\f[R]) and no |
| 46 |
actual devices. |
| 47 |
.TP |
| 48 |
\f[B]\-\-proc DST\f[R] |
| 49 |
Mounts \f[B]/proc\f[R] from the host at \f[B]DST\f[R] in the sandbox. |
| 50 |
.TP |
| 51 |
\f[B]\-\-dir DST\f[R] |
| 52 |
Creates a directory and all missing parent directories at \f[B]DST\f[R] |
| 53 |
in the sandbox. |
| 54 |
All directories are created with mode 755 unless the path ends with |
| 55 |
\f[B]/tmp\f[R] or \f[B]/var/tmp\f[R] in which case it is created with |
| 56 |
mode 1777. |
| 57 |
.TP |
| 58 |
\f[B]\-\-bind SRC DST\f[R] |
| 59 |
The source path \f[B]SRC\f[R] is recursively bind mounted to |
| 60 |
\f[B]DST\f[R] in the sandbox. |
| 61 |
The mountpoint is created in the sandbox if it does not yet exist. |
| 62 |
Any missing parent directories in the sandbox are created as well. |
| 63 |
The source path may optionally be prefixed with a \f[B]+\f[R] character. |
| 64 |
If so, the source path is interpreted relative to the sandbox root |
| 65 |
directory instead of the host root directory. |
| 66 |
.TP |
| 67 |
\f[B]\-\-bind\-try SRC DST\f[R] |
| 68 |
Like \f[B]\-\-bind\f[R], but doesn\(cqt fail if the source path |
| 69 |
doesn\(cqt exist. |
| 70 |
.TP |
| 71 |
\f[B]\-\-ro\-bind SRC DST\f[R] |
| 72 |
Like \f[B]\-\-bind\f[R], but does a recursive readonly bind mount. |
| 73 |
.TP |
| 74 |
\f[B]\-\-ro\-bind\-try SRC DST\f[R] |
| 75 |
Like \f[B]\-\-bind\-try\f[R], but does a recursive readonly bind mount. |
| 76 |
.TP |
| 77 |
\f[B]\-\-symlink SRC DST\f[R] |
| 78 |
Creates a symlink at \f[B]DST\f[R] in the sandbox pointing to |
| 79 |
\f[B]SRC\f[R]. |
| 80 |
If \f[B]DST\f[R] already exists and is a file or symlink, a temporary |
| 81 |
symlink is created and mounted on top of \f[B]DST\f[R]. |
| 82 |
.TP |
| 83 |
\f[B]\-\-write DATA DST\f[R] |
| 84 |
Writes the string from \f[B]DATA\f[R] to \f[B]DST\f[R] in the sandbox. |
| 85 |
.TP |
| 86 |
\f[B]\-\-overlay\-lowerdir DIR\f[R] |
| 87 |
Adds \f[B]DIR\f[R] from the host as a new lower directory for the next |
| 88 |
overlayfs mount. |
| 89 |
.TP |
| 90 |
\f[B]\-\-overlay\-upperdir DIR\f[R] |
| 91 |
Sets the upper directory for the next overlayfs mount to \f[B]DIR\f[R] |
| 92 |
from the host. |
| 93 |
If set to \f[B]tmpfs\f[R], the upperdir and workdir will be |
| 94 |
subdirectories of a fresh tmpfs mount. |
| 95 |
.TP |
| 96 |
\f[B]\-\-overlay\-workdir DIR\f[R] |
| 97 |
Sets the working directory for the next overlayfs mount to \f[B]DIR\f[R] |
| 98 |
from the host. |
| 99 |
.TP |
| 100 |
\f[B]\-\-overlay DST\f[R] |
| 101 |
Mounts a new overlay filesystem at \f[B]DST\f[R] in the sandbox. |
| 102 |
The lower directories, upper directory and working directory are |
| 103 |
specified using the \f[B]\-\-overlay\-lowerdir\f[R], |
| 104 |
\f[B]\-\-overlay\-upperdir\f[R] and \f[B]\-\-overlay\-workdir\f[R] |
| 105 |
options respectively. |
| 106 |
After each \f[B]\-\-overlay\f[R] option is parsed, the other overlay |
| 107 |
options are reset. |
| 108 |
.TP |
| 109 |
\f[B]\-\-unsetenv NAME\f[R] |
| 110 |
Unsets the \f[B]NAME\f[R] environment variable in the sandbox. |
| 111 |
.TP |
| 112 |
\f[B]\-\-setenv NAME VALUE\f[R] |
| 113 |
Sets the \f[B]NAME\f[R] environment variable to \f[B]VALUE\f[R] in the |
| 114 |
sandbox |
| 115 |
.TP |
| 116 |
\f[B]\-\-chdir DIR\f[R] |
| 117 |
Changes the working directory to \f[B]DIR\f[R] in the sandbox. |
| 118 |
.TP |
| 119 |
\f[B]\-\-same\-dir\f[R] |
| 120 |
Changes to the working directory in the sandbox to the current working |
| 121 |
directory that \f[B]mkosi\-sandbox\f[R] is invoked in on the host. |
| 122 |
.TP |
| 123 |
\f[B]\-\-become\-root\f[R] |
| 124 |
Maps the current user to the root user in the sandbox. |
| 125 |
If this option is not specified, the current user is mapped to itself in |
| 126 |
the sandbox. |
| 127 |
Regardless of whether this option is specified or not, the current user |
| 128 |
will have a full set of ambient capabilities in the sandbox. |
| 129 |
This includes \f[B]CAP_SYS_ADMIN\f[R] which means that the invoked |
| 130 |
process in the sandbox will be able to do bind mounts and other |
| 131 |
operations. |
| 132 |
.RS |
| 133 |
If \f[B]mkosi\-sandbox\f[R] is invoked as the root user, this option |
| 134 |
won\(cqt do anything. |
| 135 |
.RE |
| 136 |
.TP |
| 137 |
\f[B]\-\-suppress\-chown\f[R] |
| 138 |
Specifying this option causes all calls to \f[B]chown()\f[R] or similar |
| 139 |
system calls to become a noop in the sandbox. |
| 140 |
This is primarily useful when invoking package managers in the sandbox |
| 141 |
which might try to \f[B]chown()\f[R] files to different users or groups |
| 142 |
which would fail unless \f[B]mkosi\-sandbox\f[R] is invoked by a |
| 143 |
privileged user. |
| 144 |
.TP |
| 145 |
\f[B]\-\-suppress\-sync\f[R] |
| 146 |
Specifying this option causes all calls to \f[B]sync()\f[R] or similar |
| 147 |
system calls to become a noop in the sandbox. |
| 148 |
This is primarily useful when invoking package managers in the sandbox |
| 149 |
which might try to \f[B]sync()\f[R] files when extracting packages which |
| 150 |
is unnecessary when building images and slows down execution time |
| 151 |
significantly. |
| 152 |
.TP |
| 153 |
\f[B]\-\-unshare\-net\f[R] |
| 154 |
Specifying this option makes \f[B]mkosi\-sandbox\f[R] unshare a network |
| 155 |
namespace if possible. |
| 156 |
.TP |
| 157 |
\f[B]\-\-unshare\-ipc\f[R] |
| 158 |
Specifying this option makes \f[B]mkosi\-sandbox\f[R] unshare an IPC |
| 159 |
namespace if possible. |
| 160 |
.TP |
| 161 |
\f[B]\-\-suspend\f[R] |
| 162 |
Make the \f[B]mkosi\-sandbox\f[R] process suspend itself with |
| 163 |
\f[B]SIGSTOP\f[R] just before it calls \f[B]execve()\f[R]. |
| 164 |
This is useful to wait until all setup logic has completed before |
| 165 |
continuing execution in the parent process invoking |
| 166 |
\f[B]mkosi\-sandbox\f[R] by using \f[B]waitid()\f[R] with the |
| 167 |
\f[B]WNOWAIT\f[R] AND \f[B]WSTOPPED\f[R] flags. |
| 168 |
.TP |
| 169 |
\f[B]\-\-pack\-fds\f[R] |
| 170 |
Pack inherited file descriptors together starting at file descriptor |
| 171 |
number 3 and set \f[B]$LISTEN_FDS\f[R] to the number of packed file |
| 172 |
descriptors and \f[B]$LISTEN_PID\f[R] to the current process pid. |
| 173 |
.TP |
| 174 |
\f[B]\-\-version\f[R] |
| 175 |
Show package version. |
| 176 |
.TP |
| 177 |
\f[B]\-\-help\f[R], \f[B]\-h\f[R] |
| 178 |
Show brief usage information. |
| 179 |
.SH EXAMPLES |
| 180 |
Start \f[B]bash\f[R] in the current working directory in its own network |
| 181 |
namespace as the current user. |
| 182 |
.IP |
| 183 |
.EX |
| 184 |
mkosi\-sandbox \-\-bind / / \-\-same\-dir \-\-unshare\-net |
| 185 |
.EE |
| 186 |
.PP |
| 187 |
Run \f[B]id\f[R] as the root user in a sandbox with only \f[B]/usr\f[R] |
| 188 |
from the host plus the necessary symlinks to be able to run commands. |
| 189 |
.IP |
| 190 |
.EX |
| 191 |
mkosi\-sandbox \(rs |
| 192 |
\-\-ro\-bind /usr /usr \(rs |
| 193 |
\-\-symlink usr/bin /bin \(rs |
| 194 |
\-\-symlink usr/lib /lib \(rs |
| 195 |
\-\-symlink usr/lib64 /lib64 \(rs |
| 196 |
\-\-symlink usr/sbin /sbin \(rs |
| 197 |
\-\-dev /dev \(rs |
| 198 |
\-\-proc /proc \(rs |
| 199 |
\-\-tmpfs /tmp \(rs |
| 200 |
\-\-become\-root \(rs |
| 201 |
id |
| 202 |
.EE |
| 203 |
.SH SEE ALSO |
| 204 |
\f[B]mkosi(1)\f[R] |