summaryrefslogtreecommitdiff
path: root/man
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2013-03-25 21:20:08 +0100
committerLennart Poettering <lennart@poettering.net>2013-03-25 21:28:30 +0100
commite3d84721dc9bcf9008f72dae03ff0f7842d0bb4b (patch)
tree2f62446a9d8961872060346793f788e3cac366fd /man
parent1b036593b76614dd05942a78120c151161cccc0f (diff)
units: introduce new timers.target and paths.target to hook timer/path units into for boot
Diffstat (limited to 'man')
-rw-r--r--man/bootup.xml143
-rw-r--r--man/systemd.special.xml258
2 files changed, 261 insertions, 140 deletions
diff --git a/man/bootup.xml b/man/bootup.xml
index 65923528d4..a596e85b70 100644
--- a/man/bootup.xml
+++ b/man/bootup.xml
@@ -50,18 +50,20 @@
<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 now (optionally) extracts and
+ <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
<citerefentry><refentrytitle>dracut</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- which looks for the root file system. After the root
- file system is found and mounted the initrd hands over
- control to the system manager (such as
+ 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
@@ -132,35 +134,35 @@
v
sysinit.target
|
- _________________/|\___________________
- / | \
- | | |
- v | v
- (various | rescue.service
- sockets...) | |
- | | v
- v | <emphasis>rescue.target</emphasis>
- sockets.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
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>
- | | |
- \_______________ | _________________/
+ ____________________________________/| 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>
+ <emphasis>graphical.target</emphasis></programlisting>
<para>Target units that are commonly used as boot
targets are <emphasis>emphasized</emphasis>. These
@@ -174,23 +176,41 @@
</refsect1>
<refsect1>
- <title>Initrd System Manager Bootup</title>
- <para>The default target in the initrd is the initrd.target. The bootup process is
- identical to the System Manager Bootup until it reaches basic.target. From there,
- systemd approaches the special initrd.target. If the root device can be mounted at
- /sysroot, the sysroot.mount unit becomes active and the initrd-root-fs.target is
- reached.
- The initrd-parse-etc.service scans /sysroot/etc/fstab for a possible /usr mountpoint
- and additional entries marked with the <emphasis>x-initrd.mount</emphasis> option.
- All entries found are mounted below /sysroot, and the initrd-fs.target is reached.
- The initrd-cleanup.service isolates to the initrd-switch-root.target, where cleanup
- services can run. As the very last step, the initrd-switch-root.service is activated,
- which will cause the system to switch its root to /sysroot.
+ <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>
- (identical to System Manager Bootup)
- :
+<programlisting> : (beginning identical to above)
:
v
basic.target
@@ -203,13 +223,13 @@
| initrd-root-fs.target
| |
| v
- | initrd-parse-etc.service
- (custom initrd services) |
- | v
+ v initrd-parse-etc.service
+ (custom initrd |
+ services...) v
| (sysroot-usr.mount and
| various mounts marked
| with fstab option
- | x-initrd.mount)
+ | x-initrd.mount...)
| |
| v
| initrd-fs.target
@@ -225,11 +245,11 @@
|
v
______________________/|
- / |
+ / v
| initrd-udevadm-cleanup-db.service
- | |
- (custom initrd services) |
- | |
+ v |
+ (custom initrd |
+ services...) |
\______________________ |
\|
v
@@ -239,17 +259,16 @@
initrd-switch-root.service
|
v
- switch-root
-</programlisting>
+ Transition to Host OS</programlisting>
</refsect1>
<refsect1>
<title>System Manager Shutdown</title>
- <para>System shutdown also consists of various target
- units with some minimal ordering structure
- applied:</para>
+ <para>System shutdown with systemd also consists of
+ various target units with some minimal ordering
+ structure applied:</para>
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 67a81b639b..8a7242662d 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -73,6 +73,7 @@
<filename>network.target</filename>,
<filename>nss-lookup.target</filename>,
<filename>nss-user-lookup.target</filename>,
+ <filename>paths.target</filename>,
<filename>poweroff.target</filename>,
<filename>printer.target</filename>,
<filename>reboot.target</filename>,
@@ -97,6 +98,7 @@
<filename>syslog.socket</filename>,
<filename>system-update.target</filename>,
<filename>time-sync.target</filename>,
+ <filename>timers.target</filename>,
<filename>umount.target</filename></para>
</refsynopsisdiv>
@@ -116,22 +118,23 @@
<term><filename>basic.target</filename></term>
<listitem>
<para>A special target unit
- covering early boot-up.</para>
+ covering basic boot-up.</para>
<para>systemd automatically
adds dependencies of the types
- Requires and After for this
- target unit to all SysV
- service units configured for
- runlevel 1 to 5.</para>
- <para>Usually this should pull-in
- all sockets, mount points,
- swap devices and other basic
+ <varname>Requires=</varname>
+ and <varname>After=</varname>
+ for this target unit to all
+ services (except for those
+ with
+ <varname>DefaultDependencies=no</varname>).</para>
+
+ <para>Usually this should
+ pull-in all mount points, swap
+ devices, sockets, timers, and
+ path units and other basic
initialization necessary for
- the general purpose
- daemons. Most normal daemons
- should have dependencies of
- type After and Requires on
- this unit.</para>
+ general purpose
+ daemons.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -139,9 +142,15 @@
<listitem>
<para>This target is started
automatically as soon as a
- bluetooth controller is
+ Bluetooth controller is
plugged in or becomes
available at boot.</para>
+
+ <para>This may be used to pull
+ in Bluetooth management
+ daemons dynamically when
+ Bluetooth hardware is
+ found.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -169,7 +178,7 @@
<term><filename>dbus.service</filename></term>
<listitem>
<para>A special unit for the
- D-Bus system bus. As soon as
+ D-Bus bus daemon. As soon as
this service is fully started
up systemd will connect to it
and register its
@@ -182,7 +191,7 @@
<para>A special unit for the
D-Bus system bus socket. All
units with
- <literal>Type=dbus</literal>
+ <varname>Type=dbus</varname>
automatically gain a
dependency on this
unit.</para>
@@ -198,6 +207,7 @@
<filename>multi-user.target</filename>
or
<filename>graphical.target</filename>.</para>
+
<para>The default unit systemd
starts at bootup can be
overridden with the
@@ -247,8 +257,10 @@
<term><filename>getty.target</filename></term>
<listitem>
<para>A special target unit
- that pulls in all local TTY
- <filename>getty</filename> instances.
+ that pulls in statically
+ configured local TTY
+ <filename>getty</filename>
+ instances.
</para>
</listitem>
</varlistentry>
@@ -261,11 +273,17 @@
<filename>multi-user.target</filename>.</para>
<para>Units that are needed
- for graphical login shall add
- Wants dependencies for their
- unit to this unit (or
+ for graphical logins shall add
+ <varname>Wants=</varname>
+ dependencies for their unit to
+ this unit (or
<filename>multi-user.target</filename>)
- during installation.</para>
+ during installation. This is
+ best configured via
+ <varname>WantedBy=graphical.target</varname>
+ in the unit's
+ <literal>[Install]</literal>
+ section.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -290,7 +308,13 @@
<term><filename>halt.target</filename></term>
<listitem>
<para>A special target unit
- for shutting down and halting the system.</para>
+ for shutting down and halting
+ the system. Note that this
+ target is distinct from
+ <filename>poweroff.target</filename>
+ in that it generally really
+ just halts the system rather
+ than powering it down.</para>
<para>Applications wanting to
halt the system should start
@@ -300,16 +324,17 @@
<varlistentry>
<term><filename>initrd-fs.target</filename></term>
<listitem>
- <para>systemd automatically
- adds dependencies of type
- Before to sysroot-usr.mount and
- all mount points fround in
+ <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ automatically adds
+ dependencies of type
+ <varname>Before=</varname> to
+ <filename>sysroot-usr.mount</filename>
+ and all mount points fround in
<filename>/etc/fstab</filename>
that have the
<option>auto</option> and
<option>x-initrd.mount</option>
mount options set.
- See also <literal>systemd-fstab-generator</literal>.
</para>
</listitem>
</varlistentry>
@@ -338,20 +363,21 @@
<varlistentry>
<term><filename>local-fs.target</filename></term>
<listitem>
- <para>systemd automatically
+ <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ automatically adds
+ dependencies of type
+ <varname>Before=</varname> to
+ all mount units that refer to
+ local mount points for this
+ target unit. In addition, it
adds dependencies of type
- After to all mount units that
- refer to local mount points
- for this target unit. In
- addition, systemd adds
- dependencies of type Wants to
+ <varname>Wants=</varname> to
this target unit for those
mounts listed in
<filename>/etc/fstab</filename>
that have the
- <option>auto</option> and
- <option>comment=systemd.mount</option>
- mount options set.</para>
+ <option>auto</option> mount
+ option set.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -377,9 +403,15 @@
<para>Units that are needed
for a multi-user system shall
- add Wants dependencies to
- this unit for their unit during
- installation.</para>
+ add <varname>Wants=</varname>
+ dependencies for their unit to
+ this unit during
+ installation. This is best
+ configured via
+ <varname>WantedBy=multi-uer.target</varname>
+ in the unit's
+ <literal>[Install]</literal>
+ section.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -387,10 +419,10 @@
<listitem>
<para>systemd automatically
adds dependencies of type
- After for this target unit to
- all SysV init script service
- units with an LSB header
- referring to the
+ <varname>After=</varname> for
+ this target unit to all SysV
+ init script service units with
+ an LSB header referring to the
<literal>$network</literal>
facility.</para>
@@ -418,7 +450,8 @@
<filename>nss-user-lookup.target</filename>
should be used. systemd
automatically adds
- dependencies of type After for
+ dependencies of type
+ <varname>After=</varname> for
this target unit to all SysV
init script service units with
an LSB header referring to the
@@ -441,6 +474,29 @@
</listitem>
</varlistentry>
<varlistentry>
+ <term><filename>paths.target</filename></term>
+ <listitem>
+ <para>A special target unit
+ that sets up all path units
+ (see
+ <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details) that shall be
+ active after boot.</para>
+
+ <para>It is recommended that
+ path units installed by
+ applications get pulled in via
+ <varname>Wants=</varname>
+ dependencies from this
+ unit. This is best configured
+ via a
+ <varname>WantedBy=paths.target</varname>
+ in the path unit's
+ <literal>[Install]</literal>
+ section.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><filename>poweroff.target</filename></term>
<listitem>
<para>A special target unit
@@ -463,6 +519,12 @@
printer is plugged in or
becomes available at
boot.</para>
+
+ <para>This may be used to pull
+ in printer management
+ daemons dynamically when
+ printer hardware is
+ found.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -490,10 +552,10 @@
<para>systemd automatically
adds dependencies of type
- After for this target unit to
- all SysV init script service
- units with an LSB header
- referring to the
+ <varname>After=</varname> for
+ this target unit to all SysV
+ init script service units with
+ an LSB header referring to the
<literal>$remote_fs</literal>
facility.</para>
</listitem>
@@ -525,11 +587,14 @@
<varlistentry>
<term><filename>initrd-root-fs.target</filename></term>
<listitem>
- <para>systemd automatically
- adds dependencies of type
- Before to the sysroot.mount unit,
- which is generated from the kernel command
- line by the <literal>systemd-fstab-generator</literal>.
+ <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ automatically adds
+ dependencies of type
+ <varname>Before=</varname> to
+ the
+ <filename>sysroot.mount</filename>
+ unit, which is generated from
+ the kernel command line.
</para>
</listitem>
</varlistentry>
@@ -538,10 +603,10 @@
<listitem>
<para>systemd automatically
adds dependencies of type
- After for this target unit to
- all SysV init script service
- units with an LSB header
- referring to the
+ <varname>After=</varname> for
+ this target unit to all SysV
+ init script service units with
+ an LSB header referring to the
<literal>$portmap</literal>
facility.</para>
</listitem>
@@ -574,20 +639,12 @@
<para>Services that shall be
terminated on system shutdown
- shall add Conflicts
+ shall add <varname>Conflicts=</varname>
dependencies to this unit for
their service unit, which is
implicitly done when
<varname>DefaultDependencies=yes</varname>
is set (the default).</para>
-
- <para>systemd automatically
- adds dependencies of type
- Conflicts to this target unit
- for all SysV init script
- service units that shall be
- terminated in SysV runlevels 0
- or 6.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -607,7 +664,9 @@
<para>A special target unit
that is pulled in by
<filename>suspend.target</filename>,
- <filename>hibernate.target</filename> and <filename>hybrid-sleep.target</filename>
+ <filename>hibernate.target</filename>
+ and
+ <filename>hybrid-sleep.target</filename>
and may be used to hook units
into the sleep state
logic.</para>
@@ -621,20 +680,35 @@
smartcard controller is
plugged in or becomes
available at boot.</para>
+
+ <para>This may be used to pull
+ in printer management
+ daemons dynamically when
+ smartcard hardware is
+ found.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>sockets.target</filename></term>
<listitem>
<para>A special target unit
- that sets up all service
- sockets.</para>
+ that sets up all socket
+ units.(see
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details) that shall be
+ active after boot.</para>
<para>Services that can be
socket-activated shall add
- Wants dependencies to this
- unit for their socket unit
- during installation.</para>
+ <varname>Wants=</varname>
+ dependencies to this unit for
+ their socket unit during
+ installation. This is best
+ configured via a
+ <varname>WantedBy=sockets.target</varname>
+ in the socket unit's
+ <literal>[Install]</literal>
+ section.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -645,6 +719,11 @@
sound card is plugged in or
becomes available at
boot.</para>
+
+ <para>This may be used to pull
+ in audio management daemons
+ dynamically when printer
+ hardware is found.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -710,15 +789,38 @@
<listitem>
<para>systemd automatically
adds dependencies of type
- After for this target unit to
- all SysV init script service
- units with an LSB header
- referring to the
+ <varname>After=</varname> for
+ this target unit to all SysV
+ init script service units with
+ an LSB header referring to the
<literal>$time</literal>
facility.</para>
</listitem>
</varlistentry>
<varlistentry>
+ <term><filename>timers.target</filename></term>
+ <listitem>
+ <para>A special target unit
+ that sets up all timer
+ units (see
+ <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details) that shall be
+ active after boot.</para>
+
+ <para>It is recommended that
+ timer units installed by
+ applications get pulled in via
+ <varname>Wants=</varname>
+ dependencies from this
+ unit. This is best configured
+ via
+ <varname>WantedBy=timers.target</varname>
+ in the timer unit's
+ <literal>[Install]</literal>
+ section.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><filename>umount.target</filename></term>
<listitem>
<para>A special target unit
@@ -788,7 +890,7 @@
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>