chiark / gitweb /
man: reword man page titles
[elogind.git] / man / daemon.xml
index 01ab0f3..9d43353 100644 (file)
@@ -8,16 +8,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-  General Public License for more details.
+  Lesser General Public License for more details.
 
-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
@@ -44,7 +44,7 @@
 
         <refnamediv>
                 <refname>daemon</refname>
-                <refpurpose>Writing and Packaging System Daemons</refpurpose>
+                <refpurpose>Writing and packaging system daemons</refpurpose>
         </refnamediv>
 
         <refsect1>
 
                                 <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
 
                                 <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
                                 <varname>StandardError=syslog</varname>
                                 in the service unit file. For details
                                 see
-                                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                                 and
                                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
 
                 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>
                         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
                         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
                         this scheme provided by systemd see
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                         and
-                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
+                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>. For
                         details about porting existing daemons to
                         socket-based activation see below. With
                         minimal effort it is possible to implement
                         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
                         <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>
                         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
                                 <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
                                 system-independent.</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>
                         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>
 
 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 an exercise for the
                         reader.)</para>
 
                         <para>Additionally, to ensure that
@@ -785,21 +801,73 @@ endif</programlisting>
 
                         <para>In the
                         <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-                        <filename>.spec</filename> file use a snippet like
-                        the following to enable/disable the service
-                        during installation/deinstallation. Consult
+                        <filename>.spec</filename> file use snippets
+                        like the following to enable/disable the
+                        service during
+                        installation/deinstallation. This makes use of
+                        the RPM macros shipped along systemd. Consult
                         the packaging guidelines of your distribution
                         for details and the equivalent for other
-                        package managers:</para>
+                        package managers.</para>
+
+                        <para>At the top of the file:</para>
+
+                        <programlisting>BuildRequires: systemd
+%{?systemd_requires}</programlisting>
+
+                        <para>And as scriptlets, further down:</para>
 
                         <programlisting>%post
-/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+%systemd_post foobar.service foobar.socket
 
 %preun
-if [ "$1" -eq 0 ]; then
-        /usr/bin/systemd-install disable foobar.service foobar.socket >/dev/null 2>&amp;1 || :
+%systemd_preun foobar.service foobar.socket
+
+%postun
+%systemd_postun</programlisting>
+
+                        <para>If the service shall be restarted during
+                        upgrades replace the
+                        <literal>%postun</literal> scriptlet above
+                        with the following:</para>
+
+                        <programlisting>%postun
+%systemd_postun_with_restart foobar.service</programlisting>
+
+                        <para>Note that
+                        <literal>%systemd_post</literal> and
+                        <literal>%systemd_preun</literal> expect the
+                        names of all units that are installed/removed
+                        as arguments, separated by
+                        spaces. <literal>%systemd_postun</literal>
+                        expects no
+                        arguments. <literal>%systemd_postun_with_restart</literal>
+                        expects the units to restart as
+                        arguments.</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>
 
@@ -809,8 +877,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 +917,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,8 +938,7 @@ 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-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,