From: Lennart Poettering Date: Wed, 1 Jul 2026 16:22:13 +0000 (+0200) Subject: man: document the new .component files X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=87f4e729d8b6f781f798cef69d6dfae43c7905ef;p=thirdparty%2Fsystemd.git man: document the new .component files --- diff --git a/man/rules/meson.build b/man/rules/meson.build index 3dafcc13dec..eac4465769b 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1379,6 +1379,7 @@ manpages = [ ['systemd.timer', '5', [], ''], ['systemd.unit', '5', [], ''], ['systemd.v', '7', [], ''], + ['sysupdate.components', '5', [], 'ENABLE_SYSUPDATE'], ['sysupdate.d', '5', [], 'ENABLE_SYSUPDATE'], ['sysupdate.features', '5', [], 'ENABLE_SYSUPDATE'], ['sysusers.d', '5', [], 'ENABLE_SYSUSERS'], diff --git a/man/systemd-sysupdate.xml b/man/systemd-sysupdate.xml index 28b6ac53c22..7386a399e7c 100644 --- a/man/systemd-sysupdate.xml +++ b/man/systemd-sysupdate.xml @@ -492,6 +492,8 @@ systemd1 sysupdate.d5 + sysupdate.features5 + sysupdate.components5 systemd-sysupdated.service8 systemd-repart8 diff --git a/man/sysupdate.components.xml b/man/sysupdate.components.xml new file mode 100644 index 00000000000..54cec98c7c8 --- /dev/null +++ b/man/sysupdate.components.xml @@ -0,0 +1,292 @@ + + + + + + + + sysupdate.components + systemd + + + + sysupdate.components + 5 + + + + sysupdate.components + Definition Files for Update Components + + + + + /etc/sysupdate.component.component + /run/sysupdate.component.component + /usr/local/lib/sysupdate.component.component + /usr/lib/sysupdate.component.component + + + + + Description + + A "Component" is a set of + sysupdate.d5 + transfer definitions that + systemd-sysupdate8 + updates independently from the rest of the OS. + Each component is a self-contained installation with its own version, and its own set of transfer files, + stored in a directory named after the component: + sysupdate.component.d/*.transfer (as opposed to the + default, component-less sysupdate.d/*.transfer). + Components are selected via the , or + switches of + systemd-sysupdate8, and + enumerated by its components command. + + Because components are updated separately, they are the right tool for OS resources that shall be + versioned and updated independently from the base OS — for example a container image or a portable service + image that follows its own release cycle. This is the primary difference between a component and an + sysupdate.features5 + Optional Feature: the transfers belonging to a feature are updated in lock-step with the target they are + part of, while a component is a wholly separate installation. Do not use a component for resources that + shall always be updated synchronously with something else; use a feature (or simply additional transfer + files in the same directory) for those cases. + + A component does not require a *.component file: as soon as a matching + sysupdate.component.d/ directory with transfer definitions + exists, the component is available for updating. The *.component file described here + is optional, and carries metadata about the component (such as a human-readable description and a + documentation URL) as well as its enablement state. + + When a component is disabled (via Enabled=false, see below), operations that + would download or install new versions — most importantly update — refuse to act on + it. Other operations, such as vacuum and cleanup, continue to + consider the component's transfers so that previously installed instances remain managed and can be + cleaned up. Components are enabled or disabled with the enable-component and + disable-component commands of + systemd-sysupdate8, + which write an Enabled= setting into a drop-in next to the component definition. + + Component definitions support drop-in files, which are most commonly used to override the + Enabled= setting. Drop-ins are read from + sysupdate.component.component.d/*.conf in the same set of + directories as the main file. They can also be masked to hide the component definition entirely. + + Each *.component file contains one section: [Component]. + + + + [Component] Section Options + + This section defines general properties of this component. + + + + Description= + + A short human-readable description of this component. + This may be used as a label for this component, so the string should meaningfully identify the + component among the components available on the system. + + + + + + Documentation= + + A user-presentable URL to documentation about this component. + This setting supports specifier expansion; see below for details on supported specifiers. + + + + + + Enabled= + + Whether or not this component is enabled. If unspecified, the component is enabled + by default. When disabled, systemd-sysupdate refuses to download or install new + versions of this component, but continues to consider its transfers while vacuuming and in other + situations where it needs to determine ownership over previously downloaded system resources. + + + + + + Suggest= + + Takes a boolean argument. If true, this component is suggested for enablement, if + false it is not. This does not enable the component on its own, but is a hint surfaced by the update + tools (for example via the switch of + systemd-sysupdate8) + so that the system administrator or higher-level tooling may act on it. + + If this setting is not specified, the SuggestOn…= conditions described below + are evaluated instead to determine whether the component is suggested. If neither this setting nor any + SuggestOn…= condition is specified, the component is not suggested. + + + + + + SuggestOnArchitecture= + SuggestOnFirmware= + SuggestOnVirtualization= + SuggestOnHost= + SuggestOnFraction= + SuggestOnKernelCommandLine= + SuggestOnVersion= + SuggestOnCredential= + SuggestOnSecurity= + SuggestOnOSRelease= + SuggestOnMachineTag= + + Suggest this component for enablement depending on system properties. These settings + take the same arguments and implement the same semantics — including the leading ! + for negation — as the identically-named + ConditionArchitecture=, ConditionFirmware=, + ConditionVirtualization=, ConditionHost=, + ConditionFraction=, ConditionKernelCommandLine=, + ConditionVersion=, ConditionCredential=, + ConditionSecurity=, ConditionOSRelease= and + ConditionMachineTag= settings for unit files, which are documented in + systemd.unit5. + The component is suggested if all specified conditions apply. As with the Condition…= + settings, assigning an empty string to one of these resets the list. + + These conditions are only evaluated if Suggest= is not specified. + + + + + + + + Specifiers + + Specifiers may be used in the Documentation= setting. The following expansions + are understood: + + + Specifiers available + + + + + + + Specifier + Meaning + Details + + + + + + + + + + + + + + + + + + + + +
+ + + + Examples + + + A Separately Updated Container Image + + We'll use the hypothetical "foobarOS" described in + sysupdate.d5 as our + example base OS. + foobarOS ships a container image that many, but not all, deployments want to run. The image has its own + release cadence and version number, entirely separate from the base OS, so it is a poor fit for an + Optional Feature (which would be version-locked to the OS). Instead, let's model it as a component named + webapp. + + First, the component definition, carrying its metadata and marking it as disabled by default: + + # /usr/lib/sysupdate.webapp.component +[Component] +Description=WebApp Container Image +Documentation=https://docs.example.com/foobarOS/webapp +Enabled=false + + + Next, the transfer definition for the component, placed in the component's own directory + sysupdate.webapp.d/: + + # /usr/lib/sysupdate.webapp.d/50-webapp.transfer +[Source] +Type=url-file +Path=https://download.example.com/ +MatchPattern=webapp_@v.raw.xz + +[Target] +Type=regular-file +Path=/var/lib/machines +MatchPattern=webapp_@v.raw +Mode=0444 +InstancesMax=2 + + + With these two files, updates for the webapp component can be checked and + downloaded independently of the base OS, for example with + systemd-sysupdate --component=webapp update. Because + Enabled=false was set, the administrator must first opt in with + systemd-sysupdate enable-component webapp, which writes the following drop-in: + + # /etc/sysupdate.webapp.component.d/50-systemd-sysupdate-enabled.conf +# Generated via 'systemd-sysupdate enable-component' + +[Component] +Enabled=true + + + + + A Component Suggested Only on Bare Metal + + Suppose foobarOS ships a component with firmware and microcode updates that is only relevant when + running on physical hardware, not inside a virtual machine. We can use SuggestOn…= to + hint that the component should be enabled in that case, without enabling it automatically: + + # /usr/lib/sysupdate.firmware.component +[Component] +Description=Firmware and Microcode Updates +Documentation=https://docs.example.com/foobarOS/firmware +Enabled=false +SuggestOnVirtualization=!vm + + + Higher-level tooling can now query the suggested components (via + systemd-sysupdate --component-suggested …) and enable them as appropriate. On bare + metal the firmware component is suggested; inside a VM it is not. + + + + + See Also + + systemd1 + systemd-sysupdate8 + sysupdate.d5 + sysupdate.features5 + + + + diff --git a/man/sysupdate.d.xml b/man/sysupdate.d.xml index 29daeda81a0..9c27bf444a0 100644 --- a/man/sysupdate.d.xml +++ b/man/sysupdate.d.xml @@ -1068,6 +1068,8 @@ CurrentSymlink=myContainer systemd1 systemd-sysupdate8 + sysupdate.features5 + sysupdate.components5 systemd-repart8 diff --git a/man/sysupdate.features.xml b/man/sysupdate.features.xml index d3a7a638101..29f067f61ba 100644 --- a/man/sysupdate.features.xml +++ b/man/sysupdate.features.xml @@ -381,6 +381,7 @@ InstancesMax=2 systemd1 systemd-sysupdate8 sysupdate.d5 + sysupdate.components5