From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from atuin.qyliss.net (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id A77E54649; Tue, 25 Nov 2025 18:00:24 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 993) id 4B6D2461F; Tue, 25 Nov 2025 18:00:21 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-26) on atuin.qyliss.net X-Spam-Level: X-Spam-Status: No, score=-0.8 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,DMARC_MISSING,RCVD_IN_DNSWL_LOW,SPF_HELO_PASS autolearn=unavailable autolearn_force=no version=4.0.1 Received: from fout-a3-smtp.messagingengine.com (fout-a3-smtp.messagingengine.com [103.168.172.146]) by atuin.qyliss.net (Postfix) with ESMTPS id 62E0C461D for ; Tue, 25 Nov 2025 18:00:19 +0000 (UTC) Received: from phl-compute-02.internal (phl-compute-02.internal [10.202.2.42]) by mailfout.phl.internal (Postfix) with ESMTP id 9A48AEC0413; Tue, 25 Nov 2025 13:00:17 -0500 (EST) Received: from phl-mailfrontend-02 ([10.202.2.163]) by phl-compute-02.internal (MEProxy); Tue, 25 Nov 2025 13:00:17 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=alyssa.is; h=cc :cc:content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm2; t=1764093617; x=1764180017; bh=yB1HFNchTu bLKsxHG0y2Dm7A9yPpKEp9AEpkP701pmI=; b=GObIlcWSpwBOHorCZgcAp7EoCX iS0R5XZU9vTxIT+4bdoAjSBRA5XVKPd5AxBoTP9zjzm+CtweqkxQGhx99Rx9Z1vc iV34+Z72e3eNYzZ7p/zLZlXDKkqQHK7GeCRWGkcLj3xwmjItqgrTmUmXUBMmShva K9RsiKTMPwVPybtE4sBON9qvVn2hIqqnyK8iAcI77LrzCaghkoaoRT9meDRkMIj8 eVSLeCT5ye9TyD4cVzgV9Fl5M8DtzcxfVsAI8vpDPCe6Bw8GFeKmUoaTqn3TuOnh 6egIg8U+0XHg4HT2GE+CS3xapg8XyfS/Zzz2G60pnH4TVkeod6stRPJ4i12Q== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; t= 1764093617; x=1764180017; bh=yB1HFNchTubLKsxHG0y2Dm7A9yPpKEp9AEp kP701pmI=; b=UJdkPVYTwf6NFJkbno9vUiTY8RALY1SmtetuadN8qfl7wA1Irfp NEuYKv9cZx5QNmDYzNoVIEyu2uSG8RCTZGfm130xDcc2A7JacJrWaLk4k8/Ni1tp nA8w0qxWWKhnNKkKuDlbPyr/Nz324gBfCEB8BY2wac2Vlu9kMdb6eThw5QHXrCH8 rQG1k6YZZqvgVvA+miOf84IccLhrOvAx3BoxrWUhKw2z27Gzsq6JQeJ5xjgY8FyT 8UzM+41U5+he//1e1Xf1KoQOEpvMU0ONhvA94PtJqw0ocHeKPb3YVemIKpdX87uB Yi0f8TOrXS70IiwhQ4jmfvsgYoacI9fHJpQ== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeffedrtdeggddvgedvudefucetufdoteggodetrf dotffvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfurfetoffkrfgpnffqhgenuceu rghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmnecujf gurhephffvvefujghffffkgggtsehgtderredttdejnecuhfhrohhmpeetlhihshhsrgcu tfhoshhsuceohhhisegrlhihshhsrgdrihhsqeenucggtffrrghtthgvrhhnpeffheegud fffeejueekvdfgueektddvieekgfekudeugedvgefgfeeitddvjedttdenucffohhmrghi nhepshhpvggtthhruhhmqdhoshdrohhrghdpfhhrvggvuggvshhkthhophdrohhrghdpnh higihoshdrohhrghenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhl fhhrohhmpehhihesrghlhihsshgrrdhishdpnhgspghrtghpthhtohepvddpmhhouggvpe hsmhhtphhouhhtpdhrtghpthhtohepuggvmhhiohgsvghnohhurhesghhmrghilhdrtgho mhdprhgtphhtthhopeguvghvvghlsehsphgvtghtrhhumhdqohhsrdhorhhg X-ME-Proxy: Feedback-ID: i12284293:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 25 Nov 2025 13:00:17 -0500 (EST) Received: by fw12.qyliss.net (Postfix, from userid 1000) id 24CA725FDF4F; Tue, 25 Nov 2025 19:00:01 +0100 (CET) From: Alyssa Ross To: Demi Marie Obenour , Spectrum OS Development Subject: Re: [PATCH v4 13/14] Documentation: Update support In-Reply-To: <20251121-updates-v4-13-d4561c42776e@gmail.com> References: <20251121-updates-v4-0-d4561c42776e@gmail.com> <20251121-updates-v4-13-d4561c42776e@gmail.com> Date: Tue, 25 Nov 2025 19:00:00 +0100 Message-ID: <87jyze0z8f.fsf@alyssa.is> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Message-ID-Hash: W5HPIDERJM36TS76PJPDEEO676DQ3WQN X-Message-ID-Hash: W5HPIDERJM36TS76PJPDEEO676DQ3WQN X-MailFrom: hi@alyssa.is X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-devel.spectrum-os.org-0; header-match-devel.spectrum-os.org-1; header-match-devel.spectrum-os.org-2; header-match-devel.spectrum-os.org-3; header-match-devel.spectrum-os.org-4; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Demi Marie Obenour X-Mailman-Version: 3.3.9 Precedence: list List-Id: Patches and low-level development discussion Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Demi Marie Obenour writes: > 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 > --- > 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/Documen= tation/development/build-configuration.adoc > index 545aa8c05ac40a101b5ee280015cde7ec4f3a66f..24672802d2395b9ba124baeba= 433bf2c4fc59193 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/con= fig.default.nix] > for supported configuration attributes and their default values. >=20=20 > +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 si= gning key is > +an invalid key. Therefore, updates will not work. To enable updates, p= rovide a valid key > +and update server URL. Spectrum uses > +https://www.freedesktop.org/software/systemd/man/latest/systemd-sysupdat= e.html[systemd-sysupdate], > +so see the https://www.freedesktop.org/software/systemd/man/latest/sysup= date.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/up= dates.nix] produces an > +directory that is compatible with systemd-sysupdate, except that the sig= nature (`SHA256SUMS.gpg`) > +is missing. > + > +Updates are signed, so the worst a compromised update server can do is f= ill up your home directory. User data partition. No home directories in Spectrum. > + > .config.nix to build Spectrum with a https://nixos.org/manual/nixpkgs/un= stable/#sec-overlays-definition[Nixpkgs overlay] > [example] > [source,nix] > diff --git a/Documentation/installation/getting-spectrum.adoc b/Documenta= tion/installation/getting-spectrum.adoc > index e7806e0f92793320bf0cdcbdd11dbc4e713275c7..0abc83a9e6fc01084b3faa9b9= 3eb38398b0aef27 100644 > --- a/Documentation/installation/getting-spectrum.adoc > +++ b/Documentation/installation/getting-spectrum.adoc > @@ -86,13 +86,24 @@ a menu allowing you to "Install Spectrum". >=20=20 > 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. I don't think this is something we should be encouraging in user documentation. From a user point of view, updates are not available yet. We don't need to go any further than changing from saying "updates are not supported yet" to "updates are not available yet". > CAUTION: Do not use Spectrum for anything important or sensitive as it i= s not > yet suitable for real-world use. Many important security properties are > -currently missing, and there is no procedure for updating to > -new versions=E2=80=94you have to reinstall the OS. > +currently missing. > diff --git a/Documentation/installation/index.adoc b/Documentation/instal= lation/index.adoc > index d67c88dda062066c19c3b21e699f074cc18a6dbc..c61092c93a3965b6c4014aeae= e9090532634c9be 100644 > --- a/Documentation/installation/index.adoc > +++ b/Documentation/installation/index.adoc > @@ -18,6 +18,8 @@ development. >=20=20 > =3D=3D Uninstalling and Updating >=20=20 > -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. >=20=20 > You can replace Spectrum by installing another OS. > diff --git a/Documentation/using-spectrum/index.adoc b/Documentation/usin= g-spectrum/index.adoc > index 25347a4ed7bb1f899ee0a3b85aa51da94bb954b4..5d9ea657f7c6f8c21edbf8637= d2d2d0bf52f931d 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 ca= n do next: >=20=20 > * xref:running-vms.adoc[Start some applications]. > * xref:creating-custom-vms.adoc[Create your own VM] to use other applica= tions. > +* xref:updates.adoc[Enable updates] so you can use newer versions of Spe= ctrum > + without reinstalling the OS. > diff --git a/Documentation/using-spectrum/updates.adoc b/Documentation/us= ing-spectrum/updates.adoc > new file mode 100644 > index 0000000000000000000000000000000000000000..64f085bf1e721b46076b86228= adb8e86b3e5c57d > --- /dev/null > +++ b/Documentation/using-spectrum/updates.adoc > @@ -0,0 +1,30 @@ > +=3D Updating the OS > +:page-parent: Using Spectrum > + > +// SPDX-FileCopyrightText: 2025 Demi Marie Obenour > +// 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. User documentation should primarily say that updates are not available first, and only at that point maybe link to developer documentation about how to use it with a custom image. > +=3D=3D 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 upd= ates > +into this directory. Once it exits, the host snapshots this directory a= nd > +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. This shouldn't be in user documentation either, but could be in the developer documentation. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iHUEARYKAB0WIQQGoGac7QfI+H5ZtFCZddwkt31pFQUCaSXuoAAKCRCZddwkt31p FSCSAQCXgQdCMVv7PkCJxQqAA1HS0Q2jLXFW11T7xUCkLDpi6gEA+YNKPAbT2Owh bgLuALMobLFcyF+/2mXKbGDlVUJ6tQQ= =kghI -----END PGP SIGNATURE----- --=-=-=--