Debian Codegraph @

upstream/debian-unstable/man8/systemd-sysinstall.8

raw
1 '\" t
2 .TH "SYSTEMD\-SYSINSTALL" "8" "" "systemd 261~rc3" "systemd-sysinstall"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-sysinstall, systemd-sysinstall.service \- Simple OS installer
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-sysinstall\fR\ 'u
26 \fBsystemd\-sysinstall\fR [OPTIONS...] [BLOCKDEVICE]
27 .PP
28 systemd\-sysinstall\&.service
29 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-sysinstall\fR
32 is a simple terminal and command line based operating system installer tool\&. Its primary use\-case is to act as an automatically started interactive interface when booting from an installer medium (e\&.g\&. a USB stick), in order to install an OS onto a target disk\&. However, it may also be invoked directly from a shell\&. It executes the following steps:
33 .sp
34 .RS 4
35 .ie n \{\
36 \h'-04' 1.\h'+01'\c
37 .\}
38 .el \{\
39 .sp -1
40 .IP " 1." 4.2
41 .\}
42 It prompts the user for the target disk to install the OS on\&. (Unless the block device is already specified on the command line\&.)
43 .RE
44 .sp
45 .RS 4
46 .ie n \{\
47 \h'-04' 2.\h'+01'\c
48 .\}
49 .el \{\
50 .sp -1
51 .IP " 2." 4.2
52 .\}
53 It validates whether the disk is suitable (i\&.e\&. large enough, and with enough free/unpartitioned space) for an OS installation\&. If it is generally suitable the user is prompted if they want to erase the disk before installation, or if the OS shall be added to the existing partitions on the disk (the latter only if enough free/unpartitioned disk space is available)\&.
54 .RE
55 .sp
56 .RS 4
57 .ie n \{\
58 \h'-04' 3.\h'+01'\c
59 .\}
60 .el \{\
61 .sp -1
62 .IP " 3." 4.2
63 .\}
64 It prompts the user whether to register the newly installed OS with the firmware boot option menu\&.
65 .RE
66 .sp
67 .RS 4
68 .ie n \{\
69 \h'-04' 4.\h'+01'\c
70 .\}
71 .el \{\
72 .sp -1
73 .IP " 4." 4.2
74 .\}
75 It requests confirmation from the user, after showing a summary of the planned OS installation\&.
76 .RE
77 .sp
78 .RS 4
79 .ie n \{\
80 \h'-04' 5.\h'+01'\c
81 .\}
82 .el \{\
83 .sp -1
84 .IP " 5." 4.2
85 .\}
86 It invokes
87 \fBsystemd-creds\fR(1)\*(Aqs
88 \fBencrypt\fR
89 command in order to generate encrypted (TPM locked, if available) system credential files for a few, very basic system settings of the currently booted system (locale, keymap, timezone), which it will install on the target disk, parameterizing the invoked kernel\&. (Or in other words, it prepares that some settings already in effect on the installer system are propagated securely onto the new installation\&.)
90 .RE
91 .sp
92 .RS 4
93 .ie n \{\
94 \h'-04' 6.\h'+01'\c
95 .\}
96 .el \{\
97 .sp -1
98 .IP " 6." 4.2
99 .\}
100 It invokes
101 \fBsystemd-repart\fR(8)
102 with a definitions directory of
103 /usr/lib/repart\&.sysinstall\&.d/
104 (only if populated \(en if not will use the default of
105 /usr/lib/repart\&.d/)\&. This is supposed to set up the basic OS partition structure on the target disk and copies in basic OS partitions (most importantly the
106 /usr/
107 hierarchy)\&.
108 .RE
109 .sp
110 .RS 4
111 .ie n \{\
112 \h'-04' 7.\h'+01'\c
113 .\}
114 .el \{\
115 .sp -1
116 .IP " 7." 4.2
117 .\}
118 It invokes
119 \fBbootctl\fR(1)\*(Aqs
120 \fBlink\fR
121 command to install an OS kernel image onto the target disk\*(Aqs ESP/XBOOTLDR, together with the credential files prepared earlier\&.
122 .RE
123 .sp
124 .RS 4
125 .ie n \{\
126 \h'-04' 8.\h'+01'\c
127 .\}
128 .el \{\
129 .sp -1
130 .IP " 8." 4.2
131 .\}
132 It invokes
133 \fBbootctl\fR(1)\*(Aqs
134 \fBinstall\fR
135 command to install the
136 \fBsystemd-boot\fR(7)
137 boot loader onto the target disk\*(Aqs ESP\&.
138 .RE
139 .sp
140 .RS 4
141 .ie n \{\
142 \h'-04' 9.\h'+01'\c
143 .\}
144 .el \{\
145 .sp -1
146 .IP " 9." 4.2
147 .\}
148 After confirmation, it reboots the system\&.
149 .RE
150 .PP
151 Note that the prompts/confirmation may be disabled via the command line, enabling fully automatic, non\-interactive installation\&. See below\&.
152 .PP
153 Note this tool does not interactively query the user for a user to create or a root password to be set on the target system, under the assumption these questions are better prompted from within the newly installed system\*(Aqs first boot process, for example via the
154 \fBsystemd-firstboot\fR(1)
155 or
156 systemd\-homed\-firstboot\&.service
157 components\&. Note that if required such settings may be propagated explicitly via the
158 \fB\-\-load\-credential=\fR
159 switch below\&.
160 .SH "OPTIONS"
161 .PP
162 The following options are understood:
163 .PP
164 \fB\-\-definitions=\fR
165 .RS 4
166 Overrides the directory where
167 \fBsystemd\-repart\fR
168 shall read its partition definitions from, in place of the default of
169 /usr/lib/repart\&.sysinstall\&.d/\&.
170 .sp
171 Added in version 261\&.
172 .RE
173 .PP
174 \fB\-\-welcome=\fR
175 .RS 4
176 Takes a boolean argument\&. Controls whether to show the brief welcome text normally displayed at the beginning of the installation\&. Defaults to true\&.
177 .sp
178 Added in version 261\&.
179 .RE
180 .PP
181 \fB\-\-chrome=\fR
182 .RS 4
183 Takes a boolean argument\&. Controls whether to show the colored bars at the top and bottom of the terminal interface\&. Defaults to true\&.
184 .sp
185 Added in version 261\&.
186 .RE
187 .PP
188 \fB\-\-erase=\fR
189 .RS 4
190 Takes a boolean argument\&. Controls whether to erase the current contents of the target disk\&. If this switch is not used the user is prompted\&.
191 .sp
192 Added in version 261\&.
193 .RE
194 .PP
195 \fB\-\-confirm=\fR
196 .RS 4
197 Takes a boolean argument\&. Controls whether to interactively query the user for confirmation before initiating the OS installation\&. Defaults to true\&.
198 .sp
199 Added in version 261\&.
200 .RE
201 .PP
202 \fB\-\-reboot=\fR
203 .RS 4
204 Takes a boolean argument\&. Controls whether to reboot the system after completing the installation\&. Defaults to false\&.
205 .sp
206 Added in version 261\&.
207 .RE
208 .PP
209 \fB\-\-variables=\fR
210 .RS 4
211 Takes a boolean argument\&. Controls whether to register the installed boot loader in the firmware\*(Aqs boot options database\&. If not specified the user will be prompted\&.
212 .sp
213 Added in version 261\&.
214 .RE
215 .PP
216 \fB\-\-summary=\fR
217 .RS 4
218 Takes a boolean argument\&. Controls whether to show a summary of the choices made before asking for confirmation to proceed with the OS installation\&. Defaults to true\&.
219 .sp
220 Added in version 261\&.
221 .RE
222 .PP
223 \fB\-\-kernel=\fR
224 .RS 4
225 Takes a path to a unified kernel image (UKI)\&. Explicitly selects the kernel image to install on the target disk\&. If unspecified the currently booted kernel image is installed on the target disk\&.
226 .sp
227 Added in version 261\&.
228 .RE
229 .PP
230 \fB\-\-set\-credential=\fR\fB\fIid\fR\fR\fB:\fR\fB\fIvalue\fR\fR
231 .RS 4
232 Accepts an additional system credential to encrypt (with a key generated on the local TPM, if available, and the null key otherwise) and place next to the installed kernel image in the ESP\&. This may be used to parameterize the installed kernel with arbitrary system credentials\&. Do not use this switch for sensitive data (such as passwords), use
233 \fB\-\-load\-credential=\fR
234 instead, see below\&. May be used multiple times to configure multiple credentials\&.
235 .sp
236 Note that three system credentials are propagated in similar fashion to the target system: the locale, keymap and timezone\&. This may be controlled by the relevant
237 \fB\-\-copy\-locale=\fR,
238 \fB\-\-copy\-keymap=\fR
239 and
240 \fB\-\-copy\-timezone=\fR
241 options below\&.
242 .sp
243 See
244 \fBsystemd.system-credentials\fR(7)
245 for a list of well\-known system credentials that may be propagated this way\&. (Note that you may pass arbitrary additional credentials this way, that can be consumed by any service of your choice, via the usual system credentials logic\&.)
246 .sp
247 Added in version 261\&.
248 .RE
249 .PP
250 \fB\-\-load\-credential=\fR\fB\fIid\fR\fR\fB:\fR\fB\fIpath\fR\fR
251 .RS 4
252 Similar to
253 \fB\-\-set\-credential=\fR
254 but reads the credential value from a file on disk or an
255 \fBAF_UNIX\fR
256 socket in the file system\&. This is generally preferable for sensitive data, such as passwords\&.
257 .sp
258 Added in version 261\&.
259 .RE
260 .PP
261 \fB\-\-copy\-locale=\fR, \fB\-\-copy\-keymap=\fR, \fB\-\-copy\-timezone=\fR
262 .RS 4
263 These options take boolean parameters\&. They control whether the indicated system settings shall be propagated from the currently running system into the new target OS installation\&. These options default to true\&.
264 .sp
265 Typically, these three settings are the minimal settings that need to be configured during early boot of an installer medium in order to make the installer tool accessible to the user\&. The
266 \fBsystemd-firstboot\fR(1)
267 tool may be used to query the user interactively when the OS install medium is booted for these properties\&. By propagating these settings to the target installation via system credentials they do not need to be queried again on first boot of the new installation\&.
268 .sp
269 Added in version 261\&.
270 .RE
271 .PP
272 \fB\-\-mute\-console=\fR
273 .RS 4
274 Takes a boolean argument\&. Controls whether to disable kernel and service manager log output to the console the installer is invoked on temporarily while running, in order to avoid interleaved output\&. Defaults to false\&.
275 .sp
276 Added in version 261\&.
277 .RE
278 .PP
279 \fB\-h\fR, \fB\-\-help\fR
280 .RS 4
281 Print a short help text and exit\&.
282 .RE
283 .PP
284 \fB\-\-version\fR
285 .RS 4
286 Print a short version string and exit\&.
287 .RE
288 .SH "EXIT STATUS"
289 .PP
290 On success, 0 is returned, and a non\-zero failure code otherwise\&.
291 .SH "EXAMPLE"
292 .PP
293 \fBExample\ \&1.\ \&Invoke the tool for a fully automatic non\-interactive OS installation\fR
294 .sp
295 .if n \{\
296 .RS 4
297 .\}
298 .nf
299 systemd\-sysinstall \e
300 /dev/disk/by\-id/nvme\-Micron_MTFDKBA1T0TFH_214532D0CDA5 \e
301 \-\-erase=yes \e
302 \-\-confirm=no \e
303 \-\-variables=yes \e
304 \-\-load\-credential=ssh\&.authorized_keys\&.root:my\-ssh\-key
305
306 .fi
307 .if n \{\
308 .RE
309 .\}
310 .PP
311 This installs the OS on the selected disk, erasing any previous contents, without confirmation, registers it in the firmware, and drops in the SSH key for the root user, read from the
312 my\-ssh\-key
313 file in the current directory\&.
314 .SH "SEE ALSO"
315 .PP
316 \fBsystemd\fR(1), \fBsystemd-creds\fR(1), \fBsystemd-repart\fR(8), \fBbootctl\fR(1), \fBsystemd-firstboot\fR(1), \fBsystemd-boot\fR(7), \fBsystemd.system-credentials\fR(7)