X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fdaemon.xml;h=7e7039e07ad5a226f190ea302d8b517c2fcc6d17;hp=01ab0f3b511ed655a6e44d8cc879b3a68f99b564;hb=b24a167b6f0f9a44686736734e6d0cec07e1efa3;hpb=99ffae46d38f05b6c8bc09fe29e50a507ae8b79b

diff --git a/man/daemon.xml b/man/daemon.xml
index 01ab0f3b5..7e7039e07 100644
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -115,7 +115,7 @@
 
                                 <listitem><para>In the child, call
                                 <function>fork()</function> again, to
-                                ensure the daemon can never re-aquire
+                                ensure the daemon can never re-acquire
                                 a terminal again.</para></listitem>
 
                                 <listitem><para>Call <function>exit()</function> in the
@@ -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
-                case of sockets), until the activation
+                case of sockets), until the activation is
                 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
-                        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
@@ -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
-                        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
@@ -570,8 +570,9 @@
                         <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>
@@ -643,7 +644,7 @@
                         to the CPU and IO schedulers. If a process
                         executed by the init system shall not
                         negatively impact the amount of CPU or IO
-                        bandwith available to other processes, it
+                        bandwidth available to other processes, it
                         should be configured with
                         <varname>CPUSchedulingPolicy=idle</varname>
                         and/or
@@ -678,7 +679,8 @@
                                 <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
@@ -703,16 +705,45 @@
                                 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
-                                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
-                                <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>
@@ -726,19 +757,20 @@
                         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=systemdsessionunitdir</command>
-                        (for session services). This will make the
+                        --variable=systemdsystemunitdir</command> (for
+                        system services), resp. <command>pkg-config
+                        systemd
+                        --variable=systemduserunitdir</command>
+                        (for user services). This will make the
                         services available in the system on explicit
                         request but not activate them automatically
                         during boot. Optionally, during package
                         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>
 
@@ -753,15 +785,17 @@
 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
                         machines, and optionally allows their
                         installation even on machines lacking
                         systemd. (Modification of this snippet for the
-                        session unit directory is left as excercise to the
+                        user unit directory is left as excercise to the
                         reader.)</para>
 
                         <para>Additionally, to ensure that
@@ -793,13 +827,64 @@ endif</programlisting>
                         package managers:</para>
 
                         <programlisting>%post
-/usr/bin/systemd-install 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
-if [ "$1" -eq 0 ]; then
-        /usr/bin/systemd-install 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>
 
+                        <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>
 
@@ -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
-                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
@@ -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
-                        open file descriptors if file descriptors are
+                        open file descriptors if sockets are
                         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>,
-                        <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>,