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 nine places (in the absence of any overriding environment variables) where systemd searches for unit files, as enumerated in path-lookup.c. Three are documented in the systemd.unit manual page. Three are used by generators, and are 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". Two are determined by the way that systemd is built and packaged.

The remaining one (/usr/local/lib/systemd/system) is not a generator directory nor is a build-system-determined directory; but its documentation was erased by Lennart Poettering in July 2013 because "generator paths are internal implementation details".

Zbigniew Jędrzejewski-Szmek restored it in 2018 because "control, transient, dbus config, or generator paths […] are visible to users, and they need to understand why systemd loads units from those paths". /usr/local/lib/systemd/system remains not a generator directory, despite this years-long back and forth over a group of directories that it was never a member of.

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

The systemd.special manual page states that all services (that have default dependencies in effect) require and are ordered after

The systemd.service manual page states that all services (that have default dependencies in effect) are ordered after, 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.