Debian Codegraph @

upstream/fedora-44/man1/mkosi-sandbox.1

raw
1 .\" Automatically generated by Pandoc 3.6.4
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\[cq]t fail if the source path
69 doesn\[cq]t 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 .PP
134 If \f[B]mkosi\-sandbox\f[R] is invoked as the root user, this option
135 won\[cq]t do anything.
136 .RE
137 .TP
138 \f[B]\-\-suppress\-chown\f[R]
139 Specifying this option causes all calls to \f[B]chown()\f[R] or similar
140 system calls to become a noop in the sandbox.
141 This is primarily useful when invoking package managers in the sandbox
142 which might try to \f[B]chown()\f[R] files to different users or groups
143 which would fail unless \f[B]mkosi\-sandbox\f[R] is invoked by a
144 privileged user.
145 .TP
146 \f[B]\-\-suppress\-sync\f[R]
147 Specifying this option causes all calls to \f[B]sync()\f[R] or similar
148 system calls to become a noop in the sandbox.
149 This is primarily useful when invoking package managers in the sandbox
150 which might try to \f[B]sync()\f[R] files when extracting packages which
151 is unnecessary when building images and slows down execution time
152 significantly.
153 .TP
154 \f[B]\-\-unshare\-net\f[R]
155 Specifying this option makes \f[B]mkosi\-sandbox\f[R] unshare a network
156 namespace if possible.
157 .TP
158 \f[B]\-\-unshare\-ipc\f[R]
159 Specifying this option makes \f[B]mkosi\-sandbox\f[R] unshare an IPC
160 namespace if possible.
161 .TP
162 \f[B]\-\-suspend\f[R]
163 Make the \f[B]mkosi\-sandbox\f[R] process suspend itself with
164 \f[B]SIGSTOP\f[R] just before it calls \f[B]execve()\f[R].
165 This is useful to wait until all setup logic has completed before
166 continuing execution in the parent process invoking
167 \f[B]mkosi\-sandbox\f[R] by using \f[B]waitid()\f[R] with the
168 \f[B]WNOWAIT\f[R] AND \f[B]WSTOPPED\f[R] flags.
169 .TP
170 \f[B]\-\-pack\-fds\f[R]
171 Pack inherited file descriptors together starting at file descriptor
172 number 3 and set \f[B]$LISTEN_FDS\f[R] to the number of packed file
173 descriptors and \f[B]$LISTEN_PID\f[R] to the current process pid.
174 .TP
175 \f[B]\-\-version\f[R]
176 Show package version.
177 .TP
178 \f[B]\-\-help\f[R], \f[B]\-h\f[R]
179 Show brief usage information.
180 .SH EXAMPLES
181 Start \f[B]bash\f[R] in the current working directory in its own network
182 namespace as the current user.
183 .IP
184 .EX
185 mkosi\-sandbox \-\-bind / / \-\-same\-dir \-\-unshare\-net
186 .EE
187 .PP
188 Run \f[B]id\f[R] as the root user in a sandbox with only \f[B]/usr\f[R]
189 from the host plus the necessary symlinks to be able to run commands.
190 .IP
191 .EX
192 mkosi\-sandbox \[rs]
193 \-\-ro\-bind /usr /usr \[rs]
194 \-\-symlink usr/bin /bin \[rs]
195 \-\-symlink usr/lib /lib \[rs]
196 \-\-symlink usr/lib64 /lib64 \[rs]
197 \-\-symlink usr/sbin /sbin \[rs]
198 \-\-dev /dev \[rs]
199 \-\-proc /proc \[rs]
200 \-\-tmpfs /tmp \[rs]
201 \-\-become\-root \[rs]
202 id
203 .EE
204 .SH SEE ALSO
205 \f[B]mkosi(1)\f[R]