Bug#1082643: daemon.7: Some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Mon Sep 23 22:25:20 BST 2024
Package: systemd
Version: 256.6-1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-]groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
troff: backtrace: file '<stdin>':844
troff:<stdin>:844: warning: [page 7, 4.4i]: cannot break line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.10.9-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages systemd depends on:
ii libacl1 2.3.2-2
ii libapparmor1 3.1.7-1+b1
ii libaudit1 1:3.1.2-4+b1
ii libblkid1 2.40.2-8
ii libc6 2.40-2
ii libcap2 1:2.66-5
ii libmount1 2.40.2-8
ii libpam0g 1.5.3-7
ii libseccomp2 2.5.5-1+b1
ii libselinux1 3.7-3
ii libssl3t64 3.3.2-1
ii libsystemd-shared 256.6-1
ii libsystemd0 256.6-1
ii mount 2.40.2-8
Versions of packages systemd recommends:
ii dbus [default-dbus-system-bus] 1.14.10-4+b1
ii libzstd1 1.5.6+dfsg-1
pn linux-sysctl-defaults <none>
pn systemd-cryptsetup <none>
pn systemd-timesyncd | time-daemon <none>
Versions of packages systemd suggests:
ii libcryptsetup12 2:2.7.5-1
ii libgcrypt20 1.11.0-6
ii libidn2-0 2.3.7-2
ii liblz4-1 1.9.4-3
ii liblzma5 5.6.2-2
pn libtss2-rc0t64 <none>
pn libtss2-tcti-device0 <none>
pn polkitd <none>
pn systemd-boot <none>
pn systemd-container <none>
pn systemd-homed <none>
pn systemd-repart <none>
pn systemd-resolved <none>
pn systemd-userdbd <none>
Versions of packages systemd is related to:
pn dbus-user-session <none>
pn dracut <none>
ii initramfs-tools 0.145
pn libnss-systemd <none>
pn libpam-systemd <none>
ii udev 256.6-1
-- no debconf information
-------------- next part --------------
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of \'nroff -mandoc\'
Add the option \'-t\', if the file contains a table.
Read the output of \'diff -u\' with \'less -R\' or similar.
-.-.
If \'man\' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint daemon.7": (possibly shortened list)
mandoc: daemon.7:2:18: WARNING: missing date, using "": TH
mandoc: daemon.7:25:2: WARNING: skipping paragraph macro: PP after SH
mandoc: daemon.7:26:335: STYLE: input text line longer than 80 bytes: A daemon is a servic...
mandoc: daemon.7:29:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:30:257: STYLE: input text line longer than 80 bytes: When a traditional S...
mandoc: daemon.7:40:278: STYLE: input text line longer than 80 bytes: Close all open file ...
mandoc: daemon.7:41:91: STYLE: input text line longer than 80 bytes: /proc/self/fd, with ...
mandoc: daemon.7:55:125: STYLE: input text line longer than 80 bytes: Reset all signal han...
mandoc: daemon.7:81:122: STYLE: input text line longer than 80 bytes: Sanitize the environ...
mandoc: daemon.7:119:269: STYLE: input text line longer than 80 bytes: again, to ensure tha...
mandoc: daemon.7:132:189: STYLE: input text line longer than 80 bytes: in the first child, ...
mandoc: daemon.7:159:85: STYLE: input text line longer than 80 bytes: and suchlike directl...
mandoc: daemon.7:170:170: STYLE: input text line longer than 80 bytes: In the daemon proces...
mandoc: daemon.7:184:318: STYLE: input text line longer than 80 bytes: (for a hypothetical ...
mandoc: daemon.7:206:205: STYLE: input text line longer than 80 bytes: From the daemon proc...
mandoc: daemon.7:221:96: STYLE: input text line longer than 80 bytes: in the original proc...
mandoc: daemon.7:223:114: STYLE: input text line longer than 80 bytes: happens after initia...
mandoc: daemon.7:230:297: STYLE: input text line longer than 80 bytes: A daemon that needs ...
mandoc: daemon.7:232:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:233:173: STYLE: input text line longer than 80 bytes: Modern services for ...
mandoc: daemon.7:235:409: STYLE: input text line longer than 80 bytes: For developing a new...
mandoc: daemon.7:237:336: STYLE: input text line longer than 80 bytes: Note that new\-style...
mandoc: daemon.7:253:110: STYLE: input text line longer than 80 bytes: If applicable, the d...
mandoc: daemon.7:287:110: STYLE: input text line longer than 80 bytes: is received, reload ...
mandoc: daemon.7:302:204: STYLE: input text line longer than 80 bytes: Provide a correct ex...
mandoc: daemon.7:314:149: STYLE: input text line longer than 80 bytes: If possible and appl...
mandoc: daemon.7:327:103: STYLE: input text line longer than 80 bytes: unit file that carri...
mandoc: daemon.7:340:360: STYLE: input text line longer than 80 bytes: As much as possible,...
mandoc: daemon.7:353:461: STYLE: input text line longer than 80 bytes: If D\-Bus is used, m...
mandoc: daemon.7:364:487: STYLE: input text line longer than 80 bytes: If your daemon provi...
mandoc: daemon.7:375:162: STYLE: input text line longer than 80 bytes: If the service opens...
mandoc: daemon.7:391:117: STYLE: input text line longer than 80 bytes: call to log directly...
mandoc: daemon.7:394:110: STYLE: input text line longer than 80 bytes: (for log level 4 "WA...
mandoc: daemon.7:410:133: STYLE: input text line longer than 80 bytes: As new\-style daemon...
mandoc: daemon.7:414:103: STYLE: input text line longer than 80 bytes: calls that possibly ...
mandoc: daemon.7:420:2: WARNING: skipping paragraph macro: PP after SH
mandoc: daemon.7:421:235: STYLE: input text line longer than 80 bytes: New\-style init syst...
mandoc: daemon.7:423:960: STYLE: input text line longer than 80 bytes: might get activated ...
mandoc: daemon.7:425:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:426:138: STYLE: input text line longer than 80 bytes: Old\-style daemons a...
mandoc: daemon.7:429:190: STYLE: input text line longer than 80 bytes: In systemd, if the d...
mandoc: daemon.7:434:84: STYLE: input text line longer than 80 bytes: graphical\&.target, ...
mandoc: daemon.7:442:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:443:1321: STYLE: input text line longer than 80 bytes: In order to maximize...
mandoc: daemon.7:445:250: STYLE: input text line longer than 80 bytes: New\-style daemons w...
mandoc: daemon.7:456:116: STYLE: input text line longer than 80 bytes: directive in the [In...
mandoc: daemon.7:458:117: STYLE: input text line longer than 80 bytes: is set, the necessar...
mandoc: daemon.7:465:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:466:392: STYLE: input text line longer than 80 bytes: When the D\-Bus IPC ...
mandoc: daemon.7:468:167: STYLE: input text line longer than 80 bytes: directive in these s...
mandoc: daemon.7:472:162: STYLE: input text line longer than 80 bytes: rtkit\-daemon\&.serv...
mandoc: daemon.7:474:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:475:393: STYLE: input text line longer than 80 bytes: Often, daemons that ...
mandoc: daemon.7:476:224: STYLE: input text line longer than 80 bytes: "systemd"\&. Like an...
mandoc: daemon.7:480:138: STYLE: input text line longer than 80 bytes: for details\&. Often...
mandoc: daemon.7:482:109: STYLE: input text line longer than 80 bytes: from all the various...
mandoc: daemon.7:484:101: STYLE: input text line longer than 80 bytes: from that target\&. ...
mandoc: daemon.7:494:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:495:339: STYLE: input text line longer than 80 bytes: Often, runtime of da...
mandoc: daemon.7:500:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:501:172: STYLE: input text line longer than 80 bytes: Some daemons that im...
mandoc: daemon.7:506:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:507:263: STYLE: input text line longer than 80 bytes: Other forms of activ...
mandoc: daemon.7:509:195: STYLE: input text line longer than 80 bytes: units when a specifi...
mandoc: daemon.7:515:919: STYLE: input text line longer than 80 bytes: for details)\&. This...
mandoc: daemon.7:521:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:522:89: STYLE: input text line longer than 80 bytes: When writing systemd...
mandoc: daemon.7:534:83: STYLE: input text line longer than 80 bytes: setting in service f...
mandoc: daemon.7:585:163: STYLE: input text line longer than 80 bytes: Normally, little if ...
mandoc: daemon.7:587:94: STYLE: input text line longer than 80 bytes: or names introduced ...
mandoc: daemon.7:598:101: STYLE: input text line longer than 80 bytes: Make sure to include...
mandoc: daemon.7:612:2: WARNING: skipping paragraph macro: PP after SS
mandoc: daemon.7:615:112: STYLE: input text line longer than 80 bytes: during package build...
mandoc: daemon.7:619:195: STYLE: input text line longer than 80 bytes: (for user services)\...
mandoc: daemon.7:621:98: STYLE: input text line longer than 80 bytes: by the administrator...
mandoc: daemon.7:629:137: STYLE: input text line longer than 80 bytes: are recommended to u...
mandoc: daemon.7:655:258: STYLE: input text line longer than 80 bytes: This snippet allows ...
mandoc: daemon.7:675:98: STYLE: input text line longer than 80 bytes: Finally, unit files ...
mandoc: daemon.7:694:278: STYLE: input text line longer than 80 bytes: file, use snippets l...
mandoc: daemon.7:747:93: STYLE: input text line longer than 80 bytes: expect the names of ...
mandoc: daemon.7:753:207: STYLE: input text line longer than 80 bytes: To facilitate upgrad...
mandoc: daemon.7:768:296: STYLE: input text line longer than 80 bytes: Where 0\&.47\&.11\-1...
mandoc: daemon.7:770:167: STYLE: input text line longer than 80 bytes: is a command specifi...
mandoc: daemon.7:772:2: WARNING: skipping paragraph macro: PP after SH
mandoc: daemon.7:773:302: STYLE: input text line longer than 80 bytes: Since new\-style ini...
mandoc: daemon.7:785:208: STYLE: input text line longer than 80 bytes: If not already imple...
mandoc: daemon.7:796:87: STYLE: input text line longer than 80 bytes: If the daemon offers...
mandoc: daemon.7:798:182: STYLE: input text line longer than 80 bytes: sockets, consider im...
mandoc: daemon.7:800:83: STYLE: input text line longer than 80 bytes: is checked for alrea...
mandoc: daemon.7:802:147: STYLE: input text line longer than 80 bytes: returns a positive v...
mandoc: daemon.7:804:512: STYLE: input text line longer than 80 bytes: sockets used in the ...
mandoc: daemon.7:815:205: STYLE: input text line longer than 80 bytes: Write and install a ...
mandoc: daemon.7:826:129: STYLE: input text line longer than 80 bytes: If the daemon expose...
mandoc: daemon.7:829:2: WARNING: skipping paragraph macro: PP after SH
mandoc: daemon.7:830:93: STYLE: input text line longer than 80 bytes: It is recommended to...
mandoc: daemon.7:833:2: WARNING: skipping paragraph macro: PP after SH
-.-.
Strings longer than 3/4 of a standard line length (80)
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
839 \%http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
844 \%https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
-.-.
Test nr. 29:
Wrong distance between sentences in the input file.
Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").
The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.
Remember coding: Only one command ("sentence") on each (logical) line.
E-mail: Easier to quote exactly the relevant lines.
Generally: Easier to edit the sentence.
Patches: Less unaffected text.
Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B.
The number of lines affected can be too large to be in a patch.
26: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
27:\fBsystemd\fR(1)\&. This manual page covers both schemes, and in particular includes recommendations for daemons that shall be included in the systemd init system\&.
30: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 (see below), and should only be implemented if compatibility with SysV is essential\&.
40:Close all open file descriptors except standard input, output, and error (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
55:Reset all signal handlers to their default\&. This is best done by iterating through the available signals up to the limit of
119:again, to ensure that the daemon can never re\-acquire a terminal again\&. (This is relevant if the program \(em and all its dependencies \(em does not carefully specify `O_NOCTTY` on each and every single `open()` call that might potentially open a TTY device node\&.)
132:in the first child, so that only the second child (the actual daemon process) stays around\&. This ensures that the daemon process is re\-parented to init/PID 1, as all daemons should be\&.
184:(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 it is verified at the same time that the PID previously stored in the PID file no longer exists or belongs to a foreign process\&.
206: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
221:in the original process\&. The process that invoked the daemon must be able to rely on that this
230:A daemon that needs to provide compatibility with SysV systems should implement the scheme pointed out above\&. However, it is recommended to make this behavior optional and configurable via a command line argument to ease debugging as well as to simplify integration into systems using systemd\&.
233: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\&.
235: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 service manager, it is recommended not to execute them when run as new\-style service\&.
237:Note that new\-style init systems guarantee execution of daemon processes in a clean process context: 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, with standard input connected to
241:logging service, unless otherwise configured\&. The umask is reset\&.
271:is received, shut down the daemon and exit cleanly\&. A
287:is received, reload the configuration files, if this applies\&. This should be combined with notifications via
302:Provide a correct exit code from the main daemon process, as this is used by the service manager to detect service errors and problems\&. It is recommended to follow the exit code scheme as defined in the
327:unit file that carries information about starting, stopping and otherwise maintaining the daemon\&. See
340:As much as possible, rely on the service manager\*(Aqs functionality to limit the access of the daemon to files, services, and other resources, i\&.e\&. in the case of systemd, rely on systemd\*(Aqs resource limit control instead of implementing your own, rely on systemd\*(Aqs privilege dropping code instead of implementing it in the daemon, and so on\&. See
353:If D\-Bus is used, make your daemon bus\-activatable by 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 \(em 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\&. See below for details\&.
364: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 parallelization 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\&. See below for details\&.
392:\fBfprintf()\fR, which is then forwarded to syslog\&. If log levels are necessary, these can be encoded by prefixing individual log lines with strings like
396:level system\&. For details, see
421:New\-style init systems provide multiple additional mechanisms to activate services, as detailed below\&. It is common that services are configured to be activated via more than one mechanism at the same time\&. An example for systemd:
423:might get activated either when Bluetooth hardware is plugged in, or when an application accesses its programming interfaces via D\-Bus\&. Or, a print server daemon might get activated when traffic arrives at an IPP port, or when a printer is plugged in, or when a file is queued in the printer spool directory\&. Even for services that are intended to be started on system bootup unconditionally, it is a good idea to implement some of the various activation schemes outlined below, in order to maximize parallelization\&. If a daemon implements a D\-Bus service or listening socket, implementing the full bus and socket activation scheme allows starting of the daemon with its clients in parallel (which speeds up boot\-up), since all its 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 is completed\&.
427:\m[blue]\fBLSB Linux Standard Base Core Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. This method of 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 scripts in the boot process\&. New\-style init systems generally use updated versions of activation, both during boot\-up and during runtime and using more minimal service description files\&.
434:graphical\&.target, which are normally used as boot targets at system startup\&. See
443:In order to maximize the possible parallelization and robustness and simplify configuration and development, it is recommended for all new\-style daemons that communicate via listening sockets to use socket\-based activation\&. In a socket\-based activation scheme, the creation and binding of the listening socket as primary communication channel of daemons to local (and sometimes remote) clients is moved out of the daemon code and into the service manager\&. Based on per\-daemon configuration, the service manager installs the sockets and then hands them off to the spawned process as soon as the respective daemon is to be started\&. Optionally, activation of the service can be delayed until the first inbound traffic arrives at the socket to implement on\-demand 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 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 client request at all (the latter is particularly true for state\-less protocols, such as DNS or syslog), because the socket stays bound and accessible during the restart, and all requests are queued while the daemon cannot process them\&.
445:New\-style daemons which support socket activation must be able to receive their sockets from the service manager instead of creating and binding them themselves\&. For details about the programming interfaces for this scheme provided by systemd, see
448:\fBsd-daemon\fR(3)\&. For details about porting existing daemons to socket\-based activation, see below\&. With minimal effort, it is possible to implement socket\-based activation in addition to traditional internal socket creation in the same codebase in order to support both new\-style and old\-style init systems from the same daemon binary\&.
453:\fBsystemd.socket\fR(5)\&. When configuring socket units for socket\-based activation, it is essential that all listening sockets are pulled in by the special target unit
454:sockets\&.target\&. It is recommended to place a
456:directive in the [Install] section to automatically add such a dependency on installation of a socket unit\&. Unless
458:is set, the necessary ordering dependencies are implicitly created for all socket units\&. For more information about
460:\fBsystemd.special\fR(7)\&. It is not necessary or recommended to place any additional dependencies on socket units (for example from
466:When the D\-Bus IPC system is used for communication with clients, new\-style daemons should use bus activation so that they are automatically activated when a client application accesses their IPC interfaces\&. This is configured in D\-Bus service files (not to be confused with systemd service unit files!)\&. To ensure that D\-Bus uses systemd to start\-up and maintain the daemon, use the
468:directive in these service files to configure the matching systemd service for a D\-Bus service\&. e\&.g\&.: For a D\-Bus service whose D\-Bus activation file is named
472:rtkit\-daemon\&.service\&. This is needed to make sure that the daemon is started in a race\-free fashion when activated via multiple mechanisms simultaneously\&.
475:Often, daemons that manage a particular type of hardware should be activated only when 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
476:"systemd"\&. Like any other kind of unit, they may then pull in other units when activated (i\&.e\&. plugged in) and thus implement device\-based activation\&. systemd dependencies may be encoded in the udev database via the
478:property\&. See
480:for details\&. Often, it is nicer to pull in services from devices only indirectly via dedicated targets\&. Example: Instead of pulling in
484:from that target\&. This provides for nicer abstraction and gives administrators the option to enable
495:Often, runtime of daemons processing spool files or directories (such as a printing system) can be delayed until these file system objects change state, or become non\-empty\&. New\-style init systems provide a way to bind service activation to file system changes\&. systemd implements this scheme via path\-based activation configured in
501:Some daemons that implement clean\-up jobs that are intended to be executed in regular intervals benefit from timer\-based activation\&. In systemd, this is implemented via
507:Other forms of activation have been suggested and implemented in some systems\&. However, there are often simpler or better alternatives, or they can be put together of combinations of the schemes above\&. Example: Sometimes, it appears useful to start daemons or
509:units when a specific IP address is configured on a network interface, because network sockets shall be bound to the address\&. However, an alternative to implement this is by utilizing the Linux
515:for details)\&. This option, when enabled, allows sockets to be bound to a non\-local, not configured IP address, and hence allows bindings to a particular IP address before it actually becomes available, making such an explicit dependency to the configured address redundant\&. Another often suggested trigger for service activation is low system load\&. However, here too, a more convincing approach might be to make proper use of features of the operating system, in particular, the CPU or I/O scheduler of Linux\&. Instead of scheduling jobs from userspace based on monitoring the OS scheduler, it is advisable to leave the scheduling of processes to the OS scheduler itself\&. systemd provides fine\-grained access to the CPU and I/O schedulers\&. If a process executed by the service manager shall not negatively impact the amount of CPU or I/O bandwidth available to other processes, it should be configured with
518:\fIIOSchedulingClass=idle\fR\&. Optionally, this may be combined with timer\-based activation to schedule background jobs during runtime and with minimal impact on the system, and remove it from the boot phase itself\&.
534:setting in service files\&. But if you do, make sure to set the PID file path using
535:\fIPIDFile=\fR\&. See
585: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
598:Make sure to include an [Install] section including installation information for the unit file\&. See
600:for details\&. To activate your service on boot, make sure to add a
604:directive\&. To activate your socket on boot, make sure to add
605:\fIWantedBy=sockets\&.target\fR\&. Usually, you also want to make sure that when your service is installed, your socket is installed too, hence add
619:(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\&.
655: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 user unit directory is left as an exercise for the reader\&.)
694: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\&.
768: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
770: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\&.
773: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 so offers additional functionality to the daemons as well as simplifying integration into new\-style init systems\&.
785: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\&.
798: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
800:is checked for already passed sockets first\&. If sockets are passed (i\&.e\&. when
802:returns a positive value), skip the socket creation step and use the passed sockets\&. Secondly, ensure that the file system socket nodes for local
804: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 service manager 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 sockets are passed\&.
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of an option in UTF-8 text.
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
839:\%http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':844
troff:<stdin>:844: warning: [page 7, 4.4i]: cannot break line
-------------- next part --------------
--- daemon.7 2024-09-23 20:28:32.118948785 +0000
+++ daemon.7.new 2024-09-23 21:04:05.123978574 +0000
@@ -22,11 +22,9 @@
.SH "NAME"
daemon \- Writing and packaging system daemons
.SH "DESCRIPTION"
-.PP
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
\fBsystemd\fR(1)\&. This manual page covers both schemes, and in particular includes recommendations for daemons that shall be included in the systemd init system\&.
.SS "SysV Daemons"
-.PP
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 (see below), and should only be implemented if compatibility with SysV is essential\&.
.sp
.RS 4
@@ -229,7 +227,6 @@ function should not be used, as it imple
.PP
A daemon that needs to provide compatibility with SysV systems should implement the scheme pointed out above\&. However, it is recommended to make this behavior optional and configurable via a command line argument to ease debugging as well as to simplify integration into systems using systemd\&.
.SS "New\-Style Daemons"
-.PP
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\&.
.PP
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 service manager, it is recommended not to execute them when run as new\-style service\&.
@@ -417,12 +414,10 @@ calls that possibly reference a TTY devi
These recommendations are similar but not identical to the
\m[blue]\fBApple MacOS X Daemon Requirements\fR\m[]\&\s-2\u[2]\d\s+2\&.
.SH "ACTIVATION"
-.PP
New\-style init systems provide multiple additional mechanisms to activate services, as detailed below\&. It is common that services are configured to be activated via more than one mechanism at the same time\&. An example for systemd:
bluetoothd\&.service
might get activated either when Bluetooth hardware is plugged in, or when an application accesses its programming interfaces via D\-Bus\&. Or, a print server daemon might get activated when traffic arrives at an IPP port, or when a printer is plugged in, or when a file is queued in the printer spool directory\&. Even for services that are intended to be started on system bootup unconditionally, it is a good idea to implement some of the various activation schemes outlined below, in order to maximize parallelization\&. If a daemon implements a D\-Bus service or listening socket, implementing the full bus and socket activation scheme allows starting of the daemon with its clients in parallel (which speeds up boot\-up), since all its 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 is completed\&.
.SS "Activation on Boot"
-.PP
Old\-style daemons are usually activated exclusively on boot (and manually by the administrator) via SysV init scripts, as detailed in the
\m[blue]\fBLSB Linux Standard Base Core Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. This method of 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 scripts in the boot process\&. New\-style init systems generally use updated versions of activation, both during boot\-up and during runtime and using more minimal service description files\&.
.PP
@@ -439,7 +434,6 @@ directories, and
\fBsystemd.special\fR(7)
for details about the two boot targets\&.
.SS "Socket\-Based Activation"
-.PP
In order to maximize the possible parallelization and robustness and simplify configuration and development, it is recommended for all new\-style daemons that communicate via listening sockets to use socket\-based activation\&. In a socket\-based activation scheme, the creation and binding of the listening socket as primary communication channel of daemons to local (and sometimes remote) clients is moved out of the daemon code and into the service manager\&. Based on per\-daemon configuration, the service manager installs the sockets and then hands them off to the spawned process as soon as the respective daemon is to be started\&. Optionally, activation of the service can be delayed until the first inbound traffic arrives at the socket to implement on\-demand 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 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 client request at all (the latter is particularly true for state\-less protocols, such as DNS or syslog), because the socket stays bound and accessible during the restart, and all requests are queued while the daemon cannot process them\&.
.PP
New\-style daemons which support socket activation must be able to receive their sockets from the service manager instead of creating and binding them themselves\&. For details about the programming interfaces for this scheme provided by systemd, see
@@ -462,7 +456,6 @@ multi\-user\&.target
or suchlike) when one is installed in
sockets\&.target\&.
.SS "Bus\-Based Activation"
-.PP
When the D\-Bus IPC system is used for communication with clients, new\-style daemons should use bus activation so that they are automatically activated when a client application accesses their IPC interfaces\&. This is configured in D\-Bus service files (not to be confused with systemd service unit files!)\&. To ensure that D\-Bus uses systemd to start\-up and maintain the daemon, use the
\fISystemdService=\fR
directive in these service files to configure the matching systemd service for a D\-Bus service\&. e\&.g\&.: For a D\-Bus service whose D\-Bus activation file is named
@@ -471,7 +464,6 @@ org\&.freedesktop\&.RealtimeKit\&.servic
in that file to bind it to the systemd service
rtkit\-daemon\&.service\&. This is needed to make sure that the daemon is started in a race\-free fashion when activated via multiple mechanisms simultaneously\&.
.SS "Device\-Based Activation"
-.PP
Often, daemons that manage a particular type of hardware should be activated only when 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
"systemd"\&. Like any other kind of unit, they may then pull in other units when activated (i\&.e\&. plugged in) and thus implement device\-based activation\&. systemd dependencies may be encoded in the udev database via the
\fISYSTEMD_WANTS=\fR
@@ -491,19 +483,16 @@ of
\fBsystemctl\fR(1)
instead of manipulating the udev ruleset\&.
.SS "Path\-Based Activation"
-.PP
Often, runtime of daemons processing spool files or directories (such as a printing system) can be delayed until these file system objects change state, or become non\-empty\&. New\-style init systems provide a way to bind service activation to file system changes\&. systemd implements this scheme via path\-based activation configured in
\&.path
units, as outlined in
\fBsystemd.path\fR(5)\&.
.SS "Timer\-Based Activation"
-.PP
Some daemons that implement clean\-up jobs that are intended to be executed in regular intervals benefit from timer\-based activation\&. In systemd, this is implemented via
\&.timer
units, as described in
\fBsystemd.timer\fR(5)\&.
.SS "Other Forms of Activation"
-.PP
Other forms of activation have been suggested and implemented in some systems\&. However, there are often simpler or better alternatives, or they can be put together of combinations of the schemes above\&. Example: Sometimes, it appears useful to start daemons or
\&.socket
units when a specific IP address is configured on a network interface, because network sockets shall be bound to the address\&. However, an alternative to implement this is by utilizing the Linux
@@ -518,7 +507,6 @@ and/or
\fIIOSchedulingClass=idle\fR\&. Optionally, this may be combined with timer\-based activation to schedule background jobs during runtime and with minimal impact on the system, and remove it from the boot phase itself\&.
.SH "INTEGRATION WITH SYSTEMD"
.SS "Writing systemd Unit Files"
-.PP
When writing systemd unit files, it is recommended to consider the following suggestions:
.sp
.RS 4
@@ -609,7 +597,6 @@ foo\&.service, for a hypothetical progra
foo\&.
.RE
.SS "Installing systemd Service Files"
-.PP
At the build installation time (e\&.g\&.
\fBmake install\fR
during package build), packages are recommended to install their systemd unit files in the directory returned by
@@ -769,7 +756,6 @@ Where 0\&.47\&.11\-1 is the first packag
\fBchkconfig\fR
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\&.
.SH "PORTING EXISTING DAEMONS"
-.PP
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 so offers additional functionality to the daemons as well as simplifying integration into new\-style init systems\&.
.PP
To port an existing SysV compatible daemon, the following steps are recommended:
@@ -826,20 +812,18 @@ Write and install a systemd unit file fo
If the daemon exposes interfaces via D\-Bus, write and install a D\-Bus activation file for the service, see above for details\&.
.RE
.SH "PLACING DAEMON DATA"
-.PP
It is recommended to follow the general guidelines for placing package files, as discussed in
\fBfile-hierarchy\fR(7)\&.
.SH "SEE ALSO"
-.PP
\fBsystemd\fR(1), \fBsd-daemon\fR(3), \fBsd_listen_fds\fR(3), \fBsd_notify\fR(3), \fBdaemon\fR(3), \fBsystemd.service\fR(5), \fBfile-hierarchy\fR(7)
.SH "NOTES"
.IP " 1." 4
LSB recommendations for SysV init scripts
.RS 4
-\%http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
+\%http://refspecs.linuxbase.org/\:LSB_3.1.1/LSB\-Core\-generic/\:LSB\-Core\-generic/\:iniscrptact.html
.RE
.IP " 2." 4
Apple MacOS X Daemon Requirements
.RS 4
-\%https://developer.apple.com/library/mac/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html
+\%https://developer.apple.com/\:library/\:mac/\:documentation/\:MacOSX/\:Conceptual/\:BPSystemStartup/\:Chapters/\:CreatingLaunchdJobs.html
.RE
More information about the Pkg-systemd-maintainers
mailing list