[thirdparty/systemd.git] / man / bootup.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2012 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="bootup">

        <refentryinfo>
                <title>bootup</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>bootup</refentrytitle>
                <manvolnum>7</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>bootup</refname>
                <refpurpose>System bootup process</refpurpose>
        </refnamediv>

        <refsect1>
                <title>Description</title>

                <para>A number of different components are involved in
                the system boot. Immediately after power-up, the
                system BIOS will do minimal hardware initialization,
                and hand control over to a boot loader stored on a
                persistent storage device. This boot loader will then
                invoke an OS kernel from disk (or the network). In the
                Linux case, this kernel (optionally) extracts and
                executes an initial RAM disk image (initrd), such as
                generated by
                <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                which looks for the root file system (possibly using
                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                for this). After the root file system is found and
                mounted, the initrd hands over control to the host's
                system manager (such as
                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
                stored on the OS image, which is then responsible for
                probing all remaining hardware, mounting all necessary
                file systems and spawning all configured
                services.</para>

                <para>On shutdown, the system manager stops all
                services, unmounts all file systems (detaching the
                storage technologies backing them), and then
                (optionally) jumps back into the initrd code which
                unmounts/detaches the root file system and the storage
                it resides on. As a last step, the system is powered down.</para>

                <para>Additional information about the system boot
                process may be found in
                <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
        </refsect1>

        <refsect1>
                <title>System Manager Bootup</title>

                <para>At boot, the system manager on the OS image is
                responsible for initializing the required file
                systems, services and drivers that are necessary for
                operation of the system. On
                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                systems, this process is split up in various discrete
                steps which are exposed as target units. (See
                <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for detailed information about target units.) The
                boot-up process is highly parallelized so that the
                order in which specific target units are reached is not
                deterministic, but still adheres to a limited amount
                of ordering structure.</para>

                <para>When systemd starts up the system, it will
                activate all units that are dependencies of
                <filename>default.target</filename> (as well as
                recursively all dependencies of these
                dependencies). Usually,
                <filename>default.target</filename> is simply an alias
                of <filename>graphical.target</filename> or
                <filename>multi-user.target</filename>, depending on
                whether the system is configured for a graphical UI or
                only for a text console. To enforce minimal ordering
                between the units pulled in, a number of well-known
                target units are available, as listed on
                <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>

                <para>The following chart is a structural overview of
                these well-known units and their position in the
                boot-up logic. The arrows describe which units are
                pulled in and ordered before which other units. Units
                near the top are started before units nearer to the
                bottom of the chart.</para>

<programlisting>local-fs-pre.target
         |
         v
(various mounts and   (various swap   (various cryptsetup
 fsck services...)     devices...)        devices...)       (various low-level   (various low-level
         |                  |                  |             services: udevd,     API VFS mounts:
         v                  v                  v             tmpfiles, random     mqueue, configfs,
  local-fs.target      swap.target     cryptsetup.target    seed, sysctl, ...)      debugfs, ...)
         |                  |                  |                    |                    |
         \__________________|_________________ | ___________________|____________________/
                                              \|/
                                               v
                                        sysinit.target
                                               |
          ____________________________________/|\________________________________________
         /                  |                  |                    |                    \
         |                  |                  |                    |                    |
         v                  v                  |                    v                    v
     (various           (various               |                (various          rescue.service
    timers...)          paths...)              |               sockets...)               |
         |                  |                  |                    |                    v
         v                  v                  |                    v              <emphasis>rescue.target</emphasis>
   timers.target      paths.target             |             sockets.target
         |                  |                  |                    |
         v                  |_________________ | ___________________/
                                              \|/
                                               v
                                         basic.target
                                               |
          ____________________________________/|                                 emergency.service
         /                  |                  |                                         |
         |                  |                  |                                         v
         v                  v                  v                                 <emphasis>emergency.target</emphasis>
     display-        (various system    (various system
 manager.service         services           services)
         |             required for            |
         |            graphical UIs)           v
         |                  |           <emphasis>multi-user.target</emphasis>
         |                  |                  |
         \_________________ | _________________/
                           \|/
                            v
                  <emphasis>graphical.target</emphasis></programlisting>

                <para>Target units that are commonly used as boot
                targets are <emphasis>emphasized</emphasis>. These
                units are good choices as goal targets, for
                example by passing them to the
                <varname>systemd.unit=</varname> kernel command line
                option (see
                <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
                or by symlinking <filename>default.target</filename>
                to them.</para>

                <para><filename>timers.target</filename> is pulled-in
                by <filename>basic.target</filename> asynchronously.
                This allows timers units to depend on services which
                become only available later in boot.</para>
        </refsect1>

        <refsect1>
                <title>Bootup in the Initial RAM Disk (initrd)</title>
                <para>The initial RAM disk implementation (initrd) can
                be set up using systemd as well. In this case, boot up
                inside the initrd follows the following
                structure.</para>

                <para>The default target in the initrd is
                <filename>initrd.target</filename>. The bootup process
                begins identical to the system manager bootup (see
                above) until it reaches
                <filename>basic.target</filename>. From there, systemd
                approaches the special target
                <filename>initrd.target</filename>. If the root device
                can be mounted at <filename>/sysroot</filename>, the
                <filename>sysroot.mount</filename> unit becomes active
                and <filename>initrd-root-fs.target</filename> is
                reached.  The service
                <filename>initrd-parse-etc.service</filename> scans
                <filename>/sysroot/etc/fstab</filename> for a possible
                <filename>/usr</filename> mount point and additional
                entries marked with the
                <emphasis>x-initrd.mount</emphasis> option. All
                entries found are mounted below
                <filename>/sysroot</filename>, and
                <filename>initrd-fs.target</filename> is reached. The
                service <filename>initrd-cleanup.service</filename>
                isolates to the
                <filename>initrd-switch-root.target</filename>, where
                cleanup services can run. As the very last step, the
                <filename>initrd-switch-root.service</filename> is
                activated, which will cause the system to switch its
                root to <filename>/sysroot</filename>.
                </para>

<programlisting>                                               : (beginning identical to above)
                                               :
                                               v
                                         basic.target
                                               |                                 emergency.service
                        ______________________/|                                         |
                       /                       |                                         v
                       |                  sysroot.mount                          <emphasis>emergency.target</emphasis>
                       |                       |
                       |                       v
                       |             initrd-root-fs.target
                       |                       |
                       |                       v
                       v            initrd-parse-etc.service
                (custom initrd                 |
                 services...)                  v
                       |            (sysroot-usr.mount and
                       |             various mounts marked
                       |               with fstab option
                       |              x-initrd.mount...)
                       |                       |
                       |                       v
                       |                initrd-fs.target
                       \______________________ |
                                              \|
                                               v
                                          initrd.target
                                               |
                                               v
                                     initrd-cleanup.service
                                          isolates to
                                    initrd-switch-root.target
                                               |
                                               v
                        ______________________/|
                       /                       v
                       |        initrd-udevadm-cleanup-db.service
                       v                       |
                (custom initrd                 |
                 services...)                  |
                       \______________________ |
                                              \|
                                               v
                                   initrd-switch-root.target
                                               |
                                               v
                                   initrd-switch-root.service
                                               |
                                               v
                                     Transition to Host OS</programlisting>
        </refsect1>


        <refsect1>
                <title>System Manager Shutdown</title>

                <para>System shutdown with systemd also consists of
                various target units with some minimal ordering
                structure applied:</para>


<programlisting>                                  (conflicts with  (conflicts with
                                    all system     all file system
                                     services)     mounts, swaps,
                                         |           cryptsetup
                                         |          devices, ...)
                                         |                |
                                         v                v
                                  shutdown.target    umount.target
                                         |                |
                                         \_______   ______/
                                                 \ /
                                                  v
                                         (various low-level
                                              services)
                                                  |
                                                  v
                                            final.target
                                                  |
            _____________________________________/ \_________________________________
           /                         |                        |                      \
           |                         |                        |                      |
           v                         v                        v                      v
systemd-reboot.service   systemd-poweroff.service   systemd-halt.service   systemd-kexec.service
           |                         |                        |                      |
           v                         v                        v                      v
    <emphasis>reboot.target</emphasis>             <emphasis>poweroff.target</emphasis>            <emphasis>halt.target</emphasis>           <emphasis>kexec.target</emphasis></programlisting>

                <para>Commonly used system shutdown targets are <emphasis>emphasized</emphasis>.</para>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry project='man-pages'><refentrytitle>boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                        <citerefentry project='die-net'><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                </para>
        </refsect1>

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