mirror of
https://github.com/systemd/systemd.git
synced 2025-03-28 02:50:16 +03:00
man: add initial version of daemon(7)
This commit is contained in:
Lennart Poettering
parent
64ca679e69
commit
64aba792f7
@ -307,14 +307,16 @@ EXTRA_DIST += \
|
||||
|
||||
dist_man_MANS = \
|
||||
man/systemd.unit.5 \
|
||||
man/systemd.service.5
|
||||
man/systemd.service.5 \
|
||||
man/daemon.7
|
||||
|
||||
nodist_man_MANS = \
|
||||
man/systemd.special.7
|
||||
|
||||
dist_noinst_DATA = \
|
||||
man/systemd.unit.html \
|
||||
man/systemd.service.html
|
||||
man/systemd.service.html \
|
||||
man/daemon.html
|
||||
|
||||
nodist_noinst_DATA = \
|
||||
man/systemd.special.html
|
||||
@ -324,7 +326,8 @@ EXTRA_DIST += \
|
||||
man/systemd.service.xml \
|
||||
man/systemd.special.xml.in \
|
||||
man/systemd.special.7.in \
|
||||
man/systemd.special.html.in
|
||||
man/systemd.special.html.in \
|
||||
man/daemon.xml
|
||||
|
||||
systemd_SOURCES = \
|
||||
src/main.c
|
||||
|
||||
316
man/daemon.xml
Normal file
316
man/daemon.xml
Normal file
@ -0,0 +1,316 @@
|
||||
<?xml version='1.0'?> <!--*-nxml-*-->
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
|
||||
<!--
|
||||
This file is part of systemd.
|
||||
|
||||
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
|
||||
(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.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<refentry id="systemd.special">
|
||||
|
||||
<refentryinfo>
|
||||
<title>daemon</title>
|
||||
<productname>systemd</productname>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<contrib>Developer</contrib>
|
||||
<firstname>Lennart</firstname>
|
||||
<surname>Poettering</surname>
|
||||
<email>lennart@poettering.net</email>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>daemon</refentrytitle>
|
||||
<manvolnum>7</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>daemon</refname>
|
||||
<refpurpose>Writing and Packaging System Daemons</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>A daemon is a service process that runs in the
|
||||
background and supervises the system or provides
|
||||
functionality to other processes. Traditionally,
|
||||
daemons are implemented following a scheme originating
|
||||
in SysV Unix. Modern daemons should follow a simpler
|
||||
yet more powerful scheme here called "new-style"
|
||||
daemons, as implemented by systemd. </para>
|
||||
|
||||
<refsect2>
|
||||
<title>SysV Daemons</title>
|
||||
|
||||
<para>When a traditional SysV daemon
|
||||
starts, it should execute the following steps
|
||||
as part of the initialization. Note that these
|
||||
steps are unnecessary for new-style daemons,
|
||||
and should only be implemented if compatbility
|
||||
with SysV is essential.</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>Close all open file
|
||||
descriptors except STDIN, STDOUT,
|
||||
STDERR (i.e. the first three file
|
||||
descriptors 0, 1, 2). This ensures
|
||||
that no accidentally passed file
|
||||
descriptor stays around in the daemon
|
||||
process. On Linux this is best
|
||||
implemented by iterating through
|
||||
<filename>/proc/self/fd</filename>,
|
||||
with a fallback of iterating from file
|
||||
descriptor 3 to the value returned by
|
||||
getrlimit() for
|
||||
RLIMIT_NOFILE.</para></listitem>
|
||||
|
||||
<listitem><para>Reset all signal
|
||||
handlers to their default. This is
|
||||
best done by iterating through the
|
||||
available signals up to the limit of
|
||||
_NSIG and resetting them to
|
||||
SIG_DFL.</para></listitem>
|
||||
|
||||
<listitem><para>Reset the signal mask
|
||||
using sigprocmask().</para></listitem>
|
||||
|
||||
<listitem><para>Call fork(),
|
||||
to create a background
|
||||
process.</para></listitem>
|
||||
|
||||
<listitem><para>In the child, call
|
||||
setsid() to detach from any terminal
|
||||
and create an independent
|
||||
session.</para></listitem>
|
||||
|
||||
<listitem><para>In the child, call
|
||||
fork() again, to ensure the daemon can
|
||||
never re-aquire a terminal
|
||||
again.</para></listitem>
|
||||
|
||||
<listitem><para>Call exit() in the
|
||||
first child, so that only the second
|
||||
child (the actual daemon process)
|
||||
stays around. This ensures that the
|
||||
daemon process is reparented to
|
||||
init/PID 1, as all daemons should
|
||||
be.</para></listitem>
|
||||
|
||||
<listitem><para>In the daemon process,
|
||||
connect <filename>/dev/null</filename>
|
||||
to STDIN, STDOUT,
|
||||
STDERR.</para></listitem>
|
||||
|
||||
<listitem><para>In the daemon process,
|
||||
reset the umask to 0, so that the file
|
||||
modes passed to open(), mkdir() and
|
||||
suchlike directly control the access
|
||||
mode of the created files and
|
||||
directories.</para></listitem>
|
||||
|
||||
<listitem><para>In the daemon process,
|
||||
change the current directory to the
|
||||
root directory (/), in order to avoid
|
||||
that the daemon involuntarily
|
||||
blocks mount points from being
|
||||
unmounted.</para></listitem>
|
||||
|
||||
<listitem><para>In the daemon process,
|
||||
drop privileges, if possible and
|
||||
applicable.</para></listitem>
|
||||
|
||||
<listitem><para>From the daemon
|
||||
process notify the original process
|
||||
started that initialization is
|
||||
complete. This can be implemented via
|
||||
an unnamed pipe or similar
|
||||
communication channel that is created
|
||||
before the first fork() and available
|
||||
in both processes.</para></listitem>
|
||||
|
||||
<listitem><para>Call exit() in the
|
||||
original process. The process that
|
||||
invoked the daemon must be able to
|
||||
rely that this exit() happens after
|
||||
initialization is complete and all
|
||||
external communication channels
|
||||
established and
|
||||
accessible.</para></listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>The BSD daemon() function should not be
|
||||
used, as it does only a subset of these steps.</para>
|
||||
|
||||
<para>A daemon that needs to provide
|
||||
compatibility with SysV systems should
|
||||
implement the scheme pointed out
|
||||
above. However, it is recommended to make this
|
||||
behaviour optional and configurable via a
|
||||
command line argument, to ease debugging as
|
||||
well as to simplify integration into systems
|
||||
using systemd.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>New-Style Daemons</title>
|
||||
|
||||
<para>Modern services for Linux should be
|
||||
implemented as new-style daemons. This makes it
|
||||
easier to supervise and control them at
|
||||
runtime and simplifies their
|
||||
implementation.</para>
|
||||
|
||||
<para>For developing a new-style daemon none
|
||||
of the initialization steps recommended for
|
||||
SysV daemons need to be implemented. New-style
|
||||
init systems such as systemd make all of them
|
||||
redundant. Moreover, since some of these steps
|
||||
interfere with process monitoring, file
|
||||
descriptor passing and other functionality of
|
||||
the init system it is recommended not to
|
||||
execute them when run as new-style
|
||||
service.</para>
|
||||
|
||||
<para>It is recommended for new-style daemons
|
||||
to implement the following:</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem><para>If SIGTERM is
|
||||
received, shut down the daemon and
|
||||
exit cleanly.</para></listitem>
|
||||
|
||||
<listitem><para>If SIGHUP is received,
|
||||
reload the configuration files, if
|
||||
this applies.</para></listitem>
|
||||
|
||||
<listitem><para>Provide a correct exit
|
||||
code from the main daemon process, as
|
||||
this is used by the init system to
|
||||
detect service errors and problems. It
|
||||
is recommended to follow the exit code
|
||||
scheme as defined in LSB
|
||||
recommendations for SysV init scripts
|
||||
(http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem>
|
||||
|
||||
<listitem><para>As much as possible,
|
||||
rely on systemd's functionality to
|
||||
limit the accces of the daemon to
|
||||
files, services and other
|
||||
resources. i.e. rely on systemd's
|
||||
resource limit control instead of
|
||||
implementing your own, rely on
|
||||
systemd's privilege dropping code
|
||||
instead of implementing it in the
|
||||
daemon, and similar.</para></listitem>
|
||||
|
||||
<listitem><para>If possible and
|
||||
applicable expose the daemon's control
|
||||
interface via the D-Bus IPC system and
|
||||
grab a bus name as last step of
|
||||
initialization.</para></listitem>
|
||||
|
||||
<listitem><para>If D-Bus is used, make
|
||||
your daemon bus-activatable, via
|
||||
supplying a D-Bus service activation
|
||||
configuration file. This has multiple
|
||||
advantages: your daemon may be started
|
||||
lazily on-demand; it may be started in
|
||||
parallel to other daemons requiring it
|
||||
-- which maximizes parallelization and
|
||||
boot-up speed; your daemon can be
|
||||
restarted on failure, without losing
|
||||
any bus requests, as the bus queues
|
||||
requests for activatable
|
||||
services.</para></listitem>
|
||||
|
||||
<listitem><para>If your daemon
|
||||
provides services to other local
|
||||
processes or remote clients via a
|
||||
socket, it should be made
|
||||
socket-activatable following the
|
||||
scheme pointed out below. Like D-Bus
|
||||
activation this enables on-demand
|
||||
starting of services as well as it
|
||||
allows improved parallization of
|
||||
service start-up. Also, for state-less
|
||||
protocols (such as syslog, DNS) a
|
||||
daemon implementing socket-based
|
||||
activation can be restarted without
|
||||
losing a single
|
||||
request.</para></listitem>
|
||||
|
||||
<listitem><para>If applicable a daemon
|
||||
should notify the init system about
|
||||
startup completion or status
|
||||
updates via the sd_notify()
|
||||
interface.</para></listitem>
|
||||
|
||||
<listitem><para>Instead of using the
|
||||
syslog() call to log directly to the
|
||||
system logger, a new-style daemon may
|
||||
choose to simply log to STDERR via
|
||||
fprintf(), which is then forwarded to
|
||||
syslog by the init system. If log
|
||||
priorities are necessary these can be
|
||||
encoded by prefixing individual log
|
||||
lines with strings like "<4>"
|
||||
(for log priority 4 "WARNING" in the
|
||||
syslog priority scheme), following a
|
||||
similar style as the Linux kernel's
|
||||
printk() priority system. In fact, using
|
||||
this style of logging also enables the
|
||||
init system to optionally direct all
|
||||
application logging to the kernel log
|
||||
buffer (kmsg), as accessible via
|
||||
dmesg.</para></listitem>
|
||||
|
||||
</orderedlist>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Bus Activation</title>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Socket Activation</title>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Writing Service Files</title>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Installing Service Files</title>
|
||||
</refsect2>
|
||||
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
<para>
|
||||
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
Loading…
x
Reference in New Issue
Block a user