Debian Codegraph @

upstream/debian-unstable/man1/mkosi-sandbox.1

raw
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]