man/bootup.xml

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