man: extend commenting of .spec file snippets a bit

[elogind.git] / man / daemon.xml

diff --git a/man/daemon.xml b/man/daemon.xml
index 8e9e9395321c657a6f6c85ca802f1d4473843b9d..42a7ffd8bb1d02f8193e27a7f26da25d7ad462b2 100644 (file)
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -384,7 +384,7 @@
                 communication channels are established already, and no
                 request is lost because client requests will be queued
                 by the bus system (in case of D-Bus) or the kernel (in
                 communication channels are established already, and no
                 request is lost because client requests will be queued
                 by the bus system (in case of D-Bus) or the kernel (in

-                case of sockets), until the activation
+                case of sockets), until the activation is

                 completed.</para>
 
                 <refsect2>
                 completed.</para>
 
                 <refsect2>


@@ -449,7 +449,7 @@
                         activation of daemons. However, the primary
                         advantage of this scheme is that all providers
                         and all consumers of the sockets can be
                         activation of daemons. However, the primary
                         advantage of this scheme is that all providers
                         and all consumers of the sockets can be

-                        started in parallel as soon als all sockets
+                        started in parallel as soon as all sockets

                         are established. In addition to that daemons
                         can be restarted with losing only a minimal
                         number of client transactions or even any
                         are established. In addition to that daemons
                         can be restarted with losing only a minimal
                         number of client transactions or even any


@@ -543,10 +543,10 @@
                         the hardware of the respective kind is plugged
                         in or otherwise becomes available. In a
                         new-style init system it is possible to bind
                         the hardware of the respective kind is plugged
                         in or otherwise becomes available. In a
                         new-style init system it is possible to bind

-                        activation to hardware plug/unplug events. In systemd,
-                        kernel devices appearing in the sysfs/udev
-                        device tree can be exposed as units if they
-                        are tagged with the string
+                        activation to hardware plug/unplug events. In
+                        systemd, kernel devices appearing in the
+                        sysfs/udev device tree can be exposed as units
+                        if they are tagged with the string

                         "<literal>systemd</literal>". Like any other
                         kind of unit they may then pull in other units
                         when activated (i.e. Plugged in) and thus
                         "<literal>systemd</literal>". Like any other
                         kind of unit they may then pull in other units
                         when activated (i.e. Plugged in) and thus


@@ -570,8 +570,9 @@
                         <filename>bluetoothd.service</filename> via
                         controlling a
                         <filename>bluetooth.target.wants/</filename>
                         <filename>bluetoothd.service</filename> via
                         controlling a
                         <filename>bluetooth.target.wants/</filename>

-                        symlink uniformly with a tool like
-                        <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        symlink uniformly with a command like
+                        <command>enable</command> of
+                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>

                         instead of manipulating the udev
                         ruleset.</para>
                 </refsect2>
                         instead of manipulating the udev
                         ruleset.</para>
                 </refsect2>


@@ -678,7 +679,8 @@
                                 <listitem><para>If your daemon
                                 registers a D-Bus name on the bus,
                                 make sure to use
                                 <listitem><para>If your daemon
                                 registers a D-Bus name on the bus,
                                 make sure to use

-                                <varname>Type=dbus</varname> if
+                                <varname>Type=dbus</varname> in the
+                                service file if

                                 possible.</para></listitem>
 
                                 <listitem><para>Make sure to set a
                                 possible.</para></listitem>
 
                                 <listitem><para>Make sure to set a


@@ -703,16 +705,45 @@
                                 operating
                                 system-independent.</para></listitem>
 
                                 operating
                                 system-independent.</para></listitem>
 

+                                <listitem><para>Since not all syslog
+                                implementations are socket-activatable
+                                yet, it is recommended to place an
+                                <varname>After=syslog.target</varname>
+                                dependency in service files for
+                                daemons that can log to
+                                syslog. <filename>syslog.target</filename>
+                                then either pulls in the syslog daemon
+                                itself or simply the activation
+                                socket. A <varname>Wants=</varname> or
+                                even <varname>Requires=</varname>
+                                dependency should generally not be
+                                added, since it should be up to the
+                                administrator whether he wants to
+                                enable logging or not, and most syslog
+                                clients work fine if no log daemon is
+                                running.</para></listitem>
+

                                 <listitem><para>Make sure to include
                                 <listitem><para>Make sure to include

-                                an <literal>[Install]</literal> section including
-                                installation information for the unit
-                                file. See
+                                an <literal>[Install]</literal>
+                                section including installation
+                                information for the unit file. See

                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                 for details. To activate your service
                                 on boot make sure to add a
                                 <varname>WantedBy=multi-user.target</varname>
                                 or
                                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                 for details. To activate your service
                                 on boot make sure to add a
                                 <varname>WantedBy=multi-user.target</varname>
                                 or

-                                <varname>WantedBy=graphical.target</varname> directive.</para></listitem>
+                                <varname>WantedBy=graphical.target</varname>
+                                directive. To activate your socket on
+                                boot, make sure to add
+                                <varname>WantedBy=sockets.target</varname>. Usually
+                                you also want to make sure that when
+                                your service is installed your socket
+                                is installed too, hence add
+                                <varname>Also=foo.socket</varname> in
+                                your service file
+                                <filename>foo.service</filename>, for
+                                a hypothetical program
+                                <filename>foo</filename>.</para></listitem>

 
                         </orderedlist>
                 </refsect2>
 
                         </orderedlist>
                 </refsect2>


@@ -726,9 +757,9 @@
                         install their systemd unit files in the
                         directory returned by <command>pkg-config
                         systemd
                         install their systemd unit files in the
                         directory returned by <command>pkg-config
                         systemd

-                        --variable=systemdsystemnunitdir</command>
-                        (for system services),
-                        resp. <command>pkg-config systemd
+                        --variable=systemdsystemunitdir</command> (for
+                        system services), resp. <command>pkg-config
+                        systemd

                         --variable=systemdsessionunitdir</command>
                         (for session services). This will make the
                         services available in the system on explicit
                         --variable=systemdsessionunitdir</command>
                         (for session services). This will make the
                         services available in the system on explicit


@@ -737,8 +768,9 @@
                         installation (e.g. <command>rpm -i</command>
                         by the administrator) symlinks should be
                         created in the systemd configuration
                         installation (e.g. <command>rpm -i</command>
                         by the administrator) symlinks should be
                         created in the systemd configuration

-                        directories via the
-                        <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        directories via the <command>enable</command>
+                        command of the
+                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>

                         tool, to activate them automatically on
                         boot.</para>
 
                         tool, to activate them automatically on
                         boot.</para>
 


@@ -753,8 +785,10 @@
 AC_ARG_WITH([systemdsystemunitdir],
         AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
         [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
 AC_ARG_WITH([systemdsystemunitdir],
         AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),
         [], [with_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])

-AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
-AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir"])</programlisting>
+if test "x$with_systemdsystemunitdir" != xno; then
+        AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
+fi
+AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ])</programlisting>

 
                         <para>This snippet allows automatic
                         installation of the unit files on systemd
 
                         <para>This snippet allows automatic
                         installation of the unit files on systemd


@@ -793,13 +827,64 @@ endif</programlisting>
                         package managers:</para>
 
                         <programlisting>%post
                         package managers:</para>
 
                         <programlisting>%post

-/usr/bin/systemd-install --start enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+if [ $1 -eq 1 ]; then
+        # On install (not upgrade), enable (but don't start) the
+        # units by default
+        /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+
+        # Alternatively, just call
+        # /bin/systemctl daemon-reload >/dev/null 2>&amp;1 || :
+        # here, if the daemon should not be enabled by default on
+        # installation
+fi

 
 %preun
 
 %preun

-if [ "$1" -eq 0 ]; then
-        /usr/bin/systemd-install --start disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+if [ $1 -eq 0 ]; then
+        # On uninstall (not upgrade), disable and stop the units
+        /bin/systemctl disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+        /bin/systemctl stop foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+fi
+
+%postun
+# Reload init system configuration, to make systemd honour changed
+# or deleted unit files
+/bin/systemctl daemon-reload >/dev/null 2>&amp;1 || :
+if [ $1 -ge 1 ] ; then
+        # On upgrade (not uninstall), optionally, restart the daemon
+        /bin/systemctl try-restart foobar.service >/dev/null 2>&amp;1 || :
+fi</programlisting>
+
+                        <para>Depending on whether your service should
+                        or should not be started/stopped/restarted
+                        during package installation, deinstallation or
+                        upgrade, a different set of commands may be
+                        specified. See
+                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        for details.</para>
+
+                        <para>To facilitate upgrades from a package
+                        version that shipped only SysV init scripts to
+                        a package version that ships both a SysV init
+                        script and a native systemd service file, use
+                        a fragment like the following:</para>
+
+                        <programlisting>%triggerun -- foobar &lt; 0.47.11-1
+if /sbin/chkconfig foobar ; then
+        /bin/systemctl enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :

 fi</programlisting>
 
 fi</programlisting>
 

+                        <para>Where 0.47.11-1 is the first package
+                        version that includes the native unit
+                        file. This fragment will ensure that the first
+                        time the unit file is installed it will be
+                        enabled if and only if the SysV init script is
+                        enabled, thus making sure that the enable
+                        status is not changed. Note that
+                        <command>chkconfig</command> is a command
+                        specific to Fedora which can be used to check
+                        whether a SysV init script is enabled. Other
+                        operating systems will have to use different
+                        commands here.</para>

                 </refsect2>
         </refsect1>
 
                 </refsect2>
         </refsect1>
 


@@ -809,8 +894,8 @@ fi</programlisting>
                 <para>Since new-style init systems such as systemd are
                 compatible with traditional SysV init systems it is
                 not strictly necessary to port existing daemons to the
                 <para>Since new-style init systems such as systemd are
                 compatible with traditional SysV init systems it is
                 not strictly necessary to port existing daemons to the

-                new style. However doing this offers additional
-                functionality to the daemons as well as it simplifies
+                new style. However doing so offers additional
+                functionality to the daemons as well as simplifying

                 integration into new-style init systems.</para>
 
                 <para>To port an existing SysV compatible daemon the
                 integration into new-style init systems.</para>
 
                 <para>To port an existing SysV compatible daemon the


@@ -849,7 +934,7 @@ fi</programlisting>
                         left-over file descriptors are passed to
                         executed processes, it might be a good choice
                         to simply skip the closing of all remaining
                         left-over file descriptors are passed to
                         executed processes, it might be a good choice
                         to simply skip the closing of all remaining

-                        open file descriptors if file descriptors are
+                        open file descriptors if sockets are

                         passed.</para></listitem>
 
                         <listitem><para>Write and install a systemd
                         passed.</para></listitem>
 
                         <listitem><para>Write and install a systemd


@@ -870,7 +955,6 @@ fi</programlisting>
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                 <title>See Also</title>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,