We slowly added many many conditions over the years, and the text became
very hard to read, because all the terms were squished in one <termitem>.
This rearragnes the text into a new subsection, with minimal grammar changes
and removal of repetitions.
The description of Alias= wasn't incorrect, but it sounded like Alias= creates
a different type of dependency, while it's just a glorified way to create
symlinks. Also recommend 'preset' in addition to 'enable'.
Describe .wants/.requires dirs as equals, without implying that the [Install]
section can only be used for .wants.
The text was partially out of date (systemd-networkd.service now creates as
alias in /etc, not /usr/lib, let's just not say anything about the full path).
Before only one comparison was allowed. Let's make this more flexible:
ConditionKernelVersion = ">=4.0" "<=4.5"
Fixes#12881.
This also fixes expressions like "ConditionKernelVersion=>" which would
evaluate as true.
Originally the description of conditions was brief, so it was acceptable
to put this part at the end. But now we have a myriad conditions, and
this crucial bit of information is easy to miss.
According to the Filesystem Hierarchy Standard, "The /usr/local hierarchy is for use by the system administrator when installing software locally. It needs to be safe from being overwritten when the system software is updated". So it should not be used by installed packages.
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
No need to waste space, and uniformity is good.
$ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
From WordNet (r) 3.0 (2006) [wn]:
time-out
n 1: a brief suspension of play; "each team has two time-outs left"
From The Free On-line Dictionary of Computing (18 March 2015) [foldoc]:
timeout
A period of time after which an error condition is raised if
some event has not occured. A common example is sending a
message. If the receiver does not acknowledge the message
within some preset timeout period, a transmission error is
assumed to have occured.
The current use of literal + replaceable is pretty ugly as it usually
ends up with cgroup_disable= rendered in quotes, which looks really
weird, and this doesn't conform with others of a similar type (for
example, the earlier `DefaultDependencies=no` discussion in the same
file.
The way this is used drifted a bit from the original intent. Let's update
the description and add some examples to inspire people to texts that look
less bad during initial boot.
In the documentation for ConditionXYZ= we claimed that AssertXYZ= would
have an effect on unit state (which is wrong), while at the
documentation for AssertXYZ= we said it only has an effect on the job,
but not the unit (which is right). Let's fix this contradiction, and
only claim the latter.
Also, fix a couple of other things (for example, stop talking about a
"failure state", but let's just expressly called it "the 'failed' state",
as that's the actual name of that state.
Finally, let's emphasize again when the conditions/assertions are
executed, and that they hence are not useful to conditionalize deps.
Fixes: #10433
C.f. 287419c119ef961db487a281162ab037eba70c61: 'systemctl exit 42' can be
used to set an exit value and pulls in exit.target, which pulls in systemd-exit.service,
which calls org.fdo.Manager.Exit, which calls method_exit(), which sets the objective
to MANAGER_EXIT. Allow the same to happen through SuccessAction=exit.
v2: update for 'exit' and 'exit-force'
We would accept e.g. FailureAction=reboot-force in user units and then do an
exit in the user manager. Let's be stricter, and define "exit"/"exit-force" as
the only supported actions in user units.
v2:
- rename 'exit' to 'exit-force' and add new 'exit'
- add test for the parsing function
FailureAction=/SuccessAction= were added later then StartLimitAction=, so it
was easiest to refer to the existing description. But those two settings are
somewhat simpler (they just execute the action unconditionally) while
StartLimitAction= has additional timing and burst parameters, and they are
about to take on a more prominent role, so let's move the description of
allowed values.
Docbook styles required those to be present, even though the templates that we
use did not show those names anywhere. But something changed semi-recently (I
would suspect docbook templates, but there was only a minor version bump in
recent years, and the changelog does not suggest anything related), and builds
now work without those entries. Let's drop this dead weight.
Tested with F26-F29, debian unstable.
$ perl -i -0pe 's/\s*<authorgroup>.*<.authorgroup>//gms' man/*xml
These lines are generally out-of-date, incomplete and unnecessary. With
SPDX and git repository much more accurate and fine grained information
about licensing and authorship is available, hence let's drop the
per-file copyright notice. Of course, removing copyright lines of others
is problematic, hence this commit only removes my own lines and leaves
all others untouched. It might be nicer if sooner or later those could
go away too, making git the only and accurate source of authorship
information.
This part of the copyright blurb stems from the GPL use recommendations:
https://www.gnu.org/licenses/gpl-howto.en.html
The concept appears to originate in times where version control was per
file, instead of per tree, and was a way to glue the files together.
Ultimately, we nowadays don't live in that world anymore, and this
information is entirely useless anyway, as people are very welcome to
copy these files into any projects they like, and they shouldn't have to
change bits that are part of our copyright header for that.
hence, let's just get rid of this old cruft, and shorten our codebase a
bit.
This corresponds nicely with the specifiers we already pass for
/var/lib, /var/cache, /run and so on.
This is particular useful to update the test-path service files to
operate without guessable files, thus allowing multiple parallel
test-path invocations to pass without issues (the idea is to set $TMPDIR
early on in the test to some private directory, and then only use the
new %T or %V specifier to refer to it).
Usually, we order our settings in our unit files in a logical order,
grouping related settings together, and putting more relevant stuff
first, instead of following a strictly alphabetical order.
For specifiers I think it makes sense to follow an alphabetical order
however, since they literally are just characters, and hence I think the
concept of alphabetical ordering is much more commanding for them. Also,
since specifiers are usually not used in combination, but mostly used
indepdently of each other I think it's not that important to group
similar ones together.
No other changes except the reordering.
Those are quite similar to %i/%I, but refer to the last dash-separated
component of the name prefix.
The new functionality of dash-dropins could largely supersede the template
functionality, so it would be tempting to overload %i/%I. But that would
not be backwards compatible. So let's add the two new letters instead.
The description in the man page disagreed with the code. Let the code win,
since if anybody is using this, they are more likely to depend on actual
behaviour rather than the docs. (In Fedora workstation installation there's
only one use, and it doesn't make much sense either way: SyslogIdentifier=%N
in xfs_scrub@.service.)
Also adds dots at the end everywhere, because we have multiple sentences in
some explanations, so we need dots.
We have a common parser, but for the user it might be
completely unobvious that the same general rules apply
to all those files. Let's add a page about the basic syntax
so that the more specific pages don't have to repeat those
details.
Files which are installed as-is (any .service and other unit files, .conf
files, .policy files, etc), are left as is. My assumption is that SPDX
identifiers are not yet that well known, so it's better to retain the
extended header to avoid any doubt.
I also kept any copyright lines. We can probably remove them, but it'd nice to
obtain explicit acks from all involved authors before doing that.
So far we didn't document control, transient, dbus config, or generator paths.
But those paths are visible to users, and they need to understand why systemd
loads units from those paths, and how the precedence hierarchy looks.
The whole thing is a bit messy, since the list of paths is quite long.
I made the tables a bit shorter by combining rows for the alternatives
where $XDG_* is set and the fallback.
In various places, tags are split like <element
param="blah">
this. This is necessary to keep everyting in one logical XML line so that
docbook renders the table properly.
Replaces #8050.
Follow-up for e79eabdb1b. There was an
apparent contradiction:
man/systemd.unit says for Requires=:
Besides, with or without specifying After=, this unit will be deactivated
if one of the other units get deactivated.
Also, some unit types may deactivate on their own (for example, a service
process may decide to exit cleanly, or a device may be unplugged by the
user), which is not propagated to units having a Requires= dependency.
Fixes#7870.
This adds a simple condition/assert/match to the service manager, to
udev's .link handling and to networkd, for matching the kernel version
string.
In this version we only do fnmatch() based globbing, but we might want
to extend that to version comparisons later on, if we like, by slightly
extending the syntax with ">=", "<=", ">", "<" and "==" expressions.
Up until now, the behaviour in systemd has (mostly) been to silently
ignore failures to action unit directives that refer to an unavailble
controller. The addition of AssertControlGroupController and its
conditional counterpart allow explicit specification of the desired
behaviour when such a situation occurs.
As for how this can happen, it is possible that a particular controller
is not available in the cgroup hierarchy. One possible reason for this
is that, in the running kernel, the controller simply doesn't exist --
for example, the CPU controller in cgroup v2 has only recently been
merged and was out of tree until then. Another possibility is that the
controller exists, but has been forcibly disabled by `cgroup_disable=`
on the kernel command line.
In future this will also support whatever comes out of issue #7624,
`DefaultXAccounting=never`, or similar.
It would be nicer to use <footnote> to place the notes directly in the table,
but docbook renders this improperly.
v2:
- also add "RequiredBy=" to the notes section
- remove duplicated paragraph
v3:
- clarify the description
- drop References/ReferenceBy which are only shown in systemd-analyze dump
The code intentionally ignored unknown specifiers, treating them as text. This
needs to change because otherwise we can never add a new specifier in a backwards
compatible way. So just treat an unknown (potential) specifier as an error.
In principle this is a break of backwards compatibility, but the previous
behaviour was pretty much useless, since the expanded value could change every
time we add new specifiers, which we do all the time.
As a compromise for backwards compatibility, only fail on alphanumerical
characters. This should cover the most cases where an unescaped percent
character is used, like size=5% and such, which behave the same as before with
this patch. OTOH, this means that we will not be able to use non-alphanumerical
specifiers without breaking backwards compatibility again. I think that's an
acceptable compromise.
v2:
- add NEWS entry
v3:
- only fail on alphanumerical
SuccessAction= is similar to FailureAction= but declares what to do on
success of a unit, rather than on failure. This is useful for running
commands in qemu/nspawn images, that shall power down on completion. We
frequently see "ExecStopPost=/usr/bin/systemctl poweroff" or so in unit
files like this. Offer a simple, more declarative alternative for this.
While we are at it, hook up failure action with unit_dump() and
transient units too.
Right now, the option only takes one of two possible values "inactive"
or "inactive-or-failed", the former being the default, and exposing same
behaviour as the status quo ante. If set to "inactive-or-failed" units
may be collected by the GC logic when in the "failed" state too.
This logic should be a nicer alternative to using the "-" modifier for
ExecStart= and friends, as the exit data is collected and logged about
and only removed when the GC comes along. This should be useful in
particular for per-connection socket-activated services, as well as
"systemd-run" command lines that shall leave no artifacts in the
system.
I was thinking about whether to expose this as a boolean, but opted for
an enum instead, as I have the suspicion other tweaks like this might be
a added later on, in which case we extend this setting instead of having
to add yet another one.
Also, let's add some documentation for the GC logic.
This augments %t which already resolves to the runtime directory root, and
should be useful for units that want to pass any of these paths in
command line arguments.
Example:
ExecStart=/usr/bin/mydaemon --datadir=%S/mydaemon
Why not expose a specifier resolving directly to the configured
state/runtime/cache/log dir? Three reasons:
1. Specifiers should be independent of configuration of the unit itself,
and StateDirectory= and friends are unit configuration. See
03fc9c723c and related work.
2. We permit multiple StateDirectory= values per unit, and it hence
wouldn't be clear which one is passed.
3. We already have %t for the runtime directory root, and we should
continue with the same scheme.
We settled on "filename" and "file system", so change a couple of places for
consistency. The exception is when there's an adjective before "file" that
binds more strongly then "name": "password file name", "output file name", etc.
Those cases are left intact.
The values for StartLimitAction are defined in `man systemd.unit`.
Don't send people to `man systemd.service` just to find they need to look
back in `man systemd.unit` again :).
Zbigniew Jędrzejewski-Szmek