systemd
doco
Here, collected, are some of the errors in systemd
documentation that I've come across, and pointed out, over the years.
systemd.socket
manual page
The systemd.socket
manual page describes automatic dependencies twice, once in a "Description" section and once in an "Automatic Dependencies" section.
The two descriptions are subtly different from each other.
This is the result of Lennart Poettering adding the latter section in November 2015, without taking the superseded wording out.
systemd.unit
manual page
There are in fact seventeen places (in the absence of any overriding environment variables) where systemd
searches for system-wide unit files, as enumerated in path-lookup.c
.
There used to be nine.
For many years the systemd.unit
manual page documented just three of them.
The three directories used by generators were intentionally undocumented on the parts of the systemd writers "to not confuse administrators/users unnecessarily and to push people to install things into the same directories on all [Linux] distributions".
A further two were determined by the way that systemd is built and packaged, and left undocumented; and a further third was /usr/local/lib/systemd/system
.
Since 2018, the manual page has documented the search path twice, contradicts itself in doing so, and doesn't document all seventeen, even though it nowadays documents generator directories again. The two lists of directories are in the synopsis and in a later table. They disagree with each other, listing different directories and listing a different number of directories, the synopsis listing 11 directories and the table listing 10 directories, with 4 differences between them.
The doco has furthermore historically made, and still does make, a right old mess of documenting /usr/local/lib/systemd/system
.
This directory, always actually processed by systemd, has erroneously been erased from the doco and then only partly restored in a back and and forth by the system people over a group of directories (generators) that /usr/local/lib/systemd/system
has never been a member of.
It is not a generator directory nor is it a build-system-determined directory; but its documentation was erased by Lennart Poettering in July 2013 because "generator paths are internal implementation details". In 2018, Zbigniew Jędrzejewski-Szmek partly restored it because "control, transient, dbus config, or generator paths […] are visible to users, and they need to understand why systemd loads units from those paths", but did not re-add it to the synopsis.
A similar fate has befallen /usr/local/lib/systemd/user
and /usr/local/share/systemd/user
, used when searching for per-user unit files but at best only partly documented.
tmpfiles.d
manual page
There are five places where systemd-tmpfiles
searches for configuration files.
The tmpfiles.d
manual page gives only three of them.
A fourth is only the case where systemd is built configured to think that /lib
and /usr/lib
differ.
The fifth, /usr/local/lib/tmpfiles.d
, is undocumented.
basic.target
being required
The systemd.special
manual page states that all services (that have default dependencies in effect) require and are ordered after basic.target
.
systemd.service
manual page states that all services (that have default dependencies in effect) are ordered after basic.target
, but do not require it.
The System 5 Incompatibilities doco for systemd falsely states that "not even $HOME
or similar" environment variables are set in the execution environments of dæmons.
In fact, if a User
directive is supplied, the HOME
, LOGNAME
, and SHELL
environment variables are all constructed (by code in execute.c
) and passed to the spawned dæmon process.
This was eventually documented in the systemd.exec
manual page in September 2013 by Zbigniew Jedrzejewski-Szmek.
But the other doco has yet to be corrected.
The System 5 Incompatibilities doco for systemd falsely states that run level S
is "fake" and "distribution specific".
In fact, run level S
is documented in the System V Interface Definition, dates back to a decade before "Linux distribution" (and indeed Linux itself) was even an idea, and is the quite real single-user mode run level that was the pre-cursor to emergency and rescue modes.
The Discoverable Partitions Specification doco for systemd falsely states that the EFI partitioning scheme is "mandatory on EFI systems".
In fact, it is not; the MBR partitioning scheme can be used on EFI systems.
The Control Group Interface doco for systemd is rejected past plans for the future being falsely presented as accomplished fact.
There is nothing in the version 2 Linux control groups API that requires any such thing as a single writer; and systemd does not in fact operate as such. The version 2 control groups API has distributed management of control groups, which can be shared amongst multiple processes and to non-superusers.