man: don't recommend After=syslog.target anymore since we don't support non-socket...

[elogind.git] / man / daemon.xml

diff --git a/man/daemon.xml b/man/daemon.xml
index 30d39d7be11eeaa177cfc17d95f74783969eee2e..997ee5b2534d0e9663fa78b78cb3196cacbacaf3 100644 (file)
--- a/man/daemon.xml
+++ b/man/daemon.xml
@@ -115,7 +115,7 @@
 
                                 <listitem><para>In the child, call
                                 <function>fork()</function> again, to
 
                                 <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
                                 a terminal again.</para></listitem>
 
                                 <listitem><para>Call <function>exit()</function> in the


@@ -323,7 +323,7 @@
 
                                 <listitem><para>Instead of using the
                                 <function>syslog()</function> call to log directly to the
 
                                 <listitem><para>Instead of using the
                                 <function>syslog()</function> call to log directly to the

-                                system logger, a new-style daemon may
+                                system syslog service, a new-style daemon may

                                 choose to simply log to STDERR via
                                 <function>fprintf()</function>, which is then forwarded to
                                 syslog by the init system. If log
                                 choose to simply log to STDERR via
                                 <function>fprintf()</function>, which is then forwarded to
                                 syslog by the init system. If log


@@ -397,7 +397,7 @@
                         url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
                         Linux Standard Base Core
                         Specification</ulink>. This method of
                         url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
                         Linux Standard Base Core
                         Specification</ulink>. This method of

-                        activation is supported ubiquitiously on Linux
+                        activation is supported ubiquitously on Linux

                         init systems, both old-style and new-style
                         systems. Among other issues SysV init scripts
                         have the disadvantage of involving shell
                         init systems, both old-style and new-style
                         systems. Among other issues SysV init scripts
                         have the disadvantage of involving shell


@@ -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


@@ -644,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
                         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
                         should be configured with
                         <varname>CPUSchedulingPolicy=idle</varname>
                         and/or


@@ -705,24 +705,6 @@
                                 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
                                 an <literal>[Install]</literal>
                                 section including installation
                                 <listitem><para>Make sure to include
                                 an <literal>[Install]</literal>
                                 section including installation


@@ -760,8 +742,8 @@
                         --variable=systemdsystemunitdir</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
+                        --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
                         services available in the system on explicit
                         request but not activate them automatically
                         during boot. Optionally, during package


@@ -785,15 +767,17 @@
 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
                         machines, and optionally allows their
                         installation even on machines lacking
                         systemd. (Modification of this snippet for the
 
                         <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 an exercise for the

                         reader.)</para>
 
                         <para>Additionally, to ensure that
                         reader.)</para>
 
                         <para>Additionally, to ensure that


@@ -826,22 +810,29 @@ endif</programlisting>
 
                         <programlisting>%post
 if [ $1 -eq 1 ]; then
 
                         <programlisting>%post
 if [ $1 -eq 1 ]; then

-        # Enable (but don't start) the units by default
+        # 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 || :
         /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
 fi
 
 %preun
 if [ $1 -eq 0 ]; then

-        # Disable and stop the units
-        /bin/systemctl disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+        # On uninstall (not upgrade), disable and stop the units
+        /bin/systemctl --no-reload disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :

         /bin/systemctl stop foobar.service foobar.socket >/dev/null 2>&amp;1 || :
 fi
 
 %postun
         /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
 if [ $1 -ge 1 ] ; then

-        # On upgrade, reload init system configuration if we changed unit files
-        /bin/systemctl daemon-reload >/dev/null 2>&amp;1 || :
-        # On upgrade, restart the daemon
+        # On upgrade (not uninstall), optionally, restart the daemon

         /bin/systemctl try-restart foobar.service >/dev/null 2>&amp;1 || :
 fi</programlisting>
 
         /bin/systemctl try-restart foobar.service >/dev/null 2>&amp;1 || :
 fi</programlisting>
 


@@ -853,6 +844,29 @@ fi</programlisting>
                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                         for details.</para>
 
                         <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 --level 5 foobar ; then
+        /bin/systemctl --no-reload 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>
 
                 </refsect2>
         </refsect1>