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 concept is redundant and predates the special chars that do the same
in ExecStar=. Let's settle on advertising just the latter, and hide
PermissionsStartOnly= from the docs (even if we continue supporting it).
In a way this is a follow-up for
a2d1fb882c, but adds a similar warning for
PIDFile=.
There's a much stronger case for doing this kind of notification in
tmpfiles.d (since it helps relating lines to each other for the purpose
of merging them). Doing this for PIDFile= is mostly about being
systematic and copying tmpfiles.d/ behaviour here.
While we are at it, let's also support relative filenames in PIDFile=
now, and prefix them with /run, to make them absolute.
Fixes: #10657
Allows configuring the watchdog signal (with a default of SIGABRT).
This allows an alternative to SIGABRT when coredumps are not desirable.
Appropriate references to SIGABRT or aborting were renamed to reflect
more liberal watchdog signals.
Closes#8658
And while we are at it, let's rearrange and extend the Type=
documentation a bit. Let's make it an itemized list, and let's add a
paragraph explaining which type best to use.
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.
Commenting out "WatchdogTimeout=3min" in systemd-logind.service causes
NotifyAccess to go from "main" to "none", breaking support for logind
restart. Let's fix that.
Absolute paths make everything simple and quick, but sometimes this requirement
can be annoying. A good example is calling 'test', which will be located in
/usr/bin/ or /bin depending on the distro. The need the provide the full path
makes it harder a portable unit file in such cases.
This patch uses a fixed search path (DEFAULT_PATH which was already used as the
default value of $PATH), and if a non-absolute file name is found, it is
immediately resolved to a full path using this search path when the unit is
loaded. After that, everything behaves as if an absolute path was specified. In
particular, the executable must exist when the unit is loaded.
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.
Changed <filename>.service</filename> to <literal>.service</literal> to match style in other manual pages: man 5 systemd.socket, device, mount, automount, swap, target path, timer, slice and scope.
Let's be more restrictive when validating PID files and MAINPID=
messages: don't accept PIDs that make no sense, and if the configuration
source is not trusted, don't accept out-of-cgroup PIDs. A configuratin
source is considered trusted when the PID file is owned by root, or the
message was received from root.
This should lock things down a bit, in case service authors write out
PID files from unprivileged code or use NotifyAccess=all with
unprivileged code. Note that doing so was always problematic, just now
it's a bit less problematic.
When we open the PID file we'll now use the CHASE_SAFE chase_symlinks()
logic, to ensure that we won't follow an unpriviled-owned symlink to a
privileged-owned file thinking this was a valid privileged PID file,
even though it really isn't.
Fixes: #6632
Systemd services are permitted to be scripts, as well as binary
executables.
The same also applies to the underlying /sbin/mount and /sbin/swapon.
It is not necessary for the user to consider what type of program file
these are. Nor is it necessary with systemd-nspawn, to distinguish between
init as a "binary" v.s. a user-specified "program".
Also fix a couple of grammar nits in the modified sentences.
With Type=notify services, EXTEND_TIMEOUT_USEC= messages will delay any startup/
runtime/shutdown timeouts.
A service that hasn't timed out, i.e, start time < TimeStartSec,
runtime < RuntimeMaxSec and stop time < TimeoutStopSec, may by sending
EXTEND_TIMEOUT_USEC=, allow the service to continue beyond the limit for
the execution phase (i.e TimeStartSec, RunTimeMaxSec and TimeoutStopSec).
EXTEND_TIMEOUT_USEC= must continue to be sent (in the same way as
WATCHDOG=1) within the time interval specified to continue to reprevent
the timeout from occuring.
Watchdog timeouts are also extended if a EXTEND_TIMEOUT_USEC is greater
than the remaining time on the watchdog counter.
Fixes#5868.
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.
That advice is generally apropriate for "user" programs, i.e. programs which
are run interactively and used pipelines and such. But it makes less sense for
daemons to propagate the exit signal. For example, if a process receives a SIGTERM,
it is apropriate for it to exit with 0 code. So let's just delete the whole
paragraph, since this page doesn't seem to be the right place for the longer
discussion which would be required to mention all the caveats and considerations.
Fixes#6415.
This patch adds two new special character prefixes to ExecStart= and
friends, in addition to the existing "-", "@" and "+":
"!" → much like "+", except with a much reduced effect as it only
disables the actual setresuid()/setresgid()/setgroups() calls, but
leaves all other security features on, including namespace
options. This is very useful in combination with
RuntimeDirectory= or DynamicUser= and similar option, as a user
is still allocated and used for the runtime directory, but the
actual UID/GID dropping is left to the daemon process itself.
This should make RuntimeDirectory= a lot more useful for daemons
which insist on doing their own privilege dropping.
"!!" → Similar to "!", but on systems supporting ambient caps this
becomes a NOP. This makes it relatively straightforward to write
unit files that make use of ambient capabilities to let systemd
drop all privs while retaining compatibility with systems that
lack ambient caps, where priv dropping is the left to the daemon
codes themselves.
This is an alternative approach to #6564 and related PRs.
This also alters the documentation to recommend memfds rather than /run
for serializing state across reboots. That's because /run doesn't
actually have the same lifecycle as the fd store, as it is cleared out
on restarts.
Fixes: #5606
Make sure to only apply the O_NONBLOCK flag to the fds passed via socket
activation.
Previously the flag was also applied to the fds which came from the fd store
but this was incorrect since services, after being restarted, expect that these
passed fds have their flags unchanged and can be reused as before.
The documentation was a bit unclear about this so clarify it.
The third paragraph of the Description already linked to
systemd.resource-control(5), but it was missing from the list of
additional options for the [Service] section.
The manpage claimed that ExecStop would be followed immediately by
SIGKILL, whereas the actual behavior is to go through KillMode= and
KillSignal= first.
Fixes#4490
As requested in
https://github.com/systemd/systemd/pull/4864#pullrequestreview-12372557.
docbook will substitute triple dots for the ellipsis in man output, so this has
no effect on the troff output, only on HTML, making it infinitesimally nicer.
In some places we show output from programs, which use dots, and those places
should not be changed. In some tables, the alignment would change if dots were
changed to the ellipsis which is only one character. Since docbook replaces the
ellipsis automatically, we should leave those be. This patch changes all other
places.
Our warning message was misleading, because we wouldn't "correct" anything,
we'd just ignore unkown escapes. Update the message.
Also, print just the extracted word (which contains the offending sequences) in
the message, instead of the whole line.
Fixes#4697.
This should simplify monitoring tools for services, by passing the most basic
information about service result/exit information via environment variables,
thus making it unnecessary to retrieve them explicitly via the bus.
As suggested by @mbiebl we already use the "!" special char in unit file
assignments for negation, hence we should not use it in a different context for
privileged execution. Let's use "+" instead.
Type=notify has a magic overriding case where a NotifyAccess=none
is turned into a NotifyAccess=main for sanity purposes.
This makes docs more clear about such behavior:
2787d83c28/src/core/service.c (L650):L651
This patch implements the new magic character '!'. By putting '!' in front
of a command, systemd executes it with full privileges ignoring paramters
such as User, Group, SupplementaryGroups, CapabilityBoundingSet,
AmbientCapabilities, SecureBits, SystemCallFilter, SELinuxContext,
AppArmorProfile, SmackProcessLabel, and RestrictAddressFamilies.
Fixes partially https://github.com/systemd/systemd/issues/3414
Related to https://github.com/coreos/rkt/issues/2482
Testing:
1. Create a user 'bob'
2. Create the unit file /etc/systemd/system/exec-perm.service
(You can use the example below)
3. sudo systemctl start ext-perm.service
4. Verify that the commands starting with '!' were not executed as bob,
4.1 Looking to the output of ls -l /tmp/exec-perm
4.2 Each file contains the result of the id command.
`````````````````````````````````````````````````````````````````
[Unit]
Description=ext-perm
[Service]
Type=oneshot
TimeoutStartSec=0
User=bob
ExecStartPre=!/usr/bin/sh -c "/usr/bin/rm /tmp/exec-perm*" ;
/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-start-pre"
ExecStart=/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-start" ;
!/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-star-2"
ExecStartPost=/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-start-post"
ExecReload=/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-reload"
ExecStop=!/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-stop"
ExecStopPost=/usr/bin/sh -c "/usr/bin/id > /tmp/exec-perm-stop-post"
[Install]
WantedBy=multi-user.target]
`````````````````````````````````````````````````````````````````
This moves the StartLimitBurst=, StartLimitInterval=, StartLimitAction=, RebootArgument= from the [Service] section
into the [Unit] section of unit files, and thus support it in all unit types, not just in services.
This way we can enforce the start limit much earlier, in particular before testing the unit conditions, so that
repeated start-up failure due to failed conditions is also considered for the start limit logic.
For compatibility the four options may also be configured in the [Service] section still, but we only document them in
their new section [Unit].
This also renamed the socket unit failure code "service-failed-permanent" into "service-start-limit-hit" to express
more clearly what it is about, after all it's only triggered through the start limit being hit.
Finally, the code in busname_trigger_notify() and socket_trigger_notify() is altered to become more alike.
Fixes: #2467
This makes sure we never run two control processes at the same time, we cannot keep track off.
This introduces a slight change of behaviour but cleans up the definition of ExecStop= and ExecStopPost=. The former is
now invoked only if the service managed to start-up correctly. The latter is called even if start-up failed half-way.
Thus, ExecStopPost= may be used as clean-up step for both successful and failed start-up attempts, but ExecStop='s
purpose is clearly defined as being responsible for shutting down the service and nothing else.
The precise behaviour of this was not documented yet. This commit adds the necessary docs.
Fixes: #1254
This completes the set of man pages for sd-event and contains some minor
other fixes for other man pages too.
The sd_event_set_name(3) man page is renamed to
sd_event_source_set_description(3), which is the correct name of the
concept today.
For all units ensure there's an "Automatic Dependencies" section in the
man page, and explain which dependencies are automatically added in all
cases, and which ones are added on top if DefaultDependencies=yes is
set.
This is also done for systemd.exec(5), systemd.resource-control(5) and
systemd.unit(5) as these pages describe common behaviour of various unit
types.
Previously it was just descibed that ExecStartPost= commands were
started "after" the ExecStart= command(s).
This hasn't specified after which event, which varies from after it has
been started, after it has exited, after it has sent READY=1 or after it
has taken the bus name, depending on Type=.
This now describes that it happens after the *service* has "started",
as defined by the Type=, and provides some clarification about precisely
when this is.
This may be unnecessary duplication, but it removes the ambiguity as to
whether RemainAfterExit=no means that ExecStartPost= shouldn't be
started because it means the service has stopped when the ExecStart=
command terminates, not "started".
https://bugzilla.redhat.com/show_bug.cgi?id=1251334
is about a unit file which has
Environment=TERM=linux PS1=system-upgrade:\w\$\x20
We used to allow that, but after recent tightening of parsing
rules, we barf. Make it clear that this is intentional.
This did not really work out as we had hoped. Trying to do this upstream
introduced several problems that probably makes it better suited as a
downstream patch after all. At any rate, it is not releaseable in the
current state, so we at least need to revert this before the release.
* by adjusting the path to binaries, but not do the same thing to the
search path we end up with inconsistent man-pages. Adjusting the search
path too would be quite messy, and it is not at all obvious that this is
worth the effort, but at any rate it would have to be done before we
could ship this.
* this means that distributed man-pages does not make sense as they depend
on config options, and for better or worse we are still distributing
man pages, so that is something that definitely needs sorting out before
we could ship with this patch.
* we have long held that split-usr is only minimally supported in order
to boot, and something we hope will eventually go away. So before we start
adding even more magic/effort in order to make this work nicely, we should
probably question if it makes sense at all.
In particular, use /lib/systemd instead of /usr/lib/systemd in distributions
like Debian which still have not adopted a /usr merge setup.
Use XML entities from man/custom-entities.ent to replace configured paths while
doing XSLT processing of the original XML files. There was precedent of some
files (such as systemd.generator.xml) which were already using this approach.
This addresses most of the (manual) fixes from this patch:
http://anonscm.debian.org/cgit/pkg-systemd/systemd.git/tree/debian/patches/Fix-paths-in-man-pages.patch?h=experimental-220
The idea of using generic XML entities was presented here:
http://lists.freedesktop.org/archives/systemd-devel/2015-May/032240.html
This patch solves almost all the issues, with the exception of:
- Path to /bin/mount and /bin/umount.
- Generic statements about preference of /lib over /etc.
These will be handled separately by follow up patches.
Tested:
- With default configure settings, ran "make install" to two separate
directories and compared the output to confirm they matched exactly.
- Used a set of configure flags including $CONFFLAGS from Debian:
http://anonscm.debian.org/cgit/pkg-systemd/systemd.git/tree/debian/rules
Installed the tree and confirmed the paths use /lib/systemd instead of
/usr/lib/systemd and that no other unexpected differences exist.
- Confirmed that `make distcheck` still passes.
With this change it is possible to send file descriptors to PID 1, via
sd_pid_notify_with_fds() which PID 1 will store individually for each
service, and pass via the usual fd passing logic on next invocation.
This is useful for enable daemon reload schemes where daemons serialize
their state to /run, push their fds into PID 1 and terminate, restoring
their state on next start from the data in /run and passed in from PID
1.
The fds are kept by PID 1 as long as no POLLHUP or POLLERR is seen on
them, and the service they belong to are either not dead or failed, or
have a job queued.
The handling of the command name and other arguments is unified. This
simplifies things and should make them more predictable for users.
Incidentally, this makes ExecStart handling match the .desktop file
specification, apart for the requirment for an absolute path.
https://bugs.freedesktop.org/show_bug.cgi?id=86171
Add a new directive called BusPolicy to define custom endpoint policies. If
one such directive is given, an endpoint object in the service's ExecContext is
created and the given policy is added to it.
When this system-wide start-up timeout is hit we execute one of the
failure actions already implemented for services that fail.
This should not only be useful on embedded devices, but also on laptops
which have the power-button reachable when the lid is closed. This
devices, when in a backpack might get powered on by accident due to the
easily reachable power button. We want to make sure that the system
turns itself off if it starts up due this after a while.
When the system manages to fully start-up logind will suspend the
machine by default if the lid is closed. However, in some cases we don't
even get as far as logind, and the boot hangs much earlier, for example
because we ask for a LUKS password that nobody ever enters.
Yeah, this is a real-life problem on my Yoga 13, which has one of those
easily accessible power buttons, even if the device is closed.
This is useful for services that simply want to run something on
shutdown, but not at bootup. They should only set ExecStop= but leave
ExecStart= unset.
Restart=on-abnormal is similar to Restart=on-failure, but avoids
restarts on unclean exit codes (but still doing restarts on all
obviously unclean exits, such as timeouts, signals, coredumps, watchdog
timeouts).
Also see:
https://fedorahosted.org/fpc/ticket/191
When rebooting with systemctl, an optional argument can be passed to the
reboot system call. This makes it possible the specify the argument in a
service file and use it when the service triggers a restart.
This is useful to distinguish between manual reboots and reboots caused by
failing services.
Actually 'STDOUT' is something that doesn't appear anywhere: in the
stdlib we have 'stdin', and there's only the constant STDOUT_FILENO,
so there's no reason to use capitals. When refering to code,
STDOUT/STDOUT/STDERR are replaced with stdin/stdout/stderr, and in
other places they are replaced with normal phrases like standard
output, etc.
* standardize capitalization of STDIN, STDOUT, and STDERR
* reword some sentences for clarity
* reflow some very long lines to be shorter than ~80 characters
* add some missing <literal>, <constant>, <varname>, <option>, and <filename> tags
The behavior of this is a little cryptic in that $MAINPID must exit as
a direct result of receiving a signal in order for a listed signal to
be considered a success condition.
grawity:
It looks like the old version _was_ correct – the default value will
be "Type=dbus" if the service has a BusName set.
Suggested change: "if neither Type= nor BusName= is specified"
This is a recurring submission and includes corrections to:
- missing words, preposition choice.
- change of /lib to /usr/lib, because that is what most distros are
using as the system-wide location for systemd/udev files.
We have lots of questions from people who assume that shell syntax works
here, so let's be very explicit what is allowed and what is not. A few
examples should also help.
http://bugs.debian.org/732156
We now treat passno as boleans in the generators, and don't need this any more. fsck itself
is able to sequentialize checks on the same local media, so in the common case the ordering
is redundant.
It is still possible to force an order by using .d fragments, in case that is desired.
This is a recurring submission and includes corrections to various
issue spotted. I guess I can just skip over reporting ubiquitous comma
placement fixes…
Since cgroups are mostly now an implementation detail of systemd lets
deemphasize it a bit in the man pages. This renames systemd.cgroup(5) to
systemd.resource-control(5) and uses the term "resource control" rather
than "cgroup" where appropriate.
This leaves the word "cgroup" in at a couple of places though, like for
example systemd-cgtop and systemd-cgls where cgroup stuff is at the core
of what is happening.
This is a recurring submission and includes corrections to various
issue spotted. I guess I can just skip over reporting ubiquitous
comma placement fixes…
Highligts in this particular commit:
- the "unsigned" type qualifier is completed to form a full type
"unsigned int"
- alphabetic -> lexicographic (that way we automatically define how
numbers get sorted)
