Debian Codegraph @

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

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