+
+ <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=systemdsystemnunitdir</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
+ 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>
+ 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=$($PKG_CONFIG --variable=systemdsystemunitdir systemd)])
+AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir])
+AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir"])</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
+ 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 a snippet like
+ the following to enable/disable the service
+ during installation/deinstallation. Consult
+ the packaging guidelines of your distribution
+ for details and the equivalent for other
+ packaging managers:</para>
+
+ <programlisting>%post
+/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&1 || :
+
+%preun
+if [ "$1" -eq 0 ]; then
+ /usr/bin/systemd-install disable foobar.service foobar.socket >/dev/null 2>&1 || :
+fi</programlisting>
+
+ </refsect2>
+
+ <refsect2>
+ <title>Porting Existing Daemons</title>
+
+ <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 integration into new-style init
+ systems.</para>
+
+ <para>To port an existing SysV compatible
+ daemon the following steps are
+ recommended:</para>
+
+ <orderedlist>
+ <listitem><para>If not already
+ implemented, add an optional command
+ line switch to the daemon to disable
+ daemonization. This is useful not only
+ for using the daemon in new-style init
+ systems, but also to ease debugging.</para></listitem>
+
+ <listitem><para>If the daemon offers
+ interfaces to other software running
+ on the local system via local AF_UNIX
+ sockets, consider implementing
+ socket-based activation (see
+ above). Usually a minimal patch is
+ sufficient to implement this: Extend
+ the socket creation in the daemon code
+ so that
+ <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ is checked for already passed sockets
+ first. If sockets are passed
+ (i.e. when
+ <function>sd_listen_fds()</function>
+ returns a positive value), skip the
+ socket createn step and use the passed
+ sockets. Secondly, ensure that the
+ file-system socket nodes for local
+ AF_UNIX sockets used in the
+ socket-based activation are not
+ removed when the daemon shuts down, if
+ sockets have been passed. Third, if
+ the daemon normally closes all
+ remaining open file descriptors as
+ part of its initialization, the
+ sockets passed from the init system
+ must be spared. Since new-style init
+ systems guarantee that no 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
+ passed.</para></listitem>
+
+ <listitem><para>Write and install a
+ systemd unit file for the service (and
+ the sockets if socket-based activation
+ is used, as well as a path unit file,
+ if the daemon processes a spool
+ directory), see above for
+ details.</para></listitem>
+
+ <listitem><para>If the daemon exposes
+ interfaces via D-Bus, write and
+ install a D-Bus activation file for
+ the service, see above for
+ details.</para></listitem>
+ </orderedlist>
+
~ianmdlvl / elogind.git / commitdiff