units: introduce new timers.target and paths.target to hook timer/path units into...

[elogind.git] / man / systemd.special.xml

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 67a81b639b8d115df3700324f969c3bb550f05ee..8a7242662d7ac6c94958e2266803f05464849b18 100644 (file)
--- 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>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>,
                 <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>syslog.socket</filename>,
                 <filename>system-update.target</filename>,
                 <filename>time-sync.target</filename>,

+                <filename>timers.target</filename>,

                 <filename>umount.target</filename></para>
         </refsynopsisdiv>
 
                 <filename>umount.target</filename></para>
         </refsynopsisdiv>
 


@@ -116,22 +118,23 @@
                                 <term><filename>basic.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
                                 <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
                                         <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
                                         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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -139,9 +142,15 @@
                                 <listitem>
                                         <para>This target is started
                                         automatically as soon as a
                                 <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>
                                         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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -169,7 +178,7 @@
                                 <term><filename>dbus.service</filename></term>
                                 <listitem>
                                         <para>A special unit for the
                                 <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
                                         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
                                         <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>
                                         automatically gain a
                                         dependency on this
                                         unit.</para>


@@ -198,6 +207,7 @@
                                         <filename>multi-user.target</filename>
                                         or
                                         <filename>graphical.target</filename>.</para>
                                         <filename>multi-user.target</filename>
                                         or
                                         <filename>graphical.target</filename>.</para>

+

                                         <para>The default unit systemd
                                         starts at bootup can be
                                         overridden with the
                                         <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
                                 <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>
                                         </para>
                                 </listitem>
                         </varlistentry>


@@ -261,11 +273,17 @@
                                         <filename>multi-user.target</filename>.</para>
 
                                         <para>Units that are needed
                                         <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>)
                                         <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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -290,7 +308,13 @@
                                 <term><filename>halt.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
                                 <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
 
                                         <para>Applications wanting to
                                         halt the system should start


@@ -300,16 +324,17 @@
                         <varlistentry>
                                 <term><filename>initrd-fs.target</filename></term>
                                 <listitem>
                         <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.
                                         <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>
                                         </para>
                                 </listitem>
                         </varlistentry>


@@ -338,20 +363,21 @@
                         <varlistentry>
                                 <term><filename>local-fs.target</filename></term>
                                 <listitem>
                         <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
                                         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
                                         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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -377,9 +403,15 @@
 
                                         <para>Units that are needed
                                         for a multi-user system shall
 
                                         <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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -387,10 +419,10 @@
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
                                 <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>
 
                                         <literal>$network</literal>
                                         facility.</para>
 


@@ -418,7 +450,8 @@
                                         <filename>nss-user-lookup.target</filename>
                                         should be used. systemd
                                         automatically adds
                                         <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
                                         this target unit to all SysV
                                         init script service units with
                                         an LSB header referring to the


@@ -440,6 +473,29 @@
                                         should be used. </para>
                                 </listitem>
                         </varlistentry>
                                         should be used. </para>
                                 </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>
                         <varlistentry>
                                 <term><filename>poweroff.target</filename></term>
                                 <listitem>


@@ -463,6 +519,12 @@
                                         printer is plugged in or
                                         becomes available at
                                         boot.</para>
                                         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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -490,10 +552,10 @@
 
                                         <para>systemd automatically
                                         adds dependencies of type
 
                                         <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>
                                         <literal>$remote_fs</literal>
                                         facility.</para>
                                 </listitem>


@@ -525,11 +587,14 @@
                         <varlistentry>
                                 <term><filename>initrd-root-fs.target</filename></term>
                                 <listitem>
                         <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>
                                         </para>
                                 </listitem>
                         </varlistentry>


@@ -538,10 +603,10 @@
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
                                 <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>
                                         <literal>$portmap</literal>
                                         facility.</para>
                                 </listitem>


@@ -574,20 +639,12 @@
 
                                         <para>Services that shall be
                                         terminated on system shutdown
 
                                         <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>
                                         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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -607,7 +664,9 @@
                                         <para>A special target unit
                                         that is pulled in by
                                         <filename>suspend.target</filename>,
                                         <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>
                                         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>
                                         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
                                 </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
 
                                         <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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -645,6 +719,11 @@
                                         sound card is plugged in or
                                         becomes available at
                                         boot.</para>
                                         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>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>


@@ -710,14 +789,37 @@
                                 <listitem>
                                         <para>systemd automatically
                                         adds dependencies of type
                                 <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>
                                         <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>
                         <varlistentry>
                                 <term><filename>umount.target</filename></term>
                                 <listitem>


@@ -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>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>
                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                   </para>
         </refsect1>