chiark / gitweb /
machined: optionally, allow registration of pre-existing units (scopes
[elogind.git] / man / systemd.special.xml
index 8a72426..76bb5cd 100644 (file)
@@ -71,6 +71,7 @@
                 <filename>local-fs-pre.target</filename>,
                 <filename>multi-user.target</filename>,
                 <filename>network.target</filename>,
+                <filename>network-online.target</filename>,
                 <filename>nss-lookup.target</filename>,
                 <filename>nss-user-lookup.target</filename>,
                 <filename>paths.target</filename>,
                 <filename>system-update.target</filename>,
                 <filename>time-sync.target</filename>,
                 <filename>timers.target</filename>,
-                <filename>umount.target</filename></para>
+                <filename>umount.target</filename>,
+                <filename>-.slice</filename>,
+                <filename>system.slice</filename>,
+                <filename>user.slice</filename>,
+                <filename>machine.slice</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>bluetooth.target</filename></term>
-                                <listitem>
-                                        <para>This target is started
-                                        automatically as soon as a
-                                        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>
                                 <term><filename>ctrl-alt-del.target</filename></term>
                                 <listitem>
                                         <para>systemd starts this
                                         dependencies of type
                                         <varname>Before=</varname> to
                                         <filename>sysroot-usr.mount</filename>
-                                        and all mount points fround in
+                                        and all mount points found in
                                         <filename>/etc/fstab</filename>
                                         that have the
                                         <option>auto</option> and
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>local-fs-pre.target</filename></term>
-                                <listitem>
-                                        <para>This target unit is
-                                        automatically ordered before
-                                        all local mount points marked
-                                        with <option>auto</option>
-                                        (see above). It can be used to
-                                        execute certain units before
-                                        all local mounts.</para>
-                                </listitem>
-                        </varlistentry>
-                        <varlistentry>
                                 <term><filename>multi-user.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
                                         this unit during
                                         installation. This is best
                                         configured via
-                                        <varname>WantedBy=multi-uer.target</varname>
+                                        <varname>WantedBy=multi-user.target</varname>
                                         in the unit's
                                         <literal>[Install]</literal>
                                         section.</para>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>network.target</filename></term>
+                                <term><filename>network-online.target</filename></term>
                                 <listitem>
-                                        <para>systemd automatically
-                                        adds dependencies of type
-                                        <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>
+                                        <para>Units that strictly
+                                        require a configured network
+                                        connection should pull in
+                                        <filename>network-online.target</filename>
+                                        (via a
+                                        <varname>Wants=</varname> type
+                                        dependency) and order
+                                        themselves after it. This
+                                        target unit is intended to
+                                        pull in a service that delays
+                                        further execution until the
+                                        network is sufficiently set
+                                        up. What precisely this
+                                        requires is left to the
+                                        implementation of the network
+                                        managing service.</para>
 
-                                        <para>This unit is supposed to
-                                        indicate when the network is
-                                        "up", but it is only very
-                                        loosely defined what that is
-                                        supposed to mean. Also see <ulink
+                                        <para>Note the distinction
+                                        between this unit and
+                                        <filename>network.target</filename>. This
+                                        unit is an active unit
+                                        (i.e. pulled in by the
+                                        consumer rather than the
+                                        provider of this
+                                        functionality) and pulls in a
+                                        service which possibly adds
+                                        substantial delays to further
+                                        execution. In contrast,
+                                        <filename>network.target</filename>
+                                        is a passive unit (i.e. pulled
+                                        in by the provider of the
+                                        functionality, rather than the
+                                        consumer) that usually does
+                                        not delay execution
+                                        much. Usually,
+                                        <filename>network.target</filename>
+                                        is part of the boot of most
+                                        systems, while
+                                        <filename>network-online.target</filename>
+                                        is not, except when at least
+                                        one unit requires it. Also see
+                                        <ulink
                                         url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
                                         Services After the Network is
                                         up</ulink> for more
                                         information.</para>
-                                </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                                <term><filename>nss-lookup.target</filename></term>
-                                <listitem>
-                                        <para>A target that should be
-                                        used as synchronization point
-                                        for all host/network name
-                                        service lookups. Note that
-                                        this is independent of
-                                        user/group name lookups for
-                                        which
-                                        <filename>nss-user-lookup.target</filename>
-                                        should be used. systemd
-                                        automatically adds
-                                        dependencies of type
-                                        <varname>After=</varname> for
-                                        this target unit to all SysV
-                                        init script service units with
-                                        an LSB header referring to the
-                                        <literal>$named</literal>
-                                        facility.</para>
-                                </listitem>
-                        </varlistentry>
-                        <varlistentry>
-                                <term><filename>nss-user-lookup.target</filename></term>
-                                <listitem>
-                                        <para>A target that should be
-                                        used as synchronization point
-                                        for all user/group name
-                                        service lookups. Note that
-                                        this is independent of
-                                        host/network name lookups for
-                                        which
-                                        <filename>nss-lookup.target</filename>
-                                        should be used. </para>
-                                </listitem>
+
+                                        <para>All mount units for
+                                        remote network file systems
+                                        automatically pull in this
+                                        unit, and order themselves
+                                        after it. Note that networking
+                                        daemons that simply provide
+                                        functionality to other hosts
+                                        generally do not need to pull
+                                        this in.</para>
+                                        </listitem>
                         </varlistentry>
                         <varlistentry>
                                 <term><filename>paths.target</filename></term>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>printer.target</filename></term>
-                                <listitem>
-                                        <para>This target is started
-                                        automatically as soon as a
-                                        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>
                                 <term><filename>reboot.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>remote-fs-pre.target</filename></term>
-                                <listitem>
-                                        <para>This target unit is
-                                        automatically ordered before
-                                        all remote mount points marked
-                                        with <option>auto</option>
-                                        (see above). It can be used to
-                                        execute certain units before
-                                        all remote mounts.</para>
-                                </listitem>
-                        </varlistentry>
-                        <varlistentry>
                                 <term><filename>rescue.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>rpcbind.target</filename></term>
-                                <listitem>
-                                        <para>systemd automatically
-                                        adds dependencies of type
-                                        <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>
-                        </varlistentry>
-                        <varlistentry>
                                 <term><filename>runlevel2.target</filename></term>
                                 <term><filename>runlevel3.target</filename></term>
                                 <term><filename>runlevel4.target</filename></term>
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>smartcard.target</filename></term>
-                                <listitem>
-                                        <para>This target is started
-                                        automatically as soon as a
-                                        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>sound.target</filename></term>
-                                <listitem>
-                                        <para>This target is started
-                                        automatically as soon as a
-                                        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>
                                 <term><filename>suspend.target</filename></term>
                                 <listitem>
                                         <para>A special target unit
                                 </listitem>
                         </varlistentry>
                         <varlistentry>
-                                <term><filename>time-sync.target</filename></term>
-                                <listitem>
-                                        <para>systemd automatically
-                                        adds dependencies of type
-                                        <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
         </refsect1>
 
         <refsect1>
+                <title>Special System Units for Devices</title>
+
+                <para>Some target units are automatically pulled in as
+                devices of certain kinds show up in the system. These
+                may be used to automatically activate various services
+                based on the specific type of the available
+                hardware.</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><filename>bluetooth.target</filename></term>
+                                <listitem>
+                                        <para>This target is started
+                                        automatically as soon as a
+                                        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>
+                                <term><filename>printer.target</filename></term>
+                                <listitem>
+                                        <para>This target is started
+                                        automatically as soon as a
+                                        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>
+                                <term><filename>smartcard.target</filename></term>
+                                <listitem>
+                                        <para>This target is started
+                                        automatically as soon as a
+                                        smartcard controller is
+                                        plugged in or becomes
+                                        available at boot.</para>
+
+                                        <para>This may be used to pull
+                                        in smartcard management
+                                        daemons dynamically when
+                                        smartcard hardware is
+                                        found.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>sound.target</filename></term>
+                                <listitem>
+                                        <para>This target is started
+                                        automatically as soon as a
+                                        sound card is plugged in or
+                                        becomes available at
+                                        boot.</para>
+
+                                        <para>This may be used to pull
+                                        in audio management daemons
+                                        dynamically when audio
+                                        hardware is found.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
+                <title>Special Passive System Units </title>
+
+                <para>A number of special system targets are defined
+                that can be used to properly order boot-up of optional
+                services. These targets are generally not part of the
+                initial boot transaction, unless they are explicitly
+                pulled in by one of the implementing services. Note
+                specifically, that these <emphasis>passive</emphasis>
+                target units are generally not pulled in by the
+                consumer of a service, but by the provider of the
+                service. This means: a consuming service should order
+                itself after these targets (as appropriate), but not
+                pull it in. A providing service should order itself
+                before these targets (as appropriate) and pull it in
+                (via a <varname>Wants=</varname> type
+                dependency).</para>
+
+                <para>Note that these passive units cannot be started
+                manually, i.e. <literal>systemctl start
+                time-sync.target</literal> will fail with an
+                error. They can only be pulled in by dependency. This
+                is enforced since they exist for ordering purposes
+                only and thus are not useful as only unit within a
+                transaction.</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><filename>local-fs-pre.target</filename></term>
+                                <listitem>
+                                        <para>This target unit is
+                                        automatically ordered before
+                                        all local mount points marked
+                                        with <option>auto</option>
+                                        (see above). It can be used to
+                                        execute certain units before
+                                        all local mounts.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>network.target</filename></term>
+                                <listitem>
+                                        <para>This unit is supposed to
+                                        indicate when network
+                                        functionality is available,
+                                        but it is only very weakly
+                                        defined what that is supposed
+                                        to mean, with one exception:
+                                        at shutdown, a unit that is
+                                        ordered after
+                                        <filename>network.target</filename>
+                                        will be stopped before the
+                                        network -- to whatever level
+                                        it might be set up then -- is
+                                        shut down. Also see <ulink
+                                        url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
+                                        Services After the Network is
+                                        up</ulink> for more
+                                        information. Also see
+                                        <filename>network-online.target</filename>
+                                        described above.</para>
+
+                                        <para>systemd automatically
+                                        adds dependencies of type
+                                        <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>
+
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>nss-lookup.target</filename></term>
+                                <listitem>
+                                        <para>A target that should be
+                                        used as synchronization point
+                                        for all host/network name
+                                        service lookups. Note that
+                                        this is independent of
+                                        user/group name lookups for
+                                        which
+                                        <filename>nss-user-lookup.target</filename>
+                                        should be used. systemd
+                                        automatically adds
+                                        dependencies of type
+                                        <varname>After=</varname> for
+                                        this target unit to all SysV
+                                        init script service units with
+                                        an LSB header referring to the
+                                        <literal>$named</literal>
+                                        facility.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>nss-user-lookup.target</filename></term>
+                                <listitem>
+                                        <para>A target that should be
+                                        used as synchronization point
+                                        for all user/group name
+                                        service lookups. Note that
+                                        this is independent of
+                                        host/network name lookups for
+                                        which
+                                        <filename>nss-lookup.target</filename>
+                                        should be used. </para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>remote-fs-pre.target</filename></term>
+                                <listitem>
+                                        <para>This target unit is
+                                        automatically ordered before
+                                        all remote mount point units
+                                        (see above). It can be used to
+                                        run certain units before the
+                                        remote mounts are
+                                        established. Note that this
+                                        unit is generally not part of
+                                        the initial transaction,
+                                        unless the unit that wants to
+                                        be ordered before all remote
+                                        mounts pulls it in via a
+                                        <varname>Wants=</varname> type
+                                        dependency. If the unit wants
+                                        to be pulled in by the first
+                                        remote mount showing up, it
+                                        should use
+                                        <filename>network-online.target</filename>
+                                        (see above).</para>
+
+                                        <para>Again, this target unit
+                                        is <emphasis>not</emphasis>
+                                        suitable for pulling in other
+                                        units, it is only useful for
+                                        ordering.</para>
+                                </listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>rpcbind.target</filename></term>
+                                <listitem>
+                                        <para>systemd automatically
+                                        adds dependencies of type
+                                        <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>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><filename>time-sync.target</filename></term>
+                                <listitem>
+                                        <para>systemd automatically
+                                        adds dependencies of type
+                                        <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>
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
                 <title>Special User Units</title>
 
                 <para>When systemd runs as a user instance, the
                 similar definitions as their system counterparts:
                 <filename>default.target</filename>,
                 <filename>shutdown.target</filename>,
-                <filename>sockets.target</filename></para>
+                <filename>sockets.target</filename>,
+                <filename>timers.target</filename>,
+                <filename>paths.target</filename>,
+                <filename>bluetooth.target</filename>,
+                <filename>printer.target</filename>,
+                <filename>smartcard.target</filename>,
+                <filename>sound.target</filename>.</para>
 
-                <para>In addition the following special unit is
+                <para>In addition, the following special unit is
                 understood only when systemd runs as service instance:</para>
 
                 <variablelist>
                                         terminate the user service
                                         manager should start this
                                         unit. If systemd receives
-                                        SIGTERM or SIGINT when running
-                                        as user service daemon it will
+                                        <constant>SIGTERM</constant> or <constant>SIGINT</constant> when running
+                                        as user service daemon, it will
                                         start this unit.</para>
 
                                         <para>Normally, this pulls in
         </refsect1>
 
         <refsect1>
+                <title>Special Slice Units</title>
+
+                <para>There are four <literal>.slice</literal> units
+                which form the basis of the hierarchy for assignment
+                of resources for services, users, and virtual machines
+                or containers.</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><filename>-.slice</filename></term>
+                                <listitem>
+                                        <para>The root slice is the
+                                        root of the hierarchy. It
+                                        usually does not contain units
+                                        directly, but may be used to
+                                        set defaults for the whole
+                                        tree.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><filename>system.slice</filename></term>
+                                <listitem>
+                                        <para>By default, all services
+                                        services started by
+                                        <command>systemd</command> are
+                                        found in this slice.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><filename>user.slice</filename></term>
+                                <listitem>
+                                        <para>By default, all user
+                                        processes and services started
+                                        on behalf of the user,
+                                        including the per-user systemd
+                                        instance are found in this
+                                        slice.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><filename>machine.slice</filename></term>
+                                <listitem>
+                                        <para>By defalt, all virtual
+                                        machines and containers
+                                        registered with
+                                        <command>systemd-machined</command>
+                                        are found in this slice.
+                                        </para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</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>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                   </para>