= Updating the OS
:page-parent: Using Spectrum

// SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0

Spectrum supports updates via the `spectrum-update` command.  This
takes the path to a staging directory as argument.  This directory
must be on a BTRFS filesystem.

Updates are atomic and take effect after the system reboots.
If the system is rebooted, crashes, or loses power during an
update, the update will not take effect.  Updates are digitally
signed and Spectrum will refuse to install an update that does
not have a trusted signature.

See xref:../development/build-configuration.adoc[build configuration]
for what is needed for updates to work.  The actual update is done using
https://www.freedesktop.org/software/systemd/man/systemd-sysupdate.html[systemd-sysupdate].
See its documentation for the details.

== Technical Note

Since Spectrum's host has no network access, the VM that does the
updates (`sys.appvm-systemd-sysupdate`) is given a BTRFS subvolume to
write the updates into.  It uses `systemd-sysupdate` to download the updates
into this directory.  Once it exits, the host snapshots this directory and
checks it for malicious filenames or non-regular files.  If the check
passes, this directory is used as the source for `systemd-sysupdate`,
which installs the updates to the OS volume and EFI system partition.