+ <refsect2>
+ <title>Other Forms of Activation</title>
+
+ <para>Other forms of activation have been
+ suggested and implemented in some
+ systems. However, there are often simpler or
+ better alternatives, or they can be put
+ together of combinations of the schemes
+ above. Example: Sometimes, it appears useful to
+ start daemons or <filename>.socket</filename>
+ units when a specific IP address is configured
+ on a network interface, because network
+ sockets shall be bound to the
+ address. However, an alternative to implement
+ this is by utilizing the Linux IP_FREEBIND
+ socket option, as accessible via
+ <varname>FreeBind=yes</varname> in systemd
+ socket files (see
+ <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details). This option, when enabled,
+ allows sockets to be bound to a non-local, not
+ configured IP address, and hence allows
+ bindings to a particular IP address before it
+ actually becomes available, making such an
+ explicit dependency to the configured address
+ redundant. Another often suggested trigger for
+ service activation is low system
+ load. However, here too, a more convincing
+ approach might be to make proper use of
+ features of the operating system, in
+ particular, the CPU or IO scheduler of
+ Linux. Instead of scheduling jobs from
+ userspace based on monitoring the OS
+ scheduler, it is advisable to leave the
+ scheduling of processes to the OS scheduler
+ itself. systemd provides fine-grained access
+ to the CPU and IO schedulers. If a process
+ executed by the init system shall not
+ negatively impact the amount of CPU or IO
+ bandwidth available to other processes, it
+ should be configured with
+ <varname>CPUSchedulingPolicy=idle</varname>
+ and/or
+ <varname>IOSchedulingClass=idle</varname>. Optionally,
+ this may be combined with timer-based
+ activation to schedule background jobs during
+ runtime and with minimal impact on the system,
+ and remove it from the boot phase
+ itself.</para>
+ </refsect2>
+
+ </refsect1>
+ <refsect1>
+ <title>Integration with Systemd</title>
+
+ <refsect2>
+ <title>Writing Systemd Unit Files</title>
+
+ <para>When writing systemd unit files, it is
+ recommended to consider the following
+ suggestions:</para>
+
+ <orderedlist>
+ <listitem><para>If possible, do not use
+ the <varname>Type=forking</varname>
+ setting in service files. But if you
+ do, make sure to set the PID file path
+ using <varname>PIDFile=</varname>. See
+ <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details.</para></listitem>
+
+ <listitem><para>If your daemon
+ registers a D-Bus name on the bus,
+ make sure to use
+ <varname>Type=dbus</varname> in the
+ service file if
+ possible.</para></listitem>
+
+ <listitem><para>Make sure to set a
+ good human-readable description string
+ with
+ <varname>Description=</varname>.</para></listitem>
+
+ <listitem><para>Do not disable
+ <varname>DefaultDependencies=</varname>,
+ unless you really know what you do and
+ your unit is involved in early boot or
+ late system shutdown.</para></listitem>
+
+ <listitem><para>Normally, little if
+ any dependencies should need to
+ be defined explicitly. However, if you
+ do configure explicit dependencies, only refer to
+ unit names listed on
+ <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ or names introduced by your own
+ package to keep the unit file
+ operating
+ system-independent.</para></listitem>
+
+ <listitem><para>Make sure to include
+ 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. 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>
+
+ <refsect2>
+ <title>Installing Systemd Service Files</title>
+
+ <para>At the build installation time
+ (e.g. <command>make install</command> during
+ package build), packages are recommended to
+ install their systemd unit files in the
+ directory returned by <command>pkg-config
+ systemd
+ --variable=systemdsystemunitdir</command> (for
+ system services) or <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 <command>enable</command>
+ command of the
+ <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ tool to activate them automatically on
+ boot.</para>
+
+ <para>Packages using
+ <citerefentry><refentrytitle>autoconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ are recommended to use a configure script
+ excerpt like the following to determine the
+ unit installation path during source
+ configuration:</para>
+
+ <programlisting>PKG_PROG_PKG_CONFIG
+AC_ARG_WITH([systemdsystemunitdir],
+ AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files]),,
+ [with_systemdsystemunitdir=auto])
+AS_IF([test "x$with_systemdsystemunitdir" = "xyes" -o "x$with_systemdsystemunitdir" = "xauto"], [
+ def_systemdsystemunitdir=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)
+
+ AS_IF([test "x$def_systemdsystemunitdir" = "x"],
+ [AS_IF([test "x$with_systemdsystemunitdir" = "xyes"],
+ [AC_MSG_ERROR([systemd support requested but pkg-config unable to query systemd package])])
+ with_systemdsystemunitdir=no],
+ [with_systemdsystemunitdir=$def_systemdsystemunitdir])])
+AS_IF([test "x$with_systemdsystemunitdir" != "xno"],
+ [AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])])
+AM_CONDITIONAL(HAVE_SYSTEMD, [test "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
+ user unit directory is left as an exercise for the
+ reader.)</para>
+
+ <para>Additionally, to ensure that
+ <command>make distcheck</command> continues to
+ work, it is recommended to add the following
+ to the top-level <filename>Makefile.am</filename>
+ file in
+ <citerefentry><refentrytitle>automake</refentrytitle><manvolnum>1</manvolnum></citerefentry>-based
+ projects:</para>
+
+ <programlisting>DISTCHECK_CONFIGURE_FLAGS = \
+ --with-systemdsystemunitdir=$$dc_install_base/$(systemdsystemunitdir)</programlisting>
+
+ <para>Finally, unit files should be installed in the system with an automake excerpt like the following:</para>
+
+ <programlisting>if HAVE_SYSTEMD
+systemdsystemunit_DATA = \
+ foobar.socket \
+ foobar.service
+endif</programlisting>
+
+ <para>In the
+ <citerefentry><refentrytitle>rpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ <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>
+
+ <para>At the top of the file:</para>
+
+ <programlisting>BuildRequires: systemd
+%{?systemd_requires}</programlisting>
+
+ <para>And as scriptlets, further down:</para>
+
+ <programlisting>%post
+%systemd_post foobar.service foobar.socket
+
+%preun
+%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 < 0.47.11-1
+if /sbin/chkconfig --level 5 foobar ; then
+ /bin/systemctl --no-reload enable foobar.service foobar.socket >/dev/null 2>&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>