man: various man page updates
This commit is contained in:
Lennart Poettering
parent
af65a09126
commit
62adf224d1
387
man/daemon.xml
387
man/daemon.xml
|
|
@ -21,7 +21,7 @@
|
||||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<refentry id="systemd.special">
|
<refentry id="daemon">
|
||||||
|
|
||||||
<refentryinfo>
|
<refentryinfo>
|
||||||
<title>daemon</title>
|
<title>daemon</title>
|
||||||
|
|
@ -55,8 +55,9 @@
|
||||||
functionality to other processes. Traditionally,
|
functionality to other processes. Traditionally,
|
||||||
daemons are implemented following a scheme originating
|
daemons are implemented following a scheme originating
|
||||||
in SysV Unix. Modern daemons should follow a simpler
|
in SysV Unix. Modern daemons should follow a simpler
|
||||||
yet more powerful scheme here called "new-style"
|
yet more powerful scheme (here called "new-style"
|
||||||
daemons, as implemented by systemd. </para>
|
daemons), as implemented by
|
||||||
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>. </para>
|
||||||
|
|
||||||
<refsect2>
|
<refsect2>
|
||||||
<title>SysV Daemons</title>
|
<title>SysV Daemons</title>
|
||||||
|
|
@ -64,7 +65,7 @@
|
||||||
<para>When a traditional SysV daemon
|
<para>When a traditional SysV daemon
|
||||||
starts, it should execute the following steps
|
starts, it should execute the following steps
|
||||||
as part of the initialization. Note that these
|
as part of the initialization. Note that these
|
||||||
steps are unnecessary for new-style daemons,
|
steps are unnecessary for new-style daemons (see below),
|
||||||
and should only be implemented if compatibility
|
and should only be implemented if compatibility
|
||||||
with SysV is essential.</para>
|
with SysV is essential.</para>
|
||||||
|
|
||||||
|
|
@ -80,7 +81,7 @@
|
||||||
<filename>/proc/self/fd</filename>,
|
<filename>/proc/self/fd</filename>,
|
||||||
with a fallback of iterating from file
|
with a fallback of iterating from file
|
||||||
descriptor 3 to the value returned by
|
descriptor 3 to the value returned by
|
||||||
getrlimit() for
|
<function>getrlimit()</function> for
|
||||||
RLIMIT_NOFILE.</para></listitem>
|
RLIMIT_NOFILE.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>Reset all signal
|
<listitem><para>Reset all signal
|
||||||
|
|
@ -91,23 +92,30 @@
|
||||||
SIG_DFL.</para></listitem>
|
SIG_DFL.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>Reset the signal mask
|
<listitem><para>Reset the signal mask
|
||||||
using sigprocmask().</para></listitem>
|
using
|
||||||
|
<function>sigprocmask()</function>.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>Call fork(),
|
<listitem><para>Sanitize the
|
||||||
|
environment block, removing or
|
||||||
|
resetting environment variables that
|
||||||
|
might negatively impact daemon
|
||||||
|
runtime.</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>Call <function>fork()</function>,
|
||||||
to create a background
|
to create a background
|
||||||
process.</para></listitem>
|
process.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>In the child, call
|
<listitem><para>In the child, call
|
||||||
setsid() to detach from any terminal
|
<function>setsid()</function> to
|
||||||
and create an independent
|
detach from any terminal and create an
|
||||||
session.</para></listitem>
|
independent session.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>In the child, call
|
<listitem><para>In the child, call
|
||||||
fork() again, to ensure the daemon can
|
<function>fork()</function> again, to
|
||||||
never re-aquire a terminal
|
ensure the daemon can never re-aquire
|
||||||
again.</para></listitem>
|
a terminal again.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>Call exit() in the
|
<listitem><para>Call <function>exit()</function> in the
|
||||||
first child, so that only the second
|
first child, so that only the second
|
||||||
child (the actual daemon process)
|
child (the actual daemon process)
|
||||||
stays around. This ensures that the
|
stays around. This ensures that the
|
||||||
|
|
@ -122,7 +130,7 @@
|
||||||
|
|
||||||
<listitem><para>In the daemon process,
|
<listitem><para>In the daemon process,
|
||||||
reset the umask to 0, so that the file
|
reset the umask to 0, so that the file
|
||||||
modes passed to open(), mkdir() and
|
modes passed to <function>open()</function>, <function>mkdir()</function> and
|
||||||
suchlike directly control the access
|
suchlike directly control the access
|
||||||
mode of the created files and
|
mode of the created files and
|
||||||
directories.</para></listitem>
|
directories.</para></listitem>
|
||||||
|
|
@ -134,6 +142,23 @@
|
||||||
blocks mount points from being
|
blocks mount points from being
|
||||||
unmounted.</para></listitem>
|
unmounted.</para></listitem>
|
||||||
|
|
||||||
|
<listitem><para>In the daemon process,
|
||||||
|
write the daemon PID (as returned by
|
||||||
|
<function>getpid()</function>) to a
|
||||||
|
PID file, for example
|
||||||
|
<filename>/var/run/foobar.pid</filename>
|
||||||
|
(for a hypothetical daemon "foobar"),
|
||||||
|
to ensure that the daemon cannot be
|
||||||
|
started more than once. This must be
|
||||||
|
implemented in race-free fashion so
|
||||||
|
that the PID file is only updated when
|
||||||
|
at the same time it is verified that
|
||||||
|
the PID previously stored in the PID
|
||||||
|
file no longer exists or belongs to a
|
||||||
|
foreign process. Commonly some kind of
|
||||||
|
file locking is employed to implement
|
||||||
|
this logic.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>In the daemon process,
|
<listitem><para>In the daemon process,
|
||||||
drop privileges, if possible and
|
drop privileges, if possible and
|
||||||
applicable.</para></listitem>
|
applicable.</para></listitem>
|
||||||
|
|
@ -144,21 +169,25 @@
|
||||||
complete. This can be implemented via
|
complete. This can be implemented via
|
||||||
an unnamed pipe or similar
|
an unnamed pipe or similar
|
||||||
communication channel that is created
|
communication channel that is created
|
||||||
before the first fork() and available
|
before the first
|
||||||
in both processes.</para></listitem>
|
<function>fork()</function> and hence
|
||||||
|
available in both the original and the
|
||||||
|
daemon process.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>Call exit() in the
|
<listitem><para>Call
|
||||||
|
<function>exit()</function> in the
|
||||||
original process. The process that
|
original process. The process that
|
||||||
invoked the daemon must be able to
|
invoked the daemon must be able to
|
||||||
rely that this exit() happens after
|
rely that this
|
||||||
initialization is complete and all
|
<function>exit()</function> happens
|
||||||
external communication channels
|
after initialization is complete and
|
||||||
|
all external communication channels
|
||||||
established and
|
established and
|
||||||
accessible.</para></listitem>
|
accessible.</para></listitem>
|
||||||
</orderedlist>
|
</orderedlist>
|
||||||
|
|
||||||
<para>The BSD daemon() function should not be
|
<para>The BSD <function>daemon()</function> function should not be
|
||||||
used, as it does only a subset of these steps.</para>
|
used, as it implements only a subset of these steps.</para>
|
||||||
|
|
||||||
<para>A daemon that needs to provide
|
<para>A daemon that needs to provide
|
||||||
compatibility with SysV systems should
|
compatibility with SysV systems should
|
||||||
|
|
@ -190,6 +219,17 @@
|
||||||
execute them when run as new-style
|
execute them when run as new-style
|
||||||
service.</para>
|
service.</para>
|
||||||
|
|
||||||
|
<para>Note that new-style init systems
|
||||||
|
guarantee execution of daemon processes in
|
||||||
|
clean process contexts: it is guaranteed that
|
||||||
|
the environment block is sanitized, that the
|
||||||
|
signal handlers and mask is reset and that no
|
||||||
|
left-over file descriptors are passed. Daemons
|
||||||
|
will be executed in their own session, and
|
||||||
|
STDIN/STDOUT/STDERR connected to
|
||||||
|
<filename>/dev/null</filename> unless
|
||||||
|
otherwise configured. The umask is reset.</para>
|
||||||
|
|
||||||
<para>It is recommended for new-style daemons
|
<para>It is recommended for new-style daemons
|
||||||
to implement the following:</para>
|
to implement the following:</para>
|
||||||
|
|
||||||
|
|
@ -207,9 +247,10 @@
|
||||||
this is used by the init system to
|
this is used by the init system to
|
||||||
detect service errors and problems. It
|
detect service errors and problems. It
|
||||||
is recommended to follow the exit code
|
is recommended to follow the exit code
|
||||||
scheme as defined in LSB
|
scheme as defined in the <ulink
|
||||||
recommendations for SysV init scripts
|
url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB
|
||||||
(http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem>
|
recommendations for SysV init
|
||||||
|
scripts</ulink>.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>As much as possible,
|
<listitem><para>As much as possible,
|
||||||
rely on systemd's functionality to
|
rely on systemd's functionality to
|
||||||
|
|
@ -220,7 +261,10 @@
|
||||||
implementing your own, rely on
|
implementing your own, rely on
|
||||||
systemd's privilege dropping code
|
systemd's privilege dropping code
|
||||||
instead of implementing it in the
|
instead of implementing it in the
|
||||||
daemon, and similar.</para></listitem>
|
daemon, and similar. See
|
||||||
|
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
|
for the available
|
||||||
|
controls.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>If possible and
|
<listitem><para>If possible and
|
||||||
applicable expose the daemon's control
|
applicable expose the daemon's control
|
||||||
|
|
@ -239,8 +283,8 @@
|
||||||
boot-up speed; your daemon can be
|
boot-up speed; your daemon can be
|
||||||
restarted on failure, without losing
|
restarted on failure, without losing
|
||||||
any bus requests, as the bus queues
|
any bus requests, as the bus queues
|
||||||
requests for activatable
|
requests for activatable services. See
|
||||||
services.</para></listitem>
|
below for details.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>If your daemon
|
<listitem><para>If your daemon
|
||||||
provides services to other local
|
provides services to other local
|
||||||
|
|
@ -255,20 +299,21 @@
|
||||||
protocols (such as syslog, DNS) a
|
protocols (such as syslog, DNS) a
|
||||||
daemon implementing socket-based
|
daemon implementing socket-based
|
||||||
activation can be restarted without
|
activation can be restarted without
|
||||||
losing a single
|
losing a single request. See below for
|
||||||
request.</para></listitem>
|
details.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>If applicable a daemon
|
<listitem><para>If applicable a daemon
|
||||||
should notify the init system about
|
should notify the init system about
|
||||||
startup completion or status
|
startup completion or status updates
|
||||||
updates via the sd_notify()
|
via the
|
||||||
|
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
interface.</para></listitem>
|
interface.</para></listitem>
|
||||||
|
|
||||||
<listitem><para>Instead of using the
|
<listitem><para>Instead of using the
|
||||||
syslog() call to log directly to the
|
<function>syslog()</function> call to log directly to the
|
||||||
system logger, a new-style daemon may
|
system logger, a new-style daemon may
|
||||||
choose to simply log to STDERR via
|
choose to simply log to STDERR via
|
||||||
fprintf(), which is then forwarded to
|
<function>fprintf()</function>, which is then forwarded to
|
||||||
syslog by the init system. If log
|
syslog by the init system. If log
|
||||||
priorities are necessary these can be
|
priorities are necessary these can be
|
||||||
encoded by prefixing individual log
|
encoded by prefixing individual log
|
||||||
|
|
@ -276,30 +321,259 @@
|
||||||
(for log priority 4 "WARNING" in the
|
(for log priority 4 "WARNING" in the
|
||||||
syslog priority scheme), following a
|
syslog priority scheme), following a
|
||||||
similar style as the Linux kernel's
|
similar style as the Linux kernel's
|
||||||
printk() priority system. In fact, using
|
<function>printk()</function> priority system. In fact,
|
||||||
this style of logging also enables the
|
using this style of logging also
|
||||||
init system to optionally direct all
|
enables the init system to optionally
|
||||||
application logging to the kernel log
|
direct all application logging to the
|
||||||
buffer (kmsg), as accessible via
|
kernel log buffer (kmsg), as
|
||||||
dmesg.</para></listitem>
|
accessible via
|
||||||
|
<citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
|
||||||
|
kind of logging may be enabled by
|
||||||
|
setting
|
||||||
|
<varname>StandardError=syslog</varname>
|
||||||
|
in the service unit file. For details
|
||||||
|
see
|
||||||
|
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||||
|
and
|
||||||
|
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
|
||||||
|
|
||||||
|
</orderedlist>
|
||||||
|
|
||||||
|
<para>These recommendations are similar but
|
||||||
|
not identical to the <ulink
|
||||||
|
url="http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html#//apple_ref/doc/uid/TP40001762-104738">Apple
|
||||||
|
MacOS X Daemon Requirements</ulink>.</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2>
|
||||||
|
<title>Socket-Based Activation</title>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2>
|
||||||
|
<title>Bus-Based Activation</title>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2>
|
||||||
|
<title>Path-Based Activation</title>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<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> 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.</para></listitem>
|
||||||
|
|
||||||
</orderedlist>
|
</orderedlist>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
|
|
||||||
<refsect2>
|
|
||||||
<title>Bus Activation</title>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2>
|
|
||||||
<title>Socket Activation</title>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2>
|
|
||||||
<title>Writing Service Files</title>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2>
|
<refsect2>
|
||||||
<title>Installing Service Files</title>
|
<title>Installing 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=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>
|
||||||
|
|
||||||
</refsect2>
|
</refsect2>
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
@ -309,8 +583,11 @@
|
||||||
<title>See Also</title>
|
<title>See Also</title>
|
||||||
<para>
|
<para>
|
||||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</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>,
|
||||||
|
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -87,6 +87,17 @@
|
||||||
<para>If an path unit is beneath another mount
|
<para>If an path unit is beneath another mount
|
||||||
point in the file system hierarchy, a dependency
|
point in the file system hierarchy, a dependency
|
||||||
between both units is created automatically.</para>
|
between both units is created automatically.</para>
|
||||||
|
|
||||||
|
<para>Unless <varname>DefaultDependencies=</varname>
|
||||||
|
is set to <option>false</option>, path units will
|
||||||
|
implicitly have dependencies of type
|
||||||
|
<varname>Conflicts=</varname> and
|
||||||
|
<varname>Before=</varname> on
|
||||||
|
<filename>shutdown.target</filename>. These ensure
|
||||||
|
that path units are terminated cleanly prior to system
|
||||||
|
shutdown. Only path units involved with early boot or
|
||||||
|
late system shutdown should disable this
|
||||||
|
option.</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
|
|
||||||
|
|
@ -64,27 +64,44 @@
|
||||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
for the common options of all unit configuration
|
for the common options of all unit configuration
|
||||||
files. The common configuration items are configured
|
files. The common configuration items are configured
|
||||||
in the generic [Unit] and [Install] sections. The
|
in the generic <literal>[Unit]</literal> and
|
||||||
service specific configuration options are configured
|
<literal>[Install]</literal> sections. The service
|
||||||
in the [Service] section.</para>
|
specific configuration options are configured in the
|
||||||
|
<literal>[Service]</literal> section.</para>
|
||||||
|
|
||||||
<para>Additional options are listed in
|
<para>Additional options are listed in
|
||||||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
|
||||||
which define the execution environment the commands
|
which define the execution environment the commands
|
||||||
are executed in.</para>
|
are executed in.</para>
|
||||||
|
|
||||||
|
<para>Unless <varname>DefaultDependencies=</varname>
|
||||||
|
is set to <option>false</option>, service units will
|
||||||
|
implicitly have dependencies of type
|
||||||
|
<varname>Requires=</varname> and
|
||||||
|
<varname>After=</varname> on
|
||||||
|
<filename>basic.target</filename> as well as
|
||||||
|
dependencies of type <varname>Conflicts=</varname> and
|
||||||
|
<varname>Before=</varname> on
|
||||||
|
<filename>shutdown.target</filename>. These ensure
|
||||||
|
that normal service units pull in basic system
|
||||||
|
initialization, and are terminated cleanly prior to
|
||||||
|
system shutdown. Only services involved with early
|
||||||
|
boot or late system shutdown should disable this
|
||||||
|
option.</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Options</title>
|
<title>Options</title>
|
||||||
|
|
||||||
<para>Service files must include a [Service] section,
|
<para>Service files must include a
|
||||||
which carries information about the service and the
|
<literal>[Service]</literal> section, which carries
|
||||||
process it supervises. A number of options that may be
|
information about the service and the process it
|
||||||
used in this section are shared with other unit
|
supervises. A number of options that may be used in
|
||||||
types. These options are documented in
|
this section are shared with other unit types. These
|
||||||
|
options are documented in
|
||||||
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
|
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
|
||||||
options specific to the [Service] section of service
|
options specific to the <literal>[Service]</literal>
|
||||||
units are the following:</para>
|
section of service units are the following:</para>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
|
@ -143,14 +160,18 @@
|
||||||
|
|
||||||
<para>Behaviour of
|
<para>Behaviour of
|
||||||
<option>dbus</option> is similar to
|
<option>dbus</option> is similar to
|
||||||
<option>simple</option>, however it
|
<option>simple</option>, however it is
|
||||||
is expected that the daemon acquires a
|
expected that the daemon acquires a
|
||||||
name on the D-Bus bus, as configured
|
name on the D-Bus bus, as configured
|
||||||
by
|
by
|
||||||
<varname>BusName=</varname>. systemd
|
<varname>BusName=</varname>. systemd
|
||||||
will proceed starting follow-up units
|
will proceed starting follow-up units
|
||||||
after the D-Bus bus name has been
|
after the D-Bus bus name has been
|
||||||
acquired.</para>
|
acquired. Service units with this
|
||||||
|
option configured implicitly have
|
||||||
|
dependencies on the
|
||||||
|
<filename>dbus.target</filename>
|
||||||
|
unit.</para>
|
||||||
|
|
||||||
<para>Behaviour of
|
<para>Behaviour of
|
||||||
<option>notify</option> is similar to
|
<option>notify</option> is similar to
|
||||||
|
|
@ -163,10 +184,13 @@
|
||||||
starting follow-up units after this
|
starting follow-up units after this
|
||||||
notification message has been sent. If
|
notification message has been sent. If
|
||||||
this option is used
|
this option is used
|
||||||
<option>NotifyAccess=</option> (see
|
<varname>NotifyAccess=</varname> (see
|
||||||
below) must be set to open access to
|
below) must be set to open access to
|
||||||
the notification socket provided by
|
the notification socket provided by
|
||||||
systemd.</para>
|
systemd. If
|
||||||
|
<varname>NotifyAccess=</varname> is not
|
||||||
|
set, it will be implicitly set to
|
||||||
|
<option>main</option>.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -220,11 +244,12 @@
|
||||||
services. This option may not be
|
services. This option may not be
|
||||||
specified more than once. Optionally,
|
specified more than once. Optionally,
|
||||||
if the absolute file name is prefixed
|
if the absolute file name is prefixed
|
||||||
with @, the second token will be
|
with <literal>@</literal>, the second
|
||||||
passed as argv[0] to the executed
|
token will be passed as
|
||||||
process, followed by the further
|
<literal>argv[0]</literal> to the
|
||||||
arguments specified. Unless
|
executed process, followed by the
|
||||||
<option>Type=forking</option> is set,
|
further arguments specified. Unless
|
||||||
|
<varname>Type=forking</varname> is set,
|
||||||
the process started via this command
|
the process started via this command
|
||||||
line will be considered the main
|
line will be considered the main
|
||||||
process of the
|
process of the
|
||||||
|
|
@ -312,7 +337,7 @@
|
||||||
forcibly via SIGTERM, and after
|
forcibly via SIGTERM, and after
|
||||||
another delay of this time with
|
another delay of this time with
|
||||||
SIGKILL. (See
|
SIGKILL. (See
|
||||||
<option>KillMode=</option>
|
<varname>KillMode=</varname>
|
||||||
below.) Takes a unit-less value in seconds, or a
|
below.) Takes a unit-less value in seconds, or a
|
||||||
time span value such as "5min
|
time span value such as "5min
|
||||||
20s". Pass 0 to disable the timeout
|
20s". Pass 0 to disable the timeout
|
||||||
|
|
@ -450,7 +475,7 @@
|
||||||
<para>Processes will first be
|
<para>Processes will first be
|
||||||
terminated via SIGTERM. If then after
|
terminated via SIGTERM. If then after
|
||||||
a delay (configured via the
|
a delay (configured via the
|
||||||
<option>TimeoutSec=</option> option)
|
<varname>TimeoutSec=</varname> option)
|
||||||
processes still remain, the
|
processes still remain, the
|
||||||
termination request is repeated with
|
termination request is repeated with
|
||||||
the SIGKILL signal. See
|
the SIGKILL signal. See
|
||||||
|
|
|
||||||
|
|
@ -95,6 +95,21 @@
|
||||||
which services are instantiated for each incoming
|
which services are instantiated for each incoming
|
||||||
connection.</para>
|
connection.</para>
|
||||||
|
|
||||||
|
<para>Unless <varname>DefaultDependencies=</varname>
|
||||||
|
is set to <option>false</option>, socket units will
|
||||||
|
implicitly have dependencies of type
|
||||||
|
<varname>Requires=</varname> and
|
||||||
|
<varname>After=</varname> on
|
||||||
|
<filename>sysinit.target</filename> as well as
|
||||||
|
dependencies of type <varname>Conflicts=</varname> and
|
||||||
|
<varname>Before=</varname> on
|
||||||
|
<filename>shutdown.target</filename>. These ensure
|
||||||
|
that socket units pull in basic system
|
||||||
|
initialization, and are terminated cleanly prior to
|
||||||
|
system shutdown. Only sockets involved with early
|
||||||
|
boot or late system shutdown should disable this
|
||||||
|
option.</para>
|
||||||
|
|
||||||
<para>Socket units may be used to implement on-demand
|
<para>Socket units may be used to implement on-demand
|
||||||
starting of services, as well as parallelized starting
|
starting of services, as well as parallelized starting
|
||||||
of services.</para>
|
of services.</para>
|
||||||
|
|
|
||||||
|
|
@ -51,6 +51,7 @@
|
||||||
<para><filename>basic.target</filename>,
|
<para><filename>basic.target</filename>,
|
||||||
<filename>ctrl-alt-del.target</filename>,
|
<filename>ctrl-alt-del.target</filename>,
|
||||||
<filename>@SPECIAL_DBUS_SERVICE@</filename>,
|
<filename>@SPECIAL_DBUS_SERVICE@</filename>,
|
||||||
|
<filename>dbus.target</filename>,
|
||||||
<filename>default.target</filename>,
|
<filename>default.target</filename>,
|
||||||
<filename>display-manager.service</filename>,
|
<filename>display-manager.service</filename>,
|
||||||
<filename>emergency.service</filename>,
|
<filename>emergency.service</filename>,
|
||||||
|
|
@ -78,8 +79,8 @@
|
||||||
<filename>sockets.target</filename>,
|
<filename>sockets.target</filename>,
|
||||||
<filename>swap.target</filename>,
|
<filename>swap.target</filename>,
|
||||||
<filename>sysinit.target</filename>,
|
<filename>sysinit.target</filename>,
|
||||||
<filename>syslog.target</filename>,
|
|
||||||
<filename>@SPECIAL_SYSLOG_SERVICE@</filename>,
|
<filename>@SPECIAL_SYSLOG_SERVICE@</filename>,
|
||||||
|
<filename>syslog.target</filename>,
|
||||||
<filename>systemd-initctl.service</filename>,
|
<filename>systemd-initctl.service</filename>,
|
||||||
<filename>systemd-initctl.socket</filename>,
|
<filename>systemd-initctl.socket</filename>,
|
||||||
<filename>systemd-logger.service</filename>,
|
<filename>systemd-logger.service</filename>,
|
||||||
|
|
@ -141,6 +142,28 @@
|
||||||
up systemd will connect to it
|
up systemd will connect to it
|
||||||
and register its
|
and register its
|
||||||
service.</para>
|
service.</para>
|
||||||
|
|
||||||
|
<para>Units should generally
|
||||||
|
avoid depending on this unit
|
||||||
|
directly and instead refer to
|
||||||
|
the
|
||||||
|
<filename>dbus.target</filename>
|
||||||
|
unit instead, which pulls this
|
||||||
|
one in directly or indirectly
|
||||||
|
via socket-based activation.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><filename>dbus.target</filename></term>
|
||||||
|
<listitem>
|
||||||
|
<para>Administrators should
|
||||||
|
ensure that this target pulls
|
||||||
|
in a service unit with the
|
||||||
|
name or alias of
|
||||||
|
<filename>@SPECIAL_DBUS_SERVICE@</filename>
|
||||||
|
(or a socket unit that
|
||||||
|
activates this
|
||||||
|
service).</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
|
@ -522,28 +545,6 @@
|
||||||
files.</para>
|
files.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
|
||||||
<term><filename>syslog.target</filename></term>
|
|
||||||
<listitem>
|
|
||||||
<para>systemd automatically
|
|
||||||
adds dependencies of type
|
|
||||||
After for this target unit to
|
|
||||||
all SysV init script service
|
|
||||||
units with an LSB header
|
|
||||||
referring to the
|
|
||||||
<literal>$syslog</literal>
|
|
||||||
facility.</para>
|
|
||||||
|
|
||||||
<para>Administrators should
|
|
||||||
ensure that this target pulls
|
|
||||||
in a service unit with the
|
|
||||||
name or alias of
|
|
||||||
<filename>@SPECIAL_SYSLOG_SERVICE@</filename>
|
|
||||||
(or a socket unit that
|
|
||||||
activates this
|
|
||||||
service).</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><filename>sysinit.target</filename></term>
|
<term><filename>sysinit.target</filename></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
|
|
@ -571,11 +572,37 @@
|
||||||
and use it for logging if it
|
and use it for logging if it
|
||||||
has been configured for
|
has been configured for
|
||||||
that.</para>
|
that.</para>
|
||||||
<para>Applications should
|
|
||||||
generally not depend on this
|
<para>Units should generally
|
||||||
service, and depend on
|
avoid depending on this unit
|
||||||
|
directly and instead refer to
|
||||||
|
the
|
||||||
<filename>syslog.target</filename>
|
<filename>syslog.target</filename>
|
||||||
instead.</para>
|
unit instead, which pulls this
|
||||||
|
one in directly or indirectly
|
||||||
|
via socket-based activation.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><filename>syslog.target</filename></term>
|
||||||
|
<listitem>
|
||||||
|
<para>systemd automatically
|
||||||
|
adds dependencies of type
|
||||||
|
After for this target unit to
|
||||||
|
all SysV init script service
|
||||||
|
units with an LSB header
|
||||||
|
referring to the
|
||||||
|
<literal>$syslog</literal>
|
||||||
|
facility.</para>
|
||||||
|
|
||||||
|
<para>Administrators should
|
||||||
|
ensure that this target pulls
|
||||||
|
in a service unit with the
|
||||||
|
name or alias of
|
||||||
|
<filename>@SPECIAL_SYSLOG_SERVICE@</filename>
|
||||||
|
(or a socket unit that
|
||||||
|
activates this
|
||||||
|
service).</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
|
|
||||||
|
|
@ -76,12 +76,22 @@
|
||||||
dependencies between units. Among other things, target
|
dependencies between units. Among other things, target
|
||||||
units are a more flexible replacement for SysV
|
units are a more flexible replacement for SysV
|
||||||
runlevels in the classic SysV init system. (And for
|
runlevels in the classic SysV init system. (And for
|
||||||
compatibility reasons there exist special
|
compatibility reasons special
|
||||||
target units such as
|
target units such as
|
||||||
<filename>runlevel3.target</filename> which are used by
|
<filename>runlevel3.target</filename> exist which are used by
|
||||||
the SysV runlevel compatibility code in systemd. See
|
the SysV runlevel compatibility code in systemd. See
|
||||||
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||||
for details).</para>
|
for details).</para>
|
||||||
|
|
||||||
|
<para>Unless
|
||||||
|
<varname>DefaultDependencies=</varname> is set to
|
||||||
|
<option>false</option>, target units will
|
||||||
|
implicitly complement all configured dependencies of type
|
||||||
|
<varname>Wants=</varname>,
|
||||||
|
<varname>Requires=</varname>,
|
||||||
|
<varname>RequiresOverridable=</varname> with
|
||||||
|
dependencies of type <varname>After=</varname>.
|
||||||
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
|
|
||||||
|
|
@ -76,6 +76,17 @@
|
||||||
matching service <filename>foo.service</filename>. The
|
matching service <filename>foo.service</filename>. The
|
||||||
unit to activate may be controlled by
|
unit to activate may be controlled by
|
||||||
<varname>Unit=</varname> (see below).</para>
|
<varname>Unit=</varname> (see below).</para>
|
||||||
|
|
||||||
|
<para>Unless <varname>DefaultDependencies=</varname>
|
||||||
|
is set to <option>false</option>, timer units will
|
||||||
|
implicitly have dependencies of type
|
||||||
|
<varname>Conflicts=</varname> and
|
||||||
|
<varname>Before=</varname> on
|
||||||
|
<filename>shutdown.target</filename>. These ensure
|
||||||
|
that timer units are stopped cleanly prior to system
|
||||||
|
shutdown. Only timer units involved with early boot or
|
||||||
|
late system shutdown should disable this
|
||||||
|
option.</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
|
|
||||||
|
|
@ -215,10 +215,10 @@
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><varname>Description=</varname></term>
|
<term><varname>Description=</varname></term>
|
||||||
<listitem><para>A free-form string
|
<listitem><para>A free-form string
|
||||||
describing the unit. This is intended for use
|
describing the unit. This is intended
|
||||||
in UIs wanting to show
|
for use in UIs to show descriptive
|
||||||
descriptive information along with the
|
information along with the unit
|
||||||
unit name.</para></listitem>
|
name.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
|
@ -451,6 +451,34 @@
|
||||||
<option>false</option>.</para></listitem>
|
<option>false</option>.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>DefaultDependencies=</varname></term>
|
||||||
|
|
||||||
|
<listitem><para>Takes a boolean
|
||||||
|
argument. If <option>true</option>
|
||||||
|
(the default), a few default
|
||||||
|
dependencies will implicitly be
|
||||||
|
created for the unit. The actual
|
||||||
|
dependencies created depend on the
|
||||||
|
unit type. For example, for service
|
||||||
|
units, these dependencies ensure that
|
||||||
|
the service is started only after
|
||||||
|
basic system initialization is
|
||||||
|
complete and is properly terminated on
|
||||||
|
system shutdown. See the respective
|
||||||
|
man pages for details. Generally, only
|
||||||
|
services involved with early boot or
|
||||||
|
late shutdown should set this option
|
||||||
|
to <option>false</option>. It is
|
||||||
|
highly recommended to leave this
|
||||||
|
option enabled for the majority of
|
||||||
|
common units. If set to
|
||||||
|
<option>false</option> this option
|
||||||
|
does not disable all implicit
|
||||||
|
dependencies, just non-essential
|
||||||
|
ones.</para></listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
||||||
<para>Unit file may include a [Install] section, which
|
<para>Unit file may include a [Install] section, which
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue