sysupdate.components — Definition Files for Update Components
/etc/sysupdate. |
/run/sysupdate. |
/usr/local/lib/sysupdate. |
/usr/lib/sysupdate. |
A "Component" is a set of
sysupdate.d(5)
transfer definitions that
systemd-sysupdate(8)
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. (as opposed to the
default, component-less component.d/*.transfersysupdate.d/*.transfer).
Components are selected via the --component=, --component-all or
--component-suggested switches of
systemd-sysupdate(8), 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.features(5) 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.
Besides being defined in the file system, components may also be provided dynamically by component providers, i.e. services implementing a Varlink interface, see below. Components defined in the file system always take precedence over those offered by providers.
A component does not require a *.component file: as soon as a matching
sysupdate. directory with transfer definitions
exists, the component is available for updating. The component.d/*.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-sysupdate(8),
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. in the same set of
directories as the main file. They can also be masked to hide the component definition entirely.component.component.d/*.conf
Each *.component file contains one section: [Component].
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=¶One or more user-presentable URLs to documentation about this component. This setting may be specified more than once. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect. It 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.
SuccessAction=¶Controls what to do after an update of this component has been installed
successfully, when multiple components are updated in one go (i.e. when
systemd-sysupdate update is invoked with --component-all). Takes
one of "continue" or "restart". If "continue",
the update logic proceeds with the next component. If "restart", the remaining
components are skipped and the current update iteration is finished early, so that the next
iteration starts from the beginning, re-reading all definition files. This is useful for components
that make new transfer files (or components) available, which should be processed before any other
components are updated. Note that the next iteration is only started if the
--loop= switch permits it, see
systemd-sysupdate(8)
for details. Defaults to "continue".
FailureAction=¶Controls what to do if updating this component failed, when multiple components are
updated in one go (i.e. when systemd-sysupdate update is invoked with
--component-all). Takes one of "continue" or
"fail". If "continue", the failure is logged, and the update logic
proceeds with the next component (and possibly further update iterations, see
--loop=), but the tool returns the first error encountered once it is done. If
"fail", the remaining components are skipped and the tool fails immediately.
Defaults to "continue".
MinVersion=, MaxVersion=¶Specifies the minimum resp. maximum version to permit for all transfers of this
component, with the same semantics as the settings of the same name in the [Transfer] section of
sysupdate.d(5):
versions older than MinVersion= are considered obsolete, versions newer than
MaxVersion= are considered too new, and neither are selected for updating. If
a transfer of the component specifies its own bounds, the more restrictive one applies. Both
settings support specifier expansion.
ProtectVersion=¶Takes one or more version strings to mark as "protected" for all transfers of this component, with the same semantics as the setting of the same name in the [Transfer] section of sysupdate.d(5): protected versions are never removed while making room for new versions. Versions listed here are added to those a transfer protects on its own. This setting supports specifier expansion.
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 --component-suggested switch of
systemd-sysupdate(8))
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.unit(5).
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 may be used in the Documentation=, MinVersion=,
MaxVersion= and ProtectVersion= settings. The following expansions
are understood:
Table 1. Specifiers available
| Specifier | Meaning | Details |
|---|---|---|
"%a" | Architecture | A short string identifying the architecture of the local system. A string such as x86, x86-64 or arm64. See the architectures defined for ConditionArchitecture= in systemd.unit(5) for a full list. |
"%A" | Operating system image version | The operating system image version identifier of the running system, as read from the IMAGE_VERSION= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%b" | Boot ID | The boot ID of the running system, formatted as string. See random(4) for more information. |
"%B" | Operating system build ID | The operating system build identifier of the running system, as read from the BUILD_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%H" | Host name | The hostname of the running system. |
"%l" | Short host name | The hostname of the running system, truncated at the first dot to remove any domain component. |
"%m" | Machine ID | The machine ID of the running system, formatted as string. See machine-id(5) for more information. |
"%M" | Operating system image identifier | The operating system image identifier of the running system, as read from the IMAGE_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%o" | Operating system ID | The operating system identifier of the running system, as read from the ID= field of /etc/os-release. See os-release(5) for more information. |
"%v" | Kernel release | Identical to uname -r output. |
"%w" | Operating system version ID | The operating system version identifier of the running system, as read from the VERSION_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%W" | Operating system variant ID | The operating system variant identifier of the running system, as read from the VARIANT_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%T" | Directory for temporary files | This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Note that the directory may be specified without a trailing slash.) |
"%V" | Directory for larger and persistent temporary files | This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Note that the directory may be specified without a trailing slash.) |
"%%" | Single percent sign | Use "%%" in place of "%" to specify a single percent sign. |
Example 1. A Separately Updated Container Image
We'll use the hypothetical "foobarOS" described in
sysupdate.d(5) 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
Example 2. 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.
In addition to the component definitions found in the file system,
systemd-sysupdate(8)
acquires component definitions from component providers: services that bind an
AF_UNIX stream socket into the /run/systemd/sysupdate/provider/
directory (directly or via a symlink) and implement the io.systemd.SysUpdate.Provider
Varlink interface on it. It is recommended to name the socket
after the service implementing it, in reverse domain name notation. A provider may define additional
components, each carrying the same kind of information as the component definition files described
above, and the feature and transfer definition files described in
sysupdate.features(5)
and sysupdate.d(5).
Note that, unlike in the configuration files, no specifier expansion is applied to strings returned by
a provider, and the SuggestOn…= conditions are not available. Providers are only
consulted while operating on the host (i.e. when none of --root=,
--image=, or --definitions= are used). Providers may run unprivileged: whoever is able to
place a socket in the directory is trusted.
The set of components systemd-sysupdate operates on is the union of the
components defined in the file system and those defined by providers. Components defined in the file
system take precedence: if the file system defines a component — i.e. a
sysupdate. file, or any feature or
transfer definition file in component.componentsysupdate.
exists — a provider's definition of a component by the same name is ignored. If multiple providers
define the same component, the definition of the provider whose socket name sorts first is used, and a
message is logged. The default component (i.e. component.d/sysupdate.d/) is always taken from
the file system.
Instead of pointing its transfers to resources on a web server, a provider may also serve these
resources itself. In that case, it must implement the generic
io.systemd.ResourceProvider Varlink interface (typically on the same socket), and
use URLs of the form
"provider:[/run/systemd/sysupdate/provider/"
in the name]/resourcePath= field of the sources of its transfers, see
sysupdate.d(5) for
details.
Since the definitions of provider-backed components do not live in the file system, the enable-component, disable-component, enable-feature and disable-feature commands of systemd-sysupdate refuse to operate on them; it is up to the provider to expose the enablement state it deems appropriate. If a provider that is present cannot be queried successfully (for example because it fails or times out), systemd-sysupdate treats the components it might define as being of unknown state rather than as removed, so that the cleanup command does not remove resources belonging to them.