]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/bootup.xml
man: standarize on one-line license header
[thirdparty/systemd.git] / man / bootup.xml
CommitLineData
013d8a39
LP
1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
0307f791 4<!-- SPDX-License-Identifier: LGPL-2.1+ -->
013d8a39
LP
5
6<refentry id="bootup">
7
798d3a52
ZJS
8 <refentryinfo>
9 <title>bootup</title>
10 <productname>systemd</productname>
798d3a52
ZJS
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>bootup</refentrytitle>
15 <manvolnum>7</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>bootup</refname>
20 <refpurpose>System bootup process</refpurpose>
21 </refnamediv>
22
23 <refsect1>
24 <title>Description</title>
25
26 <para>A number of different components are involved in the system
27 boot. Immediately after power-up, the system BIOS will do minimal
28 hardware initialization, and hand control over to a boot loader
29 stored on a persistent storage device. This boot loader will then
30 invoke an OS kernel from disk (or the network). In the Linux case,
31 this kernel (optionally) extracts and executes an initial RAM disk
32 image (initrd), such as generated by
33 <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
34 which looks for the root file system (possibly using
35 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
36 for this). After the root file system is found and mounted, the
37 initrd hands over control to the host's system manager (such as
38 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
39 stored on the OS image, which is then responsible for probing all
40 remaining hardware, mounting all necessary file systems and
41 spawning all configured services.</para>
42
43 <para>On shutdown, the system manager stops all services, unmounts
44 all file systems (detaching the storage technologies backing
45 them), and then (optionally) jumps back into the initrd code which
46 unmounts/detaches the root file system and the storage it resides
47 on. As a last step, the system is powered down.</para>
48
49 <para>Additional information about the system boot process may be
50 found in
51 <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
52 </refsect1>
53
54 <refsect1>
55 <title>System Manager Bootup</title>
56
57 <para>At boot, the system manager on the OS image is responsible
58 for initializing the required file systems, services and drivers
59 that are necessary for operation of the system. On
60 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
61 systems, this process is split up in various discrete steps which
62 are exposed as target units. (See
63 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>
64 for detailed information about target units.) The boot-up process
65 is highly parallelized so that the order in which specific target
66 units are reached is not deterministic, but still adheres to a
67 limited amount of ordering structure.</para>
68
69 <para>When systemd starts up the system, it will activate all
70 units that are dependencies of <filename>default.target</filename>
71 (as well as recursively all dependencies of these dependencies).
72 Usually, <filename>default.target</filename> is simply an alias of
73 <filename>graphical.target</filename> or
74 <filename>multi-user.target</filename>, depending on whether the
75 system is configured for a graphical UI or only for a text
76 console. To enforce minimal ordering between the units pulled in,
77 a number of well-known target units are available, as listed on
78 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
79
80 <para>The following chart is a structural overview of these
81 well-known units and their position in the boot-up logic. The
82 arrows describe which units are pulled in and ordered before which
83 other units. Units near the top are started before units nearer to
84 the bottom of the chart.</para>
013d8a39 85
24c44fdf
ZJS
86 <!-- note: do not use unicode ellipsis here, because docbook will replace that
87 with three dots anyway, messing up alignment -->
013d8a39 88<programlisting>local-fs-pre.target
72b7d998
ZJS
89 |
90 v
013d8a39 91(various mounts and (various swap (various cryptsetup
72b7d998
ZJS
92 fsck services...) devices...) devices...) (various low-level (various low-level
93 | | | services: udevd, API VFS mounts:
94 v v v tmpfiles, random mqueue, configfs,
013d8a39 95 local-fs.target swap.target cryptsetup.target seed, sysctl, ...) debugfs, ...)
72b7d998
ZJS
96 | | | | |
97 \__________________|_________________ | ___________________|____________________/
98 \|/
99 v
100 sysinit.target
101 |
102 ____________________________________/|\________________________________________
103 / | | | \
104 | | | | |
105 v v | v v
106 (various (various | (various rescue.service
107 timers...) paths...) | sockets...) |
108 | | | | v
109 v v | v <emphasis>rescue.target</emphasis>
110 timers.target paths.target | sockets.target
111 | | | |
b44787bd 112 v \_________________ | ___________________/
72b7d998
ZJS
113 \|/
114 v
115 basic.target
116 |
117 ____________________________________/| emergency.service
118 / | | |
119 | | | v
120 v v v <emphasis>emergency.target</emphasis>
121 display- (various system (various system
122 manager.service services services)
123 | required for |
124 | graphical UIs) v
125 | | <emphasis>multi-user.target</emphasis>
126 | | |
127 \_________________ | _________________/
128 \|/
129 v
130 <emphasis>graphical.target</emphasis></programlisting>
798d3a52
ZJS
131
132 <para>Target units that are commonly used as boot targets are
133 <emphasis>emphasized</emphasis>. These units are good choices as
134 goal targets, for example by passing them to the
135 <varname>systemd.unit=</varname> kernel command line option (see
136 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
72b7d998
ZJS
137 or by symlinking <filename>default.target</filename> to them.
138 </para>
798d3a52
ZJS
139
140 <para><filename>timers.target</filename> is pulled-in by
141 <filename>basic.target</filename> asynchronously. This allows
142 timers units to depend on services which become only available
143 later in boot.</para>
144 </refsect1>
145
146 <refsect1>
147 <title>Bootup in the Initial RAM Disk (initrd)</title>
148 <para>The initial RAM disk implementation (initrd) can be set up
149 using systemd as well. In this case, boot up inside the initrd
150 follows the following structure.</para>
151
152 <para>The default target in the initrd is
153 <filename>initrd.target</filename>. The bootup process begins
154 identical to the system manager bootup (see above) until it
155 reaches <filename>basic.target</filename>. From there, systemd
156 approaches the special target <filename>initrd.target</filename>.
6d9e45e9
JH
157
158 Before any file systems are mounted, it must be determined whether
159 the system will resume from hibernation or proceed with normal boot.
160 This is accomplished by <filename>systemd-hibernate-resume@.service</filename>
161 which must be finished before <filename>local-fs-pre.target</filename>,
162 so no filesystems can be mounted before the check is complete.
163
7163e1ca
DD
164 When the root device becomes available,
165 <filename>initd-root-device.target</filename> is reached.
798d3a52
ZJS
166 If the root device can be mounted at
167 <filename>/sysroot</filename>, the
168 <filename>sysroot.mount</filename> unit becomes active and
169 <filename>initrd-root-fs.target</filename> is reached. The service
170 <filename>initrd-parse-etc.service</filename> scans
171 <filename>/sysroot/etc/fstab</filename> for a possible
172 <filename>/usr</filename> mount point and additional entries
173 marked with the <emphasis>x-initrd.mount</emphasis> option. All
174 entries found are mounted below <filename>/sysroot</filename>, and
175 <filename>initrd-fs.target</filename> is reached. The service
176 <filename>initrd-cleanup.service</filename> isolates to the
177 <filename>initrd-switch-root.target</filename>, where cleanup
178 services can run. As the very last step, the
179 <filename>initrd-switch-root.service</filename> is activated,
180 which will cause the system to switch its root to
181 <filename>/sysroot</filename>.
182 </para>
183
72b7d998
ZJS
184<programlisting> : (beginning identical to above)
185 :
186 v
187 basic.target
188 | emergency.service
189 ______________________/| |
190 / | v
7163e1ca
DD
191 | initrd-root-device.target <emphasis>emergency.target</emphasis>
192 | |
193 | v
194 | sysroot.mount
72b7d998
ZJS
195 | |
196 | v
197 | initrd-root-fs.target
198 | |
199 | v
200 v initrd-parse-etc.service
201 (custom initrd |
202 services...) v
203 | (sysroot-usr.mount and
204 | various mounts marked
205 | with fstab option
206 | x-initrd.mount...)
207 | |
208 | v
209 | initrd-fs.target
210 \______________________ |
211 \|
212 v
213 initrd.target
214 |
215 v
216 initrd-cleanup.service
217 isolates to
218 initrd-switch-root.target
219 |
220 v
221 ______________________/|
222 / v
223 | initrd-udevadm-cleanup-db.service
224 v |
225 (custom initrd |
226 services...) |
227 \______________________ |
228 \|
229 v
230 initrd-switch-root.target
231 |
232 v
233 initrd-switch-root.service
234 |
235 v
236 Transition to Host OS</programlisting>
798d3a52
ZJS
237 </refsect1>
238
798d3a52
ZJS
239 <refsect1>
240 <title>System Manager Shutdown</title>
241
242 <para>System shutdown with systemd also consists of various target
243 units with some minimal ordering structure applied:</para>
244
72b7d998
ZJS
245<programlisting> (conflicts with (conflicts with
246 all system all file system
247 services) mounts, swaps,
248 | cryptsetup
249 | devices, ...)
250 | |
251 v v
252 shutdown.target umount.target
253 | |
254 \_______ ______/
255 \ /
256 v
257 (various low-level
258 services)
259 |
260 v
261 final.target
262 |
263 _____________________________________/ \_________________________________
264 / | | \
265 | | | |
266 v v v v
0e0320e0 267systemd-reboot.service systemd-poweroff.service systemd-halt.service systemd-kexec.service
72b7d998
ZJS
268 | | | |
269 v v v v
270 <emphasis>reboot.target</emphasis> <emphasis>poweroff.target</emphasis> <emphasis>halt.target</emphasis> <emphasis>kexec.target</emphasis></programlisting>
798d3a52 271
e799056e
LP
272 <para>Commonly used system shutdown targets are <emphasis>emphasized</emphasis>.</para>
273
274 <para>Note that
39e4f5bc 275 <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
e799056e
LP
276 <filename>systemd-reboot.service</filename>, <filename>systemd-poweroff.service</filename> and
277 <filename>systemd-kexec.service</filename> will transition the system and server manager (PID 1) into the second
278 phase of system shutdown (implemented in the <filename>systemd-shutdown</filename> binary), which will unmount any
279 remaining file systems, kill any remaining processes and release any other remaining resources, in a simple and
280 robust fashion, without taking any service or unit concept into account anymore. At that point, regular
281 applications and resources are generally terminated and released already, the second phase hence operates only as
282 safety net for everything that couldn't be stopped or released for some reason during the primary, unit-based
283 shutdown phase described above.</para>
798d3a52
ZJS
284 </refsect1>
285
286 <refsect1>
287 <title>See Also</title>
288 <para>
289 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
290 <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
291 <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
292 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
e799056e 293 <citerefentry><refentrytitle>systemd-halt.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
798d3a52
ZJS
294 <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
295 </para>
296 </refsect1>
013d8a39
LP
297
298</refentry>