1
0
mirror of https://github.com/systemd/systemd.git synced 2024-12-23 21:35:11 +03:00
Commit Graph

88 Commits

Author SHA1 Message Date
Zbigniew Jędrzejewski-Szmek
67da7e9a4f man: make the description of fd storage a bit more accessible
The text is split into paragraphs about specific topics. The advice
and recommendations parts are moved to the end.
2023-09-15 09:00:23 +02:00
Zbigniew Jędrzejewski-Szmek
ef86486acf man/sd_notify: split out variable descriptions to a separate section
This just moves the text around with miminal text added to refer to the new
section.
2023-09-15 09:00:23 +02:00
Abderrahim Kitouni
69106f4742 man: add version information for functions 2023-09-04 19:31:16 +01:00
Abderrahim Kitouni
ec07c3c80b man: add version info
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.
2023-08-29 14:07:24 +01:00
Lennart Poettering
e503019bc7 tree-wide: when in doubt use greek small letter mu rather than micro symbol
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
2023-06-14 10:23:56 +02:00
Lennart Poettering
0de3431871 sd-daemon: add sd_pid_notify_barrier() call and use it in systemd-notify
Previously we'd honour --pid= from the main notification we send, but
not from the barrier. This is confusing at best. Let's fix that.
2023-05-03 18:21:42 +02:00
Lennart Poettering
4054d76151 sd-daemon: add sd_pid_notifyf_with_fds()
I guess it was only a question of time until we need to add the final
frontier of notification functions: one that combines the features of
all the others:

1. specifiying a source PID
2. taking a list of fds to send along
3. accepting a format string for the status string

Hence, let's add it.
2023-04-25 17:38:57 +02:00
Daan De Meyer
623a00020f notify: Add EXIT_STATUS field
Whenever one of our tools or daemons exits, let's send the exit status
via sd-notify in the EXIT_STATUS field.
2023-04-12 15:02:34 +02:00
Lennart Poettering
1412ad9a81 man: rebreak all of sd_notify(3)
No change of contents, just some rebreaking of the full file to match
our current line break settings.
2023-04-12 10:34:37 +02:00
Lennart Poettering
75b29fda71 service: tell service processes that the fdstore is available via an env var 2023-04-12 10:34:31 +02:00
Mike Yuan
19dff6914d
core: support overriding NOTIFYACCESS= through sd-notify during runtime
Closes #25963
2023-03-22 06:33:12 +08:00
Zbigniew Jędrzejewski-Szmek
8c51e1520b man: add mention that libsystemd uses getenv()
See #26688: getenv() is not thread-safe, and could a possible source of
problems when a multi-threaded program calls setenv()/putenv()/unsetenv() in
parallel. It is not possible to avoid getenv() calls in general, since $PATH,
$LANG, $SHELL, $USER, $HOME, $TZ may need to be accessed at any time.
Add a warning to our docs so that people are aware of the issue.

Closes #26688. (Real fixes will need to be in glibc and gnome-shell or other
programs.)

The text is added to threads-aware.xml to be included in various places. By
including it in libsystemd-pkgconfig.xml, it is automatically added to all sd-*
pages. The text is also included explicitly in pages for a few other functions
which are call getenv().
2023-03-08 15:32:59 +01:00
Zbigniew Jędrzejewski-Szmek
066991f9fe man/sd_notify: fix indentation in sample programs
Whether we use a newline at the beginning of <programlisting> or not doesn't
seem to have any effect. So let's use the newline in multi-line examples; it is
easier to get the indentation right this way.
2023-01-22 17:55:34 +01:00
Lennart Poettering
81e19b6f65 man: document Type=notify-reload 2023-01-10 18:28:38 +01:00
Luca Boccassi
6c94cfcda5 sd_notify: support AF_VSOCK
Allow sending notifications via AF_VSOCK, so that VMs can communicate
to the hypervisor/VMM that they are finished booting.

Note that if the hypervisor does not support SOCK_DGRAM over AF_VSOCK
(ie: qemu at the time of writing), SOCK_SEQPACKET will be used instead.
2023-01-05 23:07:16 +01:00
Zbigniew Jędrzejewski-Szmek
2fd922afed man: recommend strerror_r() over strerror()
Let's nudge people towards the use of an anonymous buffer like we
do internally.

"errno" → "errnum", to match the man page for strerror, and also to avoid
confusion with the global variable. In general, I think that errno is a
terrible interface and we shouldn't encourage people to use it. Those functions
use errno-style error numbers, which are a different thing.
2022-10-11 16:59:00 +02:00
Zbigniew Jędrzejewski-Szmek
9cfc294fe0 man: fix formatting of "BARRIER=1"
Whitespace inside of the <varname> field was propagated to the displayed form,
causing strange indentation.
2022-07-14 19:25:15 +02:00
Daan De Meyer
ecfa85e9e1 docs: Clarify that the fd store is discarded when a service is stopped 2021-12-08 13:27:28 +00:00
Yu Watanabe
db9ecf0501 license: LGPL-2.1+ -> LGPL-2.1-or-later 2020-11-09 13:23:58 +09:00
Zbigniew Jędrzejewski-Szmek
3b1211574b man: use trailing slash on directories in more places 2020-10-05 18:44:05 +02:00
Frantisek Sumsal
2d4f8cf467 man: fix few spelling errors
Reported by Fossies.org.
2020-05-03 10:23:25 +02:00
Kumar Kartikeya Dwivedi
4f07ddfa9b
Introduce sd_notify_barrier
This adds the sd_notify_barrier function, to allow users to synchronize against
the reception of sd_notify(3) status messages. It acts as a synchronization
point, and a successful return gurantees that all previous messages have been
consumed by the manager. This can be used to eliminate race conditions where
the sending process exits too early for systemd to associate its PID to a
cgroup and attribute the status message to a unit correctly.

systemd-notify now uses this function for proper notification delivery and be
useful for NotifyAccess=all units again in user mode, or in cases where it
doesn't have a control process as parent.

Fixes: #2739
2020-05-01 03:22:47 +05:30
Kenny Levinsen
cb5a46b845 core: Add optional FDPOLL=0 argument to fdstore
A service can specify FDSTORE=1 FDPOLL=0 to request that PID1 does not
poll the fd to remove them on error. If set, fds will only be removed on
FDSTOREREMOVE=1 or when the service is done.

Fixes: #12086
2020-04-30 19:42:26 +02:00
Philip Withnall
e69cacd2af man: Fix typo in sd_notify man page
Signed-off-by: Philip Withnall <withnall@endlessm.com>
2019-06-12 10:39:50 +01:00
Jan Klötzke
99b43caf26 core: immediately trigger watchdog action on WATCHDOG=trigger
A service might be able to detect errors by itself that may require the
system to take the same action as if the service locked up. Add a
WATCHDOG=trigger state change notification to sd_notify() to let the
service manager know about the self-detected misery and instantly
trigger the configured watchdog behaviour.
2019-04-24 10:17:10 +02:00
Zbigniew Jędrzejewski-Szmek
3a54a15760 man: use same header for all files
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
2019-03-14 14:42:05 +01:00
Zbigniew Jędrzejewski-Szmek
0307f79171 man: standarize on one-line license header
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
2019-03-14 14:29:37 +01:00
Zbigniew Jędrzejewski-Szmek
514094f933 man: drop mode line in file headers
This is already included in .dir-locals, so we don't need it
in the files themselves.
2018-07-03 01:32:25 +02:00
Zbigniew Jędrzejewski-Szmek
fdbbee37d5 man: drop unused <authorgroup> tags from man sources
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
2018-06-14 12:22:18 +02:00
Lennart Poettering
0c69794138 tree-wide: remove Lennart's copyright lines
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.
2018-06-14 10:20:20 +02:00
Lennart Poettering
818bf54632 tree-wide: drop 'This file is part of systemd' blurb
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.
2018-06-14 10:20:20 +02:00
Zbigniew Jędrzejewski-Szmek
11a1589223 tree-wide: drop license boilerplate
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.
2018-04-06 18:58:55 +02:00
Daniel Black
a327431bd1 core: add EXTEND_TIMEOUT_USEC={usec} - prevent timeouts in startup/runtime/shutdown (#7214)
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.
2017-12-14 12:17:43 +01:00
Lennart Poettering
e78ee06de1 core: add a new sd_notify() message for removing fds from the FD store again
Currenly the only way to remove fds from the fdstore is to fully
stop the service, or to somehow trigger POLLERR/POLLHUP on the fd, in
which case systemd will remove the fd automatically.

Let's add another way: a new message that can be sent to remove fds
explicitly, given their name.
2017-11-27 17:04:04 +01:00
Lennart Poettering
8d1ab18a46 man: slightly improve the sd_notify() documentation regarding READY=1
READY=1 may be used to signal when a service finished startup, but also
when it finished reloading. Say so.
2017-11-27 17:01:09 +01:00
Lennart Poettering
c45d11cb30 service: reorder sd_notify() handling a bit
Let's keep handling of WATCHDOG= and WATCHDOG_USEC= together. No
functional changes.
2017-11-27 16:59:52 +01:00
Zbigniew Jędrzejewski-Szmek
572eb058cf Add SPDX license identifiers to man pages 2017-11-19 19:08:15 +01:00
Jouke Witteveen
15d167f8a3 core: propagate reload from RELOADING=1 notification (#6550) 2017-08-07 11:27:24 +02:00
Lennart Poettering
3ceb72e558 core: permit FDSTORE=1 messages with non-pollable fds
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
2017-06-26 15:14:41 +02:00
Lennart Poettering
b3bb64767a man: document that sd_notify() is racy in some cases 2017-02-06 18:21:27 +01:00
Zbigniew Jędrzejewski-Szmek
1eecafb8c1 man: use unicode ellipsis in more places
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.
2016-12-11 17:13:19 -05:00
Zbigniew Jędrzejewski-Szmek
99bdcdc7fc man: add a note that FDSTORE=1 requires epoll-compatible fds
Let's say that this was not obvious from our man page.
2016-10-28 22:45:05 -04:00
Minkyung
2787d83c28 watchdog: Support changing watchdog_usec during runtime (#3492)
Add sd_notify() parameter to change watchdog_usec during runtime.

Application can change watchdog_usec value by
sd_notify like this. Example. sd_notify(0, "WATCHDOG_USEC=20000000").

To reset watchdog_usec as configured value in service file,
restart service.

Notice.
sd_event is not currently supported. If application uses
sd_event_set_watchdog, or sd_watchdog_enabled, do not use
"WATCHDOG_USEC" option through sd_notify.
2016-06-22 13:26:05 +02:00
Jakub Wilk
7f3fdb7f19 man: fix typos 2015-12-26 20:37:17 +01:00
Jan Engelhardt
a8eaaee72a doc: correct orthography, word forms and missing/extraneous words 2015-11-06 13:45:21 +01:00
Jan Engelhardt
b938cb902c doc: correct punctuation and improve typography in documentation 2015-11-06 13:00:02 +01:00
David Strauss
3122633a91 man: Drop "internally," which is misleading
The existing text misleads readers into thinking how the notify socket protocol is "internals" and that they can only use the functions. However, the socket is part of the Interface Stability Promise. So, we should drop "internally" from the description so the man page both indicates both how the functions work and how one would talk to the socket directly.
2015-11-02 17:19:26 -08:00
Lennart Poettering
8dd4c05b54 core: add support for naming file descriptors passed using socket activation
This adds support for naming file descriptors passed using socket
activation. The names are passed in a new $LISTEN_FDNAMES= environment
variable, that matches the existign $LISTEN_FDS= one and contains a
colon-separated list of names.

This also adds support for naming fds submitted to the per-service fd
store using FDNAME= in the sd_notify() message.

This also adds a new FileDescriptorName= setting for socket unit files
to set the name for fds created by socket units.

This also adds a new call sd_listen_fds_with_names(), that is similar to
sd_listen_fds(), but also returns the names of the fds.

systemd-activate gained the new --fdname= switch to specify a name for
testing socket activation.

This is based on #1247 by Maciej Wereski.

Fixes #1247.
2015-10-06 11:52:48 +02:00
Jay Strict
1d3eaa9361 man: remove repeated word "the" and polish 2015-06-29 21:20:02 +02:00
Tom Gundersen
12b42c7667 man: revert dynamic paths for split-usr setups
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.
2015-06-18 19:47:44 +02:00