X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fdaemon.xml;h=197138e51d97537b057052e9165c614e238e6bc0;hp=b708bdcfbaae0386342606aa6044c6fc76c4df68;hb=6e303b233beae8d189d5e4f8c58ad3fa534a087a;hpb=b4f10a5e8956d26f0bc6b9aef12846b57caee08b diff --git a/man/daemon.xml b/man/daemon.xml index b708bdcfb..197138e51 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 @@ -181,11 +181,11 @@ exit() in the original process. The process that invoked the daemon must be able to - rely that this + rely on that this exit() happens after initialization is complete and all external communication channels - established and + are established and accessible. @@ -196,7 +196,7 @@ compatibility with SysV systems should implement the scheme pointed out above. However, it is recommended to make this - behaviour optional and configurable via a + behavior optional and configurable via a command line argument, to ease debugging as well as to simplify integration into systems using systemd. @@ -271,7 +271,7 @@ for details. As much as possible, - rely on the init systemd's + rely on the init system's functionality to limit the access of the daemon to files, services and other resources. i.e. in the case of @@ -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. @@ -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 @@ -462,13 +462,13 @@ New-style daemons which support socket activation must be able to receive their - sockets from the init system, instead of of + sockets from the init system, instead of creating and binding them themselves. For details about the programming interfaces for 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=systemdsystemunitdir - (for system services), - resp. pkg-config systemd - --variable=systemdsessionunitdir - (for session services). This will make the + --variable=systemdsystemunitdir (for + system services) or 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 --realize 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 --realize 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. @@ -870,8 +938,7 @@ fi See Also systemd1, - systemd-install1, - sd-daemon7, + sd-daemon3, sd_listen_fds3, sd_notify3, daemon3,