We are saying in public that the protocl is stable and can be easily
reimplemented, so provide an example doing so in the documentation,
license as MIT-0 so that it can be copied and pasted at will.
I think this was just overlooked in #13754, which removed
the restriction of Restart= on Type=oneshot services.
There's no reason to prevent RestartForceExitStatus=
now that Restart= has been allowed.
Closes#31148
The documentation for `RestartPreventExitStatus=` differs from that for `SuccessExitStatus=` in ways that are sometimes confusing (e.g. using `numeric exit codes` instead of `numeric termination statuses`), and other times plain incorrect (e.g. not mentioning `termination status names`, which I've just confirmed to work in systemd 255).
This patch modifies the documentation to be as similar as possible, so as to reduce the reader's cognitive load.
The only reason to recommend this would be if people had multiple commands
with the same name in the search path. This probably was never the best idea,
and it happens rarely anyway. Since the patch that dropped requirement for full
paths was introduced, we have dropped support for unmerged-usr and we're planning
to drop support for split-bin at some point too. Many people effectively have just
one directory in the search path, so there is even less reason to use an absolute
path. So let's recommend just using the command name, which makes the unit file
shorter and nicer to read.
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
This is a follow-up for #28596.
I think the suggestion to use Type=exec uses too strong wording:
Type=exec has non-trivial drawbacks over Type=simple, and they deserve
to be mentioned.
Hence drop the <emphasis> and turn this around so that Type=exec is
*recommended*, but Type=simple is not expressly discouraged, because
there are plenty reasons to use it.
Add a brief discussion where Type=simple might be preferable.
Also, fix the outright unruth that Type=exec was the "simplest and
fastest", because it certainly is a lot, but not that.
The descriptions of various options are reworked: first say what protocol
actually is, i.e. describe what type of notification the manager waits
for. Only after that describe various steps and things the service should
do. Also, apply some paragraph breaks.
Instead of recommending Type=simple, recommend Type=exec. Say explicitly that
Type=simple, Type=forking are not recommended. Type=simple ignores failure in a
way that doesn't make any sense except as a historical accident. We introduced
'exec' instead of changing 'simple' to keep backwards-compatiblity, but
'simple' is not very useful. 'forking' works, but is inefficient: correctly
programming the interface requires a lot of work, and at runtime, the
additional one or two forks are just a waste of CPU resources. Furthermore, we
now understand that because of COW traps, they may also increase memory
requirements. There is really no reason to use 'forking', except if it's
already implemented and the code cannot be changed to use 'notify'.
Also, remove the recommendations to use Type=simple to avoid delaying boot. In
most cases, if the service can support notifications about startup, those
should be done.
Overall, for new services, "notify", "notify-reload", and "dbus" are the
types that make sense.
When this option is set to direct, the service restarts without entering a failed
state. Dependent units are not notified of transitory failure.
This is useful for the following use case:
We have a target with Requires=my-service, After=my-service.
my-service.service is a oneshot service and has Restart=on-failure in
its definition.
my-service.service can get stuck for various reasons and time out, in
which case it is restarted. Currently, when it fails the first time, the
target fails, even though my-service is restarted.
The behavior we're looking for is that until my-service is not restarted
anymore, the target stays pending waiting for my-service.service to
start successfully or fail without being restarted anymore.
Doesn't really matter since the two unicode symbols are supposedly
equivalent, but let's better follow the unicode recommendations to
prefer greek small letter mu, as per:
https://www.unicode.org/reports/tr25
Oftentimes it is useful to allow the per-service fd store to survive
longer than for a restart. This is useful in various scenarios:
1. An fd to some security relevant object needs to be stashed somewhere,
that should not be cleaned automatically, because the security
enforcement would be dropped then.
2. A user namespace fd should be allocated on first invocation and be
kept around until the user logs out (i.e. systemd --user ends), á la
#16328 (This does not implement what #16318 asks for, but should
solve the use-case discussed there.)
3. There's interest in allow a concept of "userspace reboots" where the
kernel stays running, and userspace is swapped out (i.e. all services
exit, and the rootfs transitioned into a new version of it) while
keeping some select resources pinned, very similar to how we
implement a switch root. Thus it is useful to allow services to exit,
while leaving their fds around till the very end.
This is exposed through a new FileDescriptorStorePreserve= setting that
is closely modelled after RuntimeDirectoryPreserve= (in fact it reused
the same internal type), since we want similar behaviour in the end, and
quite often they probably want to be used together.
The description was split — part was under ExecStart= and part in "Command lines".
Now the whole generic part is moved to the separate section, and under ExecStart=
only the stuff that is specific to that option is described.
This just moves the text and removes some repetitions.
interval between restarts
RestartSteps= accepts a positive integer as the number of steps
to take to increase the interval between auto-restarts from
RestartSec= to RestartSecMax=, or 0 to disable it.
Closes#6129
Config options are -Ddefault-timeout-sec= and -Ddefault-user-timeout-sec=.
Existing -Dupdate-helper-user-timeout= is renamed to -Dupdate-helper-user-timeout-sec=
for consistency. All three options take an integer value in seconds. The
renaming and type-change of the option is a small compat break, but it's just
at compile time and result in a clear error message. I also doubt that anyone was
actually using the option.
This commit separates the user manager timeouts, but keeps them unchanged at 90 s.
The timeout for the user manager is set to 4/3*user-timeout, which means that it
is still 120 s.
Fedora wants to experiment with lower timeouts, but doing this via a patch would
be annoying and more work than necessary. Let's make this easy to configure.
DeviceAllow= and others are applied to the whole cgroup via bpf, so
using '+' on an Exec line will not bypass them. Explain this in the
manpage.
Fixes https://github.com/systemd/systemd/issues/26035
One had to read to the very end of the long description to notice that
the setting is actually primarily intended for oomd. So let's mention oomd
right at the beginning.
(s) is just ugly with a vibe of DOS. In most cases just using the normal plural
form is more natural and gramatically correct.
There are some log_debug() statements left, and texts in foreign licenses or
headers. Those are not touched on purpose.
The gist of the description is moved from systemd.resource-control
to systemd-oomd man page. Cross-references to OOMPolicy, memory.oom.group,
oomctl, ManagedOOMSwap and ManagedOOMMemoryPressure are added in all
places.
The descriptions are also more down-to-earth: instead of talking
about "taking action" let's just say "kill". We *might* add configuration
for different actions in the future, but we're not there yet, so let's
just describe what we do now.
This introduces `ExitType=main|cgroup` for services.
Similar to how `Type` specifies the launch of a service, `ExitType` is
concerned with how systemd determines that a service exited.
- If set to `main` (the current behavior), the service manager will consider
the unit stopped when the main process exits.
- The `cgroup` exit type is meant for applications whose forking model is not
known ahead of time and which might not have a specific main process.
The service will stay running as long as at least one process in the cgroup
is running. This is intended for transient or automatically generated
services, such as graphical applications inside of a desktop environment.
Motivation for this is #16805. The original PR (#18782) was reverted (#20073)
after realizing that the exit status of "the last process in the cgroup" can't
reliably be known (#19385)
This version instead uses the main process exit status if there is one and just
listens to the cgroup empty event otherwise.
The advantages of a service with `ExitType=cgroup` over scopes are:
- Integrated logging / stdout redirection
- Avoids the race / synchronisation issue between launch and scope creation
- More extensive use of drop-ins and thus distro-level configuration:
by moving from scopes to services we can have drop ins that will affect
properties that can only be set during service creation,
like `OOMPolicy` and security-related properties
- It makes systemd-xdg-autostart-generator usable by fixing [1], as obviously
only services can be used in the generator, not scopes.
[1] https://bugs.kde.org/show_bug.cgi?id=433299
For some unit types we have hundreds of options, and the reader may easily miss
that more options are described in other pages. We already mentioned this in
the introduction and then at the top of the option list, but it can't hurt to
repeat the information.
Also, add an (almost empty) Options section for the unit types which don't have
any custom options. It is nicer to have the same page structure in all cases,
so people can jump between pages for different types more easily.
The existing text must have been written before systemd-sysv-generator was
created. We don't create the wrappers dynamically since a long time.
Also add more links and make the description conditional on "if compat
is enabled".
This reverts commit cb0e818f7c.
After this was merged, some design and implementation issues were discovered,
see the discussion in #18782 and #19385. They certainly can be fixed, but so
far nobody has stepped up, and we're nearing a release. Hopefully, this feature
can be merged again after a rework.
Fixes#19345.
