NAME¶

sysupdate.components - Definition Files for Update Components

SYNOPSIS¶

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.

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=

Documentation=

Enabled=

Suggest=

SuggestOnArchitecture=, SuggestOnFirmware=, SuggestOnVirtualization=, SuggestOnHost=, SuggestOnFraction=, SuggestOnKernelCommandLine=, SuggestOnVersion=, SuggestOnCredential=, SuggestOnSecurity=, SuggestOnOSRelease=, SuggestOnMachineTag=

SPECIFIERS¶

Specifiers may be used in the Documentation= setting. The following expansions are understood:

Table 1. Specifiers available

EXAMPLES¶

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.

SEE ALSO¶

systemd(1), systemd-sysupdate(8), sysupdate.d(5), sysupdate.features(5)