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.
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=¶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 --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= setting. 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.