doc: document command candidates and the duplicate title rule

The migration guide covered a stanza at a time, which is the wrong
shape for the two idioms that repeated a whole stanza.  One of them,
several candidate binaries for one service, is now a command list.
The other, one service gated differently per platform, has no block
equivalent: those blocks share an identity because they share the
barrier condition downstream services wait for, so they cannot be
given separate titles.  For that one the guide says to split the
variants across files, or leave that file in the line-based format,
which Finit still reads.

The udevd example in services.md taught the merge-broken form, and
system/10-hotplug.conf.in pointed readers at it for their syslogd.

Also lists libConfuse among the build dependencies.  It has been
mandatory since the new .conf format landed, and build.md still said
two libraries.  And corrects the note on variable expansion: it is
${VAR} that libconfuse expands when the file is read, with
${VAR:-default} supported.  A plain $VAR reaches the service, which is
what makes `command = "syslogd -F $SYSLOGD_ARGS"` work with envfile.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg committed 2026-08-05 17:57:56 +02:00
1 parent cfae4a0e10
commit 4299ce8839
6 files changed
+147 -14

No files matched your search

+52
View File
@@ -61,6 +61,58 @@ Other run/task/service settings are:
* a leading `-` on `command` -- see
[Conditional Loading](services.md#conditional-loading)
Command Candidates
------------------
The `command` setting may list several candidates for the same
service, in which case Finit starts the first one it finds:
service udevd {
command = { "/lib/systemd/systemd-udevd", "-udevd" }
}
A candidate that is not installed is skipped without a warning, that
is the point of listing more than one. The leading `-` is read from
the candidate that wins, or from the last one when none are found, so
a block with a single command behaves as it always has.
The candidates are alternative spellings of one service, not a
fallback for a service that fails to start. Finit chooses when the
.conf file is read and does not revisit the choice.
A [`tty`](tty.md) block takes the same list, where the candidates are
the getty to run:
tty ttyAMA0 {
command = { "/sbin/agetty -L ttyAMA0 115200 vt100",
"/sbin/getty -L 115200 /dev/ttyAMA0 vt100" }
}
Duplicate Titles
----------------
The title is the service identity, so two blocks sharing a title in
one file are two declarations of one service. The parser underneath
merges them without a word, leaving a single service holding a mix of
both, so Finit rejects the file and names the title:
/etc/finit.d/hotplug.conf:12: found duplicate title 'udevd'
Nothing from a rejected file is loaded and the rest of the
configuration is unaffected.
The same title in *another* file is fine. That is how a system .conf
is overridden, the later file wins, see [Files & Layout](files.md).
Two shapes need a single identity and used to be written as repeated
declarations. One is a service with several candidate binaries, which
is now a [command list](#command-candidates). The other is a service
gated differently per platform, e.g. a syslog daemon waiting for
whichever hotplug daemon the system happens to have. For that one,
give each variant its own file, or keep them as one-liners in the
line-based format, which has no titles. The [migration
guide](migration.md) works through it.
Restarting
----------