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 :).
This adds two options that are useful for user units. In particular, it
is useful to check ConditionUser=!0 to not start for the root user.
Closes: #5187
Unit.JobTimeoutSec starts when a job is enqueued in a transaction. The
introduced distinct Unit.JobRunningTimeoutSec starts only when the job starts
running (e.g. it groups all Exec* commands of a service or spans waiting for a
device period.)
Unit.JobRunningTimeoutSec is intended to be used by default instead of
Unit.JobTimeoutSec for device units where such behavior causes less confusion
(consider a job for a _netdev mount device, with this change the timeout will
start ticking only after the network is ready).
%c and %r rely on settings made in the unit files themselves and hence resolve
to different values depending on whether they are used before or after Slice=.
Let's simply deprecate them and drop them from the documentation, as that's not
really possible to fix. Moreover they are actually redundant, as the same
information may always be queried from /proc/self/cgroup and /proc/1/cgroup.
(Accurately speaking, %R is actually not broken like this as it is constant.
However, let's remove all cgroup-related specifiers at once, as it is also
redundant, and doesn't really make much sense alone.)
Various things don't work when we're running in a user namespace, but it's
pretty hard to reliably detect if that is true.
A function is added which looks at /proc/self/uid_map and returns false
if the default "0 0 UINT32_MAX" is found, and true if it finds anything else.
This misses the case where an 1:1 mapping with the full range was used, but
I don't know how to distinguish this case.
'systemd-detect-virt --private-users' is very similar to
'systemd-detect-virt --chroot', but we check for a user namespace instead.
Let's avoid the overly abbreviated "cgroups" terminology. Let's instead write:
"Linux Control Groups (cgroups)" is the long form wherever the term is
introduced in prose. Use "control groups" in the short form wherever the term
is used within brief explanations.
Follow-up to: #4381
In certain situations drop-ins in /usr/lib/ are useful, for example when one package
wants to modify the behaviour of another package, or the vendor wants to tweak some
upstream unit without patching.
Drop-ins in /run are useful for testing, and may also be created by systemd itself.
Follow-up for the discussion in #2103.
Also update the description of drop-ins in systemd.unit(5) to say that .d
directories, not .conf files, are in /etc/system/system, /run/systemd/system,
etc.
The man pages didn't ever mention that symlinks to units can be created, and what
exactly this means. Fix that omission, and disallow presets on alias names.
Let's move the enforcement of the per-unit start limit from unit.c into the
type-specific files again. For unit types that know a concept of "result" codes
this allows us to hook up the start limit condition to it with an explicit
result code. Also, this makes sure that the state checks in clal like
service_start() may be done before the start limit is checked, as the start
limit really should be checked last, right before everything has been verified
to be in order.
The generic start limit logic is left in unit.c, but the invocation of it is
moved into the per-type files, in the various xyz_start() functions, so that
they may place the check at the right location.
Note that this change drops the enforcement entirely from device, slice, target
and scope units, since these unit types generally may not fail activation, or
may only be activated a single time. This is also documented now.
Note that restores the "start-limit-hit" result code that existed before
6bf0f408e4 already in the service code. However,
it's not introduced for all units that have a result code concept.
Fixes#3166.
We generally follow the rule that for time settings we suffix the setting name
with "Sec" to indicate the default unit if none is specified. The only
exception was the rate limiting interval settings. Fix this, and keep the old
names for compatibility.
Do the same for journald's RateLimitInterval= setting
With #2564 unit start rate limiting was moved from after the condition checks
are to before they are made, in an attempt to fix#2467. This however resulted
in #2684. However, with a previous commit a concept of per socket unit trigger
rate limiting has been added, to fix#2467 more comprehensively, hence the
start limit can be moved after the condition checks again, thus fixing #2684.
Fixes: #2684
Let's make this more digestable to read by making the list of documented unit
file paths a bit shorter.
Specifically, let's drop references to $XDG_CONFIG_HOME and $XDG_DATA_HOME, as
their default values are listed too already. Given that the fact that the XDG
basedir spec makes these paths configurable is probably not a strong point of
the spec, let's drop the reference to the env vars, and keep only the literal,
default paths for them in the list. Of course, we do support the full XDG
basedir spec in this regard, but it's one thing to implement it and another one
to recommend it by documenting it.
Replace "$HOME" by "~", because UNIX.
