man/daemon.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd.special">
  25
  26         <refentryinfo>
  27                 <title>daemon</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>daemon</refentrytitle>
  42                 <manvolnum>7</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>daemon</refname>
  47                 <refpurpose>Writing and Packaging System Daemons</refpurpose>
  48         </refnamediv>
  49
  50         <refsect1>
  51                 <title>Description</title>
  52
  53                 <para>A daemon is a service process that runs in the
  54                 background and supervises the system or provides
  55                 functionality to other processes. Traditionally,
  56                 daemons are implemented following a scheme originating
  57                 in SysV Unix. Modern daemons should follow a simpler
  58                 yet more powerful scheme here called "new-style"
  59                 daemons, as implemented by systemd. </para>
  60
  61                 <refsect2>
  62                         <title>SysV Daemons</title>
  63
  64                         <para>When a traditional SysV daemon
  65                         starts, it should execute the following steps
  66                         as part of the initialization. Note that these
  67                         steps are unnecessary for new-style daemons,
  68                         and should only be implemented if compatibility
  69                         with SysV is essential.</para>
  70
  71                         <orderedlist>
  72                                 <listitem><para>Close all open file
  73                                 descriptors except STDIN, STDOUT,
  74                                 STDERR (i.e. the first three file
  75                                 descriptors 0, 1, 2). This ensures
  76                                 that no accidentally passed file
  77                                 descriptor stays around in the daemon
  78                                 process. On Linux this is best
  79                                 implemented by iterating through
  80                                 <filename>/proc/self/fd</filename>,
  81                                 with a fallback of iterating from file
  82                                 descriptor 3 to the value returned by
  83                                 getrlimit() for
  84                                 RLIMIT_NOFILE.</para></listitem>
  85
  86                                 <listitem><para>Reset all signal
  87                                 handlers to their default. This is
  88                                 best done by iterating through the
  89                                 available signals up to the limit of
  90                                 _NSIG and resetting them to
  91                                 SIG_DFL.</para></listitem>
  92
  93                                 <listitem><para>Reset the signal mask
  94                                 using sigprocmask().</para></listitem>
  95
  96                                 <listitem><para>Call fork(),
  97                                 to create a background
  98                                 process.</para></listitem>
  99
 100                                 <listitem><para>In the child, call
 101                                 setsid() to detach from any terminal
 102                                 and create an independent
 103                                 session.</para></listitem>
 104
 105                                 <listitem><para>In the child, call
 106                                 fork() again, to ensure the daemon can
 107                                 never re-aquire a terminal
 108                                 again.</para></listitem>
 109
 110                                 <listitem><para>Call exit() in the
 111                                 first child, so that only the second
 112                                 child (the actual daemon process)
 113                                 stays around. This ensures that the
 114                                 daemon process is reparented to
 115                                 init/PID 1, as all daemons should
 116                                 be.</para></listitem>
 117
 118                                 <listitem><para>In the daemon process,
 119                                 connect <filename>/dev/null</filename>
 120                                 to STDIN, STDOUT,
 121                                 STDERR.</para></listitem>
 122
 123                                 <listitem><para>In the daemon process,
 124                                 reset the umask to 0, so that the file
 125                                 modes passed to open(), mkdir() and
 126                                 suchlike directly control the access
 127                                 mode of the created files and
 128                                 directories.</para></listitem>
 129
 130                                 <listitem><para>In the daemon process,
 131                                 change the current directory to the
 132                                 root directory (/), in order to avoid
 133                                 that the daemon involuntarily
 134                                 blocks mount points from being
 135                                 unmounted.</para></listitem>
 136
 137                                 <listitem><para>In the daemon process,
 138                                 drop privileges, if possible and
 139                                 applicable.</para></listitem>
 140
 141                                 <listitem><para>From the daemon
 142                                 process notify the original process
 143                                 started that initialization is
 144                                 complete. This can be implemented via
 145                                 an unnamed pipe or similar
 146                                 communication channel that is created
 147                                 before the first fork() and available
 148                                 in both processes.</para></listitem>
 149
 150                                 <listitem><para>Call exit() in the
 151                                 original process. The process that
 152                                 invoked the daemon must be able to
 153                                 rely that this exit() happens after
 154                                 initialization is complete and all
 155                                 external communication channels
 156                                 established and
 157                                 accessible.</para></listitem>
 158                         </orderedlist>
 159
 160                         <para>The BSD daemon() function should not be
 161                         used, as it does only a subset of these steps.</para>
 162
 163                         <para>A daemon that needs to provide
 164                         compatibility with SysV systems should
 165                         implement the scheme pointed out
 166                         above. However, it is recommended to make this
 167                         behaviour optional and configurable via a
 168                         command line argument, to ease debugging as
 169                         well as to simplify integration into systems
 170                         using systemd.</para>
 171                 </refsect2>
 172
 173                 <refsect2>
 174                         <title>New-Style Daemons</title>
 175
 176                         <para>Modern services for Linux should be
 177                         implemented as new-style daemons. This makes it
 178                         easier to supervise and control them at
 179                         runtime and simplifies their
 180                         implementation.</para>
 181
 182                         <para>For developing a new-style daemon none
 183                         of the initialization steps recommended for
 184                         SysV daemons need to be implemented. New-style
 185                         init systems such as systemd make all of them
 186                         redundant. Moreover, since some of these steps
 187                         interfere with process monitoring, file
 188                         descriptor passing and other functionality of
 189                         the init system it is recommended not to
 190                         execute them when run as new-style
 191                         service.</para>
 192
 193                         <para>It is recommended for new-style daemons
 194                         to implement the following:</para>
 195
 196                         <orderedlist>
 197                                 <listitem><para>If SIGTERM is
 198                                 received, shut down the daemon and
 199                                 exit cleanly.</para></listitem>
 200
 201                                 <listitem><para>If SIGHUP is received,
 202                                 reload the configuration files, if
 203                                 this applies.</para></listitem>
 204
 205                                 <listitem><para>Provide a correct exit
 206                                 code from the main daemon process, as
 207                                 this is used by the init system to
 208                                 detect service errors and problems. It
 209                                 is recommended to follow the exit code
 210                                 scheme as defined in LSB
 211                                 recommendations for SysV init scripts
 212                                 (http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html).</para></listitem>
 213
 214                                 <listitem><para>As much as possible,
 215                                 rely on systemd's functionality to
 216                                 limit the access of the daemon to
 217                                 files, services and other
 218                                 resources. i.e. rely on systemd's
 219                                 resource limit control instead of
 220                                 implementing your own, rely on
 221                                 systemd's privilege dropping code
 222                                 instead of implementing it in the
 223                                 daemon, and similar.</para></listitem>
 224
 225                                 <listitem><para>If possible and
 226                                 applicable expose the daemon's control
 227                                 interface via the D-Bus IPC system and
 228                                 grab a bus name as last step of
 229                                 initialization.</para></listitem>
 230
 231                                 <listitem><para>If D-Bus is used, make
 232                                 your daemon bus-activatable, via
 233                                 supplying a D-Bus service activation
 234                                 configuration file. This has multiple
 235                                 advantages: your daemon may be started
 236                                 lazily on-demand; it may be started in
 237                                 parallel to other daemons requiring it
 238                                 -- which maximizes parallelization and
 239                                 boot-up speed; your daemon can be
 240                                 restarted on failure, without losing
 241                                 any bus requests, as the bus queues
 242                                 requests for activatable
 243                                 services.</para></listitem>
 244
 245                                 <listitem><para>If your daemon
 246                                 provides services to other local
 247                                 processes or remote clients via a
 248                                 socket, it should be made
 249                                 socket-activatable following the
 250                                 scheme pointed out below. Like D-Bus
 251                                 activation this enables on-demand
 252                                 starting of services as well as it
 253                                 allows improved parallelization of
 254                                 service start-up. Also, for state-less
 255                                 protocols (such as syslog, DNS) a
 256                                 daemon implementing socket-based
 257                                 activation can be restarted without
 258                                 losing a single
 259                                 request.</para></listitem>
 260
 261                                 <listitem><para>If applicable a daemon
 262                                 should notify the init system about
 263                                 startup completion or status
 264                                 updates via the sd_notify()
 265                                 interface.</para></listitem>
 266
 267                                 <listitem><para>Instead of using the
 268                                 syslog() call to log directly to the
 269                                 system logger, a new-style daemon may
 270                                 choose to simply log to STDERR via
 271                                 fprintf(), which is then forwarded to
 272                                 syslog by the init system. If log
 273                                 priorities are necessary these can be
 274                                 encoded by prefixing individual log
 275                                 lines with strings like "&lt;4&gt;"
 276                                 (for log priority 4 "WARNING" in the
 277                                 syslog priority scheme), following a
 278                                 similar style as the Linux kernel's
 279                                 printk() priority system. In fact, using
 280                                 this style of logging also enables the
 281                                 init system to optionally direct all
 282                                 application logging to the kernel log
 283                                 buffer (kmsg), as accessible via
 284                                 dmesg.</para></listitem>
 285
 286                         </orderedlist>
 287                 </refsect2>
 288
 289                 <refsect2>
 290                         <title>Bus Activation</title>
 291                 </refsect2>
 292
 293                 <refsect2>
 294                         <title>Socket Activation</title>
 295                 </refsect2>
 296
 297                 <refsect2>
 298                         <title>Writing Service Files</title>
 299                 </refsect2>
 300
 301                 <refsect2>
 302                         <title>Installing Service Files</title>
 303                 </refsect2>
 304
 305         </refsect1>
 306
 307
 308         <refsect1>
 309                 <title>See Also</title>
 310                 <para>
 311                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 312                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 313                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 314                 </para>
 315         </refsect1>
 316
 317 </refentry>