X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fdaemon.xml;h=9d43353f90096eb6725913d9e9620ba1d0c19295;hp=01ab0f3b511ed655a6e44d8cc879b3a68f99b564;hb=34511ca7b166b0e89d08ff9870b0cf2624a7815f;hpb=99ffae46d38f05b6c8bc09fe29e50a507ae8b79b;ds=sidebyside diff --git a/man/daemon.xml b/man/daemon.xml index 01ab0f3b5..9d43353f9 100644 --- a/man/daemon.xml +++ b/man/daemon.xml @@ -8,16 +8,16 @@ 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 + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 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. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,7 +44,7 @@ daemon - Writing and Packaging System Daemons + Writing and packaging system daemons @@ -115,7 +115,7 @@ In the child, call fork() again, to - ensure the daemon can never re-aquire + ensure the daemon can never re-acquire a terminal again. Call exit() in the @@ -323,7 +323,7 @@ Instead of using the syslog() call to log directly to the - system logger, a new-style daemon may + system syslog service, 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 @@ -345,7 +345,7 @@ StandardError=syslog in the service unit file. For details see - sd-daemon7 + sd-daemon3 and systemd.exec5. @@ -384,7 +384,7 @@ communication channels are established already, and no request is lost because client requests will be queued by the bus system (in case of D-Bus) or the kernel (in - case of sockets), until the activation + case of sockets), until the activation is completed. @@ -397,7 +397,7 @@ url="http://refspecs.freestandards.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html">LSB Linux Standard Base Core Specification. This method of - activation is supported ubiquitiously on Linux + activation is supported ubiquitously on Linux init systems, both old-style and new-style systems. Among other issues SysV init scripts have the disadvantage of involving shell @@ -449,7 +449,7 @@ activation of daemons. However, the primary advantage of this scheme is that all providers and all consumers of the sockets can be - started in parallel as soon als all sockets + started in parallel as soon as all sockets are established. In addition to that daemons can be restarted with losing only a minimal number of client transactions or even any @@ -468,7 +468,7 @@ this scheme provided by systemd see sd_listen_fds3 and - sd-daemon7. For + sd-daemon3. For details about porting existing daemons to socket-based activation see below. With minimal effort it is possible to implement @@ -543,10 +543,10 @@ the hardware of the respective kind is plugged in or otherwise becomes available. In a new-style init system it is possible to bind - activation to hardware plug/unplug events. In systemd, - kernel devices appearing in the sysfs/udev - device tree can be exposed as units if they - are tagged with the string + activation to hardware plug/unplug events. In + systemd, kernel devices appearing in the + sysfs/udev device tree can be exposed as units + if they are tagged with the string "systemd". Like any other kind of unit they may then pull in other units when activated (i.e. Plugged in) and thus @@ -570,8 +570,9 @@ bluetoothd.service via controlling a bluetooth.target.wants/ - symlink uniformly with a tool like - systemd-install1 + symlink uniformly with a command like + enable of + systemctl1 instead of manipulating the udev ruleset. @@ -643,7 +644,7 @@ to the CPU and IO schedulers. If a process executed by the init system shall not negatively impact the amount of CPU or IO - bandwith available to other processes, it + bandwidth available to other processes, it should be configured with CPUSchedulingPolicy=idle and/or @@ -678,7 +679,8 @@ If your daemon registers a D-Bus name on the bus, make sure to use - Type=dbus if + Type=dbus in the + service file if possible. Make sure to set a @@ -704,15 +706,26 @@ system-independent. Make sure to include - an [Install] section including - installation information for the unit - file. See + an [Install] + section including installation + information for the unit file. See systemd.unit5 for details. To activate your service on boot make sure to add a WantedBy=multi-user.target or - WantedBy=graphical.target directive. + WantedBy=graphical.target + directive. To activate your socket on + boot, make sure to add + WantedBy=sockets.target. Usually + you also want to make sure that when + your service is installed your socket + is installed too, hence add + Also=foo.socket in + your service file + foo.service, for + a hypothetical program + foo. @@ -726,19 +739,20 @@ install their systemd unit files in the directory returned by pkg-config systemd - --variable=systemdsystemnunitdir - (for system services), - resp. pkg-config systemd - --variable=systemdsessionunitdir - (for session services). This will make the + --variable=systemdsystemunitdir (for + system services), resp. pkg-config + systemd + --variable=systemduserunitdir + (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. rpm -i by the administrator) symlinks should be created in the systemd configuration - directories via the - systemd-install1 + directories via the enable + command of the + systemctl1 tool, to activate them automatically on boot. @@ -753,15 +767,17 @@ 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"]) +if test "x$with_systemdsystemunitdir" != xno; then + AC_SUBST([systemdsystemunitdir], [$with_systemdsystemunitdir]) +fi +AM_CONDITIONAL(HAVE_SYSTEMD, [test -n "$with_systemdsystemunitdir" -a "x$with_systemdsystemunitdir" != xno ]) 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 + user unit directory is left as an exercise for the reader.) Additionally, to ensure that @@ -785,21 +801,73 @@ endif In the rpm8 - .spec file use a snippet like - the following to enable/disable the service - during installation/deinstallation. Consult + .spec 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: + package managers. + + At the top of the file: + + BuildRequires: systemd +%{?systemd_requires} + + And as scriptlets, further down: %post -/usr/bin/systemd-install enable foobar.service foobar.socket >/dev/null 2>&1 || : +%systemd_post foobar.service foobar.socket %preun -if [ "$1" -eq 0 ]; then - /usr/bin/systemd-install disable foobar.service foobar.socket >/dev/null 2>&1 || : +%systemd_preun foobar.service foobar.socket + +%postun +%systemd_postun + + If the service shall be restarted during + upgrades replace the + %postun scriptlet above + with the following: + + %postun +%systemd_postun_with_restart foobar.service + + Note that + %systemd_post and + %systemd_preun expect the + names of all units that are installed/removed + as arguments, separated by + spaces. %systemd_postun + expects no + arguments. %systemd_postun_with_restart + expects the units to restart as + arguments. + + 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: + + %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 + 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 + chkconfig 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. @@ -809,8 +877,8 @@ fi 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 + new style. However doing so offers additional + functionality to the daemons as well as simplifying integration into new-style init systems. To port an existing SysV compatible daemon the @@ -849,7 +917,7 @@ fi 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 + open file descriptors if sockets are passed. Write and install a systemd @@ -870,8 +938,7 @@ fi See Also systemd1, - systemd-install1, - sd-daemon7, + sd-daemon3, sd_listen_fds3, sd_notify3, daemon3,