Errata for systemd doco

Here, collected, are some of the errors in systemd documentation that I've come across, and pointed out, over the years.

Duplication and confusion in the 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.

Missing system search paths from the 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.

Missing search paths from the 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.

Contradiction on 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.

The systemd.service manual page states that all services (that have default dependencies in effect) are ordered after basic.target, but do not require it.

False statements about dæmon environments

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.

False statements about run level S

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.

False statements about the EFI partition table

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.

Fiction on the subject of control groups

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.


© Copyright 2016 Jonathan de Boyne Pollard. "Moral" rights asserted.
Permission is hereby granted to copy and to distribute this web page in its original, unmodified form as long as its last modification datestamp is preserved.