SYSUPDATE.COMPONENTS(5)

✨ SYSUPDATE.COMPONENTS(5) ✨

okay so you found the page for sysupdate.components — the definition files for update components — and bestie, this one is lowkey a whole vibe. it's long so buckle up, we're doing it in parts 💖

---

🌸 NAME 🌸

sysupdate.components — Definition Files for Update Components

no cap, that's literally the whole name. short. sweet. iconic.

---

🎀 SYNOPSIS 🎀

/etc/sysupdate.component.component
/run/sysupdate.component.component
/usr/local/lib/sysupdate.component.component
/usr/lib/sysupdate.component.component

those are the four places the system goes looking for your component files, in order. yes, the filename pattern really is .component.component, she said what she said 💅

---

🦋 DESCRIPTION 🦋

so. a "Component" is a set of sysupdate.d(5) transfer definitions that systemd-sysupdate(8) updates independently from the rest of the OS. like, it does its own thing, on its own schedule, main character energy fr fr.

every component is a self-contained installation with its own version and its own lil set of transfer files, and those live in a directory named after the component:

sysupdate.component.d/*.transfer

which is different from the default, component-less:

sysupdate.d/*.transfer

you pick components with the --component=, --component-all or --component-suggested switches of systemd-sysupdate(8), and you can list them all out with its components command. cute, right?

why would you even want this? because components update separately, they're the correct tool for OS resources that should be versioned and updated independently from the base OS — think a container image, or a portable service image that marches to the beat of its own release cycle. 🥁

and this is THE key difference between a component and an sysupdate.features(5) Optional Feature: the transfers belonging to a feature get updated in lock-step with the target they're part of, but a component is a wholly separate installation. so like —

do not use a component for stuff that should always be updated synchronously with something else. use a feature (or honestly just more transfer files in the same directory) for those cases. no cap, this matters.

now, a component does not require a *.component file. the second a matching sysupdate.component.d/ directory with transfer definitions exists, the component is available for updating. periodt. the *.component file we're describing here is optional — it just carries metadata about the component (like a human-readable description and a documentation URL) plus its enablement state.

when a component is disabled (via Enabled=false, keep reading bestie), operations that would download or install new versions — most importantly update — straight up refuse to act on it. 🙅 but other operations, like vacuum and cleanup, still consider the component's transfers so that previously installed instances stay managed and can be cleaned up. we love a graceful exit.

components get 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. sneaky but organized. 🫶

component definitions support drop-in files, 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. poof. gone. 💀

each *.component file contains one section: [Component]. that's it. that's the whole section list.

---

💜 [COMPONENT] SECTION OPTIONS 💜

this section defines the general properties of this component. let's go one by one, we're not skipping a single one 🍓

• Description= — a short human-readable description of this component. this may be used as a label for it, so the string should meaningfully identify the component among all the components available on the system. (so like, not "thing1". be descriptive.)

Added in version 262.

• 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.

Added in version 262.

• 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.

Added in version 262.

• 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 — it's a hint surfaced by the update tools (for example via the --component-suggested switch of systemd-sysupdate(8)) so 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. ngl, that's the default and it's fine.

Added in version 262.

• 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.

heads up: these conditions are only evaluated if Suggest= is not specified. don't be confused when one overrides the other, that's on purpose.

Added in version 262.

---

to be continued… ✨ keep scrolling bestie, there's more where that came from

✨ SPECIFIERS ✨

okay so bestie, Documentation= is not just plain text — you can drop specifiers in there and they get expanded into real live values from your system. Here's the whole menu of what gets understood:

Table 1. Specifiers available — but honestly it's a vibe-check list now, keep scrolling 💅

• "%a" — Architecture 🏗️ A short string that IDs the architecture of the local system. Like a string such as x86, x86-64 or arm64. Wanna see the full roster? Peep the architectures defined for ConditionArchitecture= in systemd.unit(5). That's the whole list, no cap.
• "%A" — Operating system image version 🖼️ The operating system image version identifier of the running system, read straight from the IMAGE_VERSION= field of /etc/os-release. If it's not set, it resolves to an empty string. More deets in os-release(5).
• "%b" — Boot ID 🥾 The boot ID of the running system, formatted as a string. random(4) has more for you.
• "%B" — Operating system build ID 🔨 The operating system build identifier of the running system, read from the BUILD_ID= field of /etc/os-release. If not set → empty string. Again, os-release(5) is your girl.
• "%H" — Host name 💻 The hostname of the running system. Periodt.
• "%l" — Short host name ✂️ The hostname of the running system, but truncated at the first dot so any domain component just… goes away. Iconic honestly.
• "%m" — Machine ID 🆔 The machine ID of the running system, formatted as a string. machine-id(5) has the lore.
• "%M" — Operating system image identifier 🎀 The operating system image identifier of the running system, read from the IMAGE_ID= field of /etc/os-release. If not set, empty string. os-release(5), go read her.
• "%o" — Operating system ID 🍓 The operating system identifier of the running system, read from the ID= field of /etc/os-release. os-release(5) for more.
• "%v" — Kernel release 🐧 Literally identical to uname -r output. Same thing. Twin behavior.
• "%w" — Operating system version ID 📌 The operating system version identifier of the running system, read from the VERSION_ID= field of /etc/os-release. If not set, it resolves to an empty string. os-release(5) knows.
• "%W" — Operating system variant ID 🌈 The operating system variant identifier of the running system, read from the VARIANT_ID= field of /etc/os-release. If not set, empty string. Yep — os-release(5).
• "%T" — Directory for temporary files 🗂️ This is either /tmp or whatever path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Heads up: 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. (Same note, bestie: the directory may be specified without a trailing slash.)
• "%%" — Single percent sign ✨ Use "%%" in place of "%" to specify a single percent sign. Escaping queen 👑

---

quick vibe check — the ones reading from /etc/os-release ("%A", "%B", "%M", "%o", "%w", "%W") all say the same thing when the field isn't there: empty string. Not an error, not a crash, just ✨ nothing ✨. Don't be surprised.

✨ EXAMPLES ✨

okay bestie, this is the part where it all clicks, I promise 💖 let's look at two whole little scenarios so you can see how components actually come together in the wild.

🌸 Example 1. A Separately Updated Container Image 🌸

so we're gonna use the hypothetical "foobarOS" from sysupdate.d(5) as our example base OS, mwah. foobarOS ships a container image that lots of deployments want to run, but not all of them. and here's the thing — that image has its own whole release cadence and version number, completely separate from the base OS. so it's honestly a terrible fit for an Optional Feature (that would get version-locked to the OS, ew). instead, let's model it as a component named webapp 🎀

first up: the component definition. it carries its metadata and marks itself 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 — and no, it does not live with the others, it goes 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 in place, updates for the webapp component can be checked and downloaded independently of the base OS — for example with systemd-sysupdate --component=webapp update. iconic behaviour, no cap 💅

and because Enabled=false was set, the administrator has to opt in first with systemd-sysupdate enable-component webapp, which writes this little drop-in for you:

# /etc/sysupdate.webapp.component.d/50-systemd-sysupdate-enabled.conf
# Generated via 'systemd-sysupdate enable-component'

[Component]
Enabled=true

and boom, you're updated. she's serving, she's versioned, she's not touching the base OS 🦋

---

🌈 Example 2. A Component Suggested Only on Bare Metal 🌈

okay so imagine foobarOS ships a component with firmware and microcode updates, right? but it's only relevant when you're running on physical hardware — not inside a virtual machine. rude to VMs, honestly. so we use SuggestOn...= to hint that the component should be enabled in that case, without just enabling it automatically behind your back:

# /usr/lib/sysupdate.firmware.component
[Component]
Description=Firmware and Microcode Updates
Documentation=https://docs.example.com/foobarOS/firmware
Enabled=false
SuggestOnVirtualization=!vm

and now higher-level tooling can 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. the way that works is genuinely so satisfying 🫶

ngl, SuggestOn...= is a hint, not an order — it tells tooling what it could enable, it does not enable anything by itself ✨

---

👀 SEE ALSO 👀

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

---

and that's the whole page, bestie!! 🎉 you made it all the way through, I'm so proud of you. this one came from systemd 262.1, and it's the SYSUPDATE.COMPONENTS(5) manual page — go forth and component-ify your updates responsibly, mwah 💖✨💅