From 4e20e0343ede2a91c040ecb7f1d0037a7691281d Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 09 2019 13:38:48 +0000 Subject: [PATCH 1/3] Fix links to systemd man pages --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index b7141de..8c40f22 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -298,7 +298,7 @@ Also, the service may not enable itself if it is currently disabled. ==== Scriptlets -The systemd package provides a set of helper macros to handle systemd scriptlet operations. These macros support systemd "presets", as documented in Features/PackagePresets. The `+%systemd_requires+` macro is a shortcut for listing the per-scriptlet dependencies on systemd. +The systemd package provides a set of helper macros to handle systemd scriptlet operations. These macros support systemd "presets", as documented in https://www.freedesktop.org/software/systemd/man/systemd.preset.html[systemd.preset(5)]. The `+%systemd_requires+` macro is a shortcut for listing the per-scriptlet dependencies on systemd. .... BuildRequires: systemd-rpm-macros @@ -344,10 +344,10 @@ BuildRequires: systemd-rpm-macros ===== Macro details -For details on what these macros evaluate to, refer to the following sources: + -https://github.com/systemd/systemd/blob/master/src/core/macros.systemd.in, + -https://github.com/systemd/systemd/blob/master/src/core/triggers.systemd.in and + -http://www.freedesktop.org/software/systemd/man/daemon.html. +For details on what these macros evaluate to, refer to the following sources: +https://github.com/systemd/systemd/blob/master/src/core/macros.systemd.in[macros.systemd.in], +https://github.com/systemd/systemd/blob/master/src/core/triggers.systemd.in[triggers.systemd.in] and +https://www.freedesktop.org/software/systemd/man/daemon.html[daemon(7)]. === Shells diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc index 84fbbc3..5f2ed15 100644 --- a/guidelines/modules/ROOT/pages/Systemd.adoc +++ b/guidelines/modules/ROOT/pages/Systemd.adoc @@ -22,7 +22,7 @@ Ideally, systemd unit files are reusable across distributions and shipped with the upstream packages. Please consider working with upstream to integrate the systemd files you prepare in the upstream sources. Information for developers on how to integrate systemd support best with their build system you may find -on http://0pointer.de/public/systemd-man/daemon.html +in https://www.freedesktop.org/software/systemd/man/daemon.html[daemon(8)]. ==== Naming @@ -67,9 +67,8 @@ The `+Type=+` setting is very important. For D-Bus services this should be "dbus", for traditional services "forking" is usually a good idea, for services not offering any interfaces to other services "simple" is best. For "one-shot" scripts "oneshot" is ideal, often combined with -`+RemainAfterExit=+`. See -http://0pointer.de/public/systemd-man/systemd.service.html for further -discussion on the topic. Since "simple" is the default type, +`+RemainAfterExit=+`. See https://www.freedesktop.org/software/systemd/man/systemd.service.html[systemd.service(5)] +for further discussion on the topic. Since "simple" is the default type, `+.service+` files which would normally set `+Type=simple+` may simply omit the `+Type+` line altogether. @@ -90,7 +89,7 @@ WantedBy=... The recommended parameters for `+WantedBy=+` are either `+graphical.target+` (services related to the graphical user interface) or `+multi-user.target+` (for everything else). When the user (or our scriptlets) invoke `+systemctl enable+` the service will be set to start in these targets. -For more information regarding these options see http://0pointer.de/public/systemd-man/systemd.unit.html and http://0pointer.de/public/systemd-man/systemd.service.html +For more information regarding these options see https://www.freedesktop.org/software/systemd/man/systemd.unit.html[systemd.unit(5)] and https://www.freedesktop.org/software/systemd/man/systemd.service.html[systemd.service(5)]. ==== EnvironmentFiles and support for /etc/sysconfig files @@ -308,7 +307,7 @@ Restart=on-abnormal in your unit's `+.service+` file for this. -The former will tell systemd to restart the daemon as soon as it fails regardless of the precise reason. It's a good choice for most long-running services. Some daemons require a way to escape constant restarting by exiting with any non-zero exit code. For those services use `+Restart=on-abnormal+`, which will still restart the daemon when it fails "abnormally", on unclean signal, core dump, timeout or watchdog exits, but not on unclean exit codes. It is recommended to to enable automatic restarts for all long-running services, but which setting is the right one, and whether it is useful at all depends on the specific service. Please consult the `+systemd.service(5)+` man page for more information on the various settings. +The former will tell systemd to restart the daemon as soon as it fails regardless of the precise reason. It's a good choice for most long-running services. Some daemons require a way to escape constant restarting by exiting with any non-zero exit code. For those services use `+Restart=on-abnormal+`, which will still restart the daemon when it fails "abnormally", on unclean signal, core dump, timeout or watchdog exits, but not on unclean exit codes. It is recommended to to enable automatic restarts for all long-running services, but which setting is the right one, and whether it is useful at all depends on the specific service. Please consult the https://www.freedesktop.org/software/systemd/man/systemd.service.html[systemd.service(5)] man page for more information on the various settings. === Private devices and networking @@ -334,7 +333,7 @@ Note that `+PrivateNetwork=yes+` should not be used for: * This also disconnects the AF_UNIX abstract namespace from the host (In case you wonder what this refers to: sockets listed in /proc/net/unix that start with an @ are in the abstract namespace, those which start in / are in the file system namespace). This means that services which listen or connect to AF_UNIX sockets in the abstract namespaces might break. AF_UNIX sockets in the file system continue to work correctly even with PrivateNetwork?=yes. We strongly recommend anyway to stop using abstract namespace AF_UNIX sockets, as they bring very little benefit these days. If your package uses them please consider moving them into the file system into a subdirectory in /run (system services) or $XDG_RUNTIME_DIR (user services). * This also disconnects the AF_NETLINK and AF_AUDIT socket families from the host. For services requiring auditing, that need to subscribe to network configuration changes, or want to subscribe to hardware devices coming and going (udev) PrivateNetwork?=yes cannot be used hence. -For further details see the systemd.exec(5) man page. +For further details see the https://www.freedesktop.org/software/systemd/man/systemd.exec.html[systemd.exec(5)] man page. == Packaging From 52cdfcee59ae67aa56e218706f18ecc05665702e Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 09 2019 13:38:48 +0000 Subject: [PATCH 2/3] Fix some obsolete paths --- diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc index 5f2ed15..7f11e35 100644 --- a/guidelines/modules/ROOT/pages/Systemd.adoc +++ b/guidelines/modules/ROOT/pages/Systemd.adoc @@ -212,7 +212,7 @@ User=root SystemdService=console-kit-daemon.service .... -And the matching systemd unit file /lib/systemd/system/console-kit-daemon.service: +And the matching systemd unit file /usr/lib/systemd/system/console-kit-daemon.service: .... [Unit] @@ -259,7 +259,7 @@ SystemdService=dbus-org.freedesktop.Avahi.service Exec=/bin/false .... -Here is the Avahi systemd unit `+.service+` file (/lib/systemd/system/avahi-daemon.service): +Here is the Avahi systemd unit `+.service+` file (/usr/lib/systemd/system/avahi-daemon.service): .... [Unit] @@ -339,7 +339,7 @@ For further details see the https://www.freedesktop.org/software/systemd/man/sys === Filesystem locations -Packages with systemd unit files *must* put them into `+%{_unitdir}+`. `+%{_unitdir}+` evaluates to /lib/systemd/system on all Fedora systems (F-15+). Unit files are architecture independent (hence, not `+%{_lib}+`) and needed early in the boot process. +Packages with systemd unit files *must* put them into `+%{_unitdir}+`. `+%{_unitdir}+` evaluates to /usr/lib/systemd/system on all Fedora systems (F-15+). Unit files are architecture independent (hence, not `+%{_lib}+`) and needed early in the boot process. Please note that in order for the `+%{_unitdir}+` macro to exist, your package must have: From 46010f8b6ab077bfbec45a59b1de99fb7871ee0a Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 09 2019 19:33:58 +0000 Subject: [PATCH 3/3] Stop using %systemd_requires for packages which only install unit files Nowadays systemd.rpm does a preset-all call when it is installed. This means that individual packages which provide systemd units and call %systemd_post in their %post will work fine no matter if they are installed *before* or *after* systemd. If installed *after*, the sequence is: ... 1. install systemd, systemctl preset-all is called 2. install package with a.service, %systemd_post calls systemctl preset a.service (a.service is enabled if presets say so). If installed *before*: ... 1. package is installed, %systemd_post calls systemctl preset a.service, but nothing happens because /usr/bin/systemctl is not found. (The scriptlet is conditionalized using [ -x /usr/bin/systemctl ], so no error or warning is emitted.) 2. systemd is installed, systemctl preset-all is called (a.service is enabled if presets say so). If systemd is not installed at all: the service is never enabled, and there's generally no way to run the service using systemd. This might happen for example when building a custom container image or systemd portable. I think that's totally reasonable, if systemd should be used in the image, it should be declared explicitly, and not pulled in as a dependency of some random package. During upgrades: %systemd_postun_with_restart calls systemctl try-restart. If systemd is not installed, than the service is obviously not running, so there's nothing to restart. The advantages of removing the dependency are: 1. it is easier to build custom images of various sorts, because systemd is a big package and pulls in a *lot* of dependencies. For specialized use cases this is totally unnecessary. 2. when those depencencies are removed, rpm has more freedom to order the transaction. In case there are other constrains on the ordering (that actually matter), there's less chance of circular dependencies and it's more likely that rpm will be able to honour those other constraints. 3. "less is more" in general. Please note that this applies to calls to systemctl preset and systemctl try-restart. If the package calls some other systemd tool, for example systemd-tmpfiles or systemd-sysusers, or otherwise requires systemd to be installed, it should retain appropriate dependencies. --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 8c40f22..088fb07 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -298,11 +298,10 @@ Also, the service may not enable itself if it is currently disabled. ==== Scriptlets -The systemd package provides a set of helper macros to handle systemd scriptlet operations. These macros support systemd "presets", as documented in https://www.freedesktop.org/software/systemd/man/systemd.preset.html[systemd.preset(5)]. The `+%systemd_requires+` macro is a shortcut for listing the per-scriptlet dependencies on systemd. +The systemd package provides a set of helper macros to handle systemd scriptlet operations. These macros support systemd "presets", as documented in https://www.freedesktop.org/software/systemd/man/systemd.preset.html[systemd.preset(5)]. .... BuildRequires: systemd-rpm-macros -%{?systemd_requires} [...] %post @@ -324,15 +323,12 @@ Some services do not support being restarted (e.g. D-Bus and various storage dae If your package includes one or more systemd units that need to be enabled by default on package installation, they MUST be covered by the xref:DefaultServices.adoc[Fedora preset policy]. -If a package is suitable for installation without systemd (in a container image, for example) and does not require any of the systemd mechanisms such as tmpfiles.d, then the `+%systemd_ordering+` macro MAY be used instead of the `+%systemd_requires+` macro. - ===== User units There are additional macros for user units (those installed under `+%_userunitdir+`) that should be used similarly to those for system units. These enable and disable user units according to presets, and are `+%systemd_user_post+` (to be used in `+%post+`) and `+%systemd_user_preun+` (to be used in `+%preun+`). .... BuildRequires: systemd-rpm-macros -%{?systemd_requires} [...] %post @@ -342,6 +338,13 @@ BuildRequires: systemd-rpm-macros %systemd_user_preun %{name}.service .... +===== Dependencies on the systemd package + +If package scriptlets call other systemd tools, for example `systemd-tmpfiles`, the package SHOULD declare appropriate dependencies. The `%systemd_requires` macro is a shortcut to require systemd for the `%pre`, `%post`, and `%postun` scriptlets. Note that those dependencies are **not** required for the `%systemd_{post,preun,postun_with_restart,user_post,user_preun}` macros listed above. + +If the package wants to use systemd tools if they are available, but does not want to declare a dependency, then the `%systemd_ordering` +macro MAY be used as a weaker form of `%systemd_requires` that only declares an ordering during an RPM transaction. + ===== Macro details For details on what these macros evaluate to, refer to the following sources: