sysupdate.components

systemd

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.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.component.d/*.transfer (as opposed to the default, component-less sysupdate.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.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-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.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=
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

Specifiers may be used in the Documentation=, MinVersion=, MaxVersion= and ProtectVersion= settings. The following expansions are understood:

Specifier	Meaning	Details

Specifiers available {.specifiers}

Examples

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

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.

Component Providers

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.component.component file, or any feature or transfer definition file in sysupdate.component.d/ 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. 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/name]/resource in the Path= 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.