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
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
--- 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
