[PATCH v3 13/14] Documentation: Update support

[Demi Marie Obenour <demiobenour@gmail.com>]

The documentation previously stated that updates were not possible
without reinstalling.  This is no longer the case, so correct the
outdated documentation and explain how to enable updates for images one
builds.

Signed-off-by: Demi Marie Obenour <demiobenour@gmail.com>
---
Changes since v2:
- Move the documentation on how to enable updates to the part on build
  configuration.
- Clarify what happens if an update is interrupted.
- Move details to a technical note.
- Link to systemd-sysupdate.
---
 Documentation/development/build-configuration.adoc | 13 ++++++++++
 Documentation/installation/getting-spectrum.adoc   | 25 +++++++++++++-----
 Documentation/installation/index.adoc              |  4 ++-
 Documentation/using-spectrum/index.adoc            |  2 ++
 Documentation/using-spectrum/updates.adoc          | 30 ++++++++++++++++++++++
 5 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/Documentation/development/build-configuration.adoc b/Documentation/development/build-configuration.adoc
index 545aa8c05ac40a101b5ee280015cde7ec4f3a66f..24672802d2395b9ba124baeba433bf2c4fc59193 100644
--- a/Documentation/development/build-configuration.adoc
+++ b/Documentation/development/build-configuration.adoc
@@ -20,6 +20,19 @@ The configuration file should contain an attribute set.  See
 https://spectrum-os.org/git/spectrum/tree/lib/config.default.nix[lib/config.default.nix]
 for supported configuration attributes and their default values.
 
+To enable updates, you need to specify a version, an update URL, and an update signing key.
+By default, the update URL is set to a .invalid domain and the update signing key is
+an invalid key.  Therefore, updates will not work.  To enable updates, provide a valid key
+and update server URL.  Spectrum uses
+https://www.freedesktop.org/software/systemd/man/latest/systemd-sysupdate.html[systemd-sysupdate],
+so see the https://www.freedesktop.org/software/systemd/man/latest/sysupdate.d.html[sysupdate.d]
+documentation for what you need to put on your server.  Building
+https://spectrum-os.org/git/spectrum/tree/release/updates.nix[release/updates.nix] produces an
+directory that is compatible with systemd-sysupdate, except that the signature (`SHA256SUMS.gpg`)
+is missing.
+
+Updates are signed, so the worst a compromised update server can do is fill up your home directory.
+
 .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/unstable/#sec-overlays-definition[Nixpkgs overlay]
 [example]
 [source,nix]
diff --git a/Documentation/installation/getting-spectrum.adoc b/Documentation/installation/getting-spectrum.adoc
index e7806e0f92793320bf0cdcbdd11dbc4e713275c7..0abc83a9e6fc01084b3faa9b93eb38398b0aef27 100644
--- a/Documentation/installation/getting-spectrum.adoc
+++ b/Documentation/installation/getting-spectrum.adoc
@@ -86,13 +86,24 @@ a menu allowing you to "Install Spectrum".
 
 NOTE: While it's possible to install Spectrum to your internal
 storage, at this point in Spectrum's development there is not much
-reason to, as OS updates are not yet implemented, and persistent
-storage is not yet exposed to VMs.  Using the "Try Spectrum" option to
-boot Spectrum will let you try out everything in Spectrum, without
-having to go through the additional step of reinstalling Spectrum
-every time you want to use a newer version.
+reason to, as persistent storage is not yet exposed to VMs.
+
+Currently, Spectrum does not provide an update server, so
+you must provide your own.  You can do this via
+xref:../development/build-configuration.adoc[build configuration].
+The default sets the signing key to `/dev/null` and the server
+URL to an invalid value, so updates won't work.  To enable updates,
+set `update-url` to the URL of your server and `update-signing-key`
+to a binary GnuPG keyring to verify the updates with.  Not all possible
+URLs will work, but most invalid URLs will cause an error during the
+build rather than runtime misbehavior.
+
+In the running system, the signing key is located at
+`/etc/systemd/import-pubring.gpg`.  The update URL is in various files
+under `/etc/updates`.  These files are read-only, but one can mount
+an overlayfs on top of `/etc/systemd` and `/etc/updates` if one wants
+to make changes.
 
 CAUTION: Do not use Spectrum for anything important or sensitive as it is not
 yet suitable for real-world use.  Many important security properties are
-currently missing, and there is no procedure for updating to
-new versions—you have to reinstall the OS.
+currently missing.
diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc
index d67c88dda062066c19c3b21e699f074cc18a6dbc..c61092c93a3965b6c4014aeaee9090532634c9be 100644
--- a/Documentation/installation/index.adoc
+++ b/Documentation/installation/index.adoc
@@ -18,6 +18,8 @@ development.
 
 == Uninstalling and Updating
 
-Currently, there is no implementation for a software update.
+Software updates are a work in progress.  If you built Spectrum yourself,
+xref:../development/build-configuration.adoc[Build configuration] for how
+to enable updates for it.
 
 You can replace Spectrum by installing another OS.
diff --git a/Documentation/using-spectrum/index.adoc b/Documentation/using-spectrum/index.adoc
index 25347a4ed7bb1f899ee0a3b85aa51da94bb954b4..5d9ea657f7c6f8c21edbf8637d2d2d0bf52f931d 100644
--- a/Documentation/using-spectrum/index.adoc
+++ b/Documentation/using-spectrum/index.adoc
@@ -11,3 +11,5 @@ Ready to get started with Spectrum? Here is what you can do next:
 
 * xref:running-vms.adoc[Start some applications].
 * xref:creating-custom-vms.adoc[Create your own VM] to use other applications.
+* xref:updates.adoc[Enable updates] so you can use newer versions of Spectrum
+  without reinstalling the OS.
diff --git a/Documentation/using-spectrum/updates.adoc b/Documentation/using-spectrum/updates.adoc
new file mode 100644
index 0000000000000000000000000000000000000000..64f085bf1e721b46076b86228adb8e86b3e5c57d
--- /dev/null
+++ b/Documentation/using-spectrum/updates.adoc
@@ -0,0 +1,30 @@
+= 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.

-- 
2.52.0