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 023B0B9D1; Wed, 26 Nov 2025 19:42:22 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 993) id 3A1B0B8C8; Wed, 26 Nov 2025 19:42:12 +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.1 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,DMARC_PASS,FREEMAIL_FROM,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=4.0.1 Received: from mail-yw1-x112e.google.com (mail-yw1-x112e.google.com [IPv6:2607:f8b0:4864:20::112e]) by atuin.qyliss.net (Postfix) with ESMTPS id A9039B7D1 for ; Wed, 26 Nov 2025 19:41:56 +0000 (UTC) Received: by mail-yw1-x112e.google.com with SMTP id 00721157ae682-787da30c50fso1380797b3.3 for ; Wed, 26 Nov 2025 11:41:55 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1764186114; x=1764790914; darn=spectrum-os.org; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=goLGksaqdHZmEFLJ0zzwYG4wKrq8ityRQkmq7hVI86o=; b=Y9gcmUh4YQS37FjnRZgeQHtCGkGQR0daR5jwCoUJfD37ZNKxMyBVhjDei0AIzBPXa2 pzo57kzGsODQPFatV6/JFwv2QRbfT6cjmYoTFxvhajctMhm3mJbbIa8MH/TOBlfFlFSd WPCE7r/gKqc1wVCOda+oynWkWzqGltw/+wRDVULk3Hd0aE6qKhAU4kp+0x0jd/JlJk03 RAHxV5DeKRs51aCl3E1NQnNdhBn7+kOe11IicV/7zQp6afz2JB8/rCUqqhJ1m+Nf5sRh LIwMmarLt/zfpgOX8eVmfSFVSe+APDZHUhLMCKi5tBf18cSJBziXDpJAdjXDg5oyZzHR uHdQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1764186114; x=1764790914; h=cc:to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to; bh=goLGksaqdHZmEFLJ0zzwYG4wKrq8ityRQkmq7hVI86o=; b=DF540ZyJnT+K96n5Ipzffw/luuPfRnVMDICkOLNT0g+IjeuqRG6BmOnp4xrFBthfFV AACRuLMQDxoHHuOY3XxAgLZh566Z6NoxmagBbTOZ7i9Ch2KbC4ASL8+WTdrkosi+fj0c eUFOs8oTx/FdWVrd2g4hAFcvSNkoRRj4glmaRXjQ6fmL8nqAfTVtMpNFZ7bOY0Evdf4d OQxz5vhBNpJ42swXjklT7xSXNn7TI1hceNX1hkG8wMohaTjj/5fMuZihr/c23MlMLpGy GYoPUlBdCob4BdNS0pgWDGeVQUnJEQfoavJ7xprRxxzLEbe01UGdfZfOrrZl1jbCBtKH yJ8g== X-Gm-Message-State: AOJu0YyYMSYzqY5isZweK+rC+I6B5Hd9sAhJSkb8tS/qzsM3wEwwyIO9 kiqTvSwr3z30EJE3a77fHk2m6I30VAeUaJgMCcfpBh3KOPs1U+mAZuRES3+aWw== X-Gm-Gg: ASbGncuDEyqN0oVaKExYT44yX5F2tSwCGlh6bfU5omoat5cBc7JGGhH0WOC0VMyWZE+ 4EkLRCW4FA51J6pFXKrcZoWCJFq9jRVMnhCHv2T9foiJv6AUR+ErRbE9Iz8k1XdyuT9NUe0iqhS 59UZWmH6WawY3akMHc67wbz6jhscq4qrRjc2BDIlI2ntX/C7glUnZtrMCTxmI58ur7EJMWfxPKf NakI8mOqutfEvv30PWRacvXfzQdYRz9nv9+tSQhLc8TCpk4O2ghJDk9e81SppBWDe+vloxssDc2 8zysJZL7aFr9i48Xcf6R7kI9FnxCZdJp0MeNuJkeGbFXMSXgi1mEZHh6Ty7nq2frRmu4lQzKOoW jR4Vmt+PNwiMHaFPrSUt9YL21AFnI7PldeBHVs0q0MlZiUBqzGopE/4xv2xOe9Y7FTyo6+Jpygw 00f4B7aoe9wOqRsP+l+U1WuTvQiJ+YucbKCBO3WeFaPdf8g+fR5mmxvCHjCmGe6gCBafwavIb2v 7tL7xS3JssZ4UCjIqMklqv/B54g2RPqj4M= X-Google-Smtp-Source: AGHT+IEb7K4EsD/unluBOYXPbxd/XnqiKb+j6ob95sYEKyLN4HfXAfRlB9RNFdLJVLEmcK9R/CbyOA== X-Received: by 2002:a05:690c:f92:b0:787:e779:9eb3 with SMTP id 00721157ae682-78ab6f87ab5mr127899487b3.62.1764186114317; Wed, 26 Nov 2025 11:41:54 -0800 (PST) Received: from localhost.localdomain (h96-60-249-169.cncrtn.broadband.dynamic.tds.net. [96.60.249.169]) by smtp.gmail.com with UTF8SMTPSA id 956f58d0204a3-6432fb67421sm1539056d50.6.2025.11.26.11.41.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Nov 2025 11:41:53 -0800 (PST) From: Demi Marie Obenour Date: Wed, 26 Nov 2025 14:40:52 -0500 Subject: [PATCH v5 12/13] Documentation: Update support MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20251126-updates-v5-12-fd746748febd@gmail.com> References: <20251126-updates-v5-0-fd746748febd@gmail.com> In-Reply-To: <20251126-updates-v5-0-fd746748febd@gmail.com> To: Spectrum OS Development X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1764186041; l=6350; i=demiobenour@gmail.com; s=20250729; h=from:subject:message-id; bh=T7uG1qi2NwYOz3cVDirg3LnXnhsE9wNz8TyNs5Yrd/M=; b=XfPeLnRIlp6hiIo9dprgCaXNQb9kBzVsTr5/pQIsDFXzp0Fe8uvbaXtk62mdm2ED3oUEb15C3 0rXbaZkNBTEDmKlEokrcpq6pjfWhi01AABSTkXuTMXmtfEFsYbwH3kF X-Developer-Key: i=demiobenour@gmail.com; a=ed25519; pk=X57Q4/YQDj9t4SBeKaDwvXYKB6quZJVx/DE2Ly2out0= Message-ID-Hash: E5DHMNB7MKFXWKJP72KXFRVKFQNBODOB X-Message-ID-Hash: E5DHMNB7MKFXWKJP72KXFRVKFQNBODOB X-MailFrom: demiobenour@gmail.com 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 , Alyssa Ross 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: The documentation previously stated that updates were not possible without reinstalling. This is still the case by default, but it is possible for developers to enable updates for images they build. Update the documentaion to reflect this. Signed-off-by: Demi Marie Obenour --- Changes since v4: - Move the documentation from the user section to the developer section. 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. Signed-off-by: Demi Marie Obenour --- Documentation/development/build-configuration.adoc | 15 ++++++++ Documentation/development/index.adoc | 2 ++ Documentation/development/updates.adoc | 42 ++++++++++++++++++++++ Documentation/installation/index.adoc | 6 +++- 4 files changed, 64 insertions(+), 1 deletion(-) diff --git a/Documentation/development/build-configuration.adoc b/Documentation/development/build-configuration.adoc index 545aa8c05ac40a101b5ee280015cde7ec4f3a66f..49651d05890900b74cafb3d75945b3bcc5b86ce6 100644 --- a/Documentation/development/build-configuration.adoc +++ b/Documentation/development/build-configuration.adoc @@ -20,6 +20,21 @@ 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.sha256.asc`) is missing. + +Updates are signed, so the worst a compromised update +server can do is fill up your user data partition. + .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/development/index.adoc b/Documentation/development/index.adoc index 6b48418ba218354ee0493cd82188c54141f63e9e..4e504253dc16286273e1af5cae9614789b2c4a12 100644 --- a/Documentation/development/index.adoc +++ b/Documentation/development/index.adoc @@ -18,6 +18,8 @@ Spectrum is free software, currently under active development. TIP: For information on writing guidelines, see xref:../contributing/writing_documentation.adoc[Documentation Style Guide]. +If you want to update Spectrum without reinstalling, see how to +xref:updates.adoc[Enable updates]. == Mailing Lists diff --git a/Documentation/development/updates.adoc b/Documentation/development/updates.adoc new file mode 100644 index 0000000000000000000000000000000000000000..8746f97e5d9b36d4960a64544af08f57ff89ce9a --- /dev/null +++ b/Documentation/development/updates.adoc @@ -0,0 +1,42 @@ += Updating the OS +:page-parent: Development + +// SPDX-FileCopyrightText: 2025 Demi Marie Obenour +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0 + +Right now, there is no official update server or update signing key. +However, it is possible to run your own update server. See +xref:../development/build-configuration.adoc[build configuration] +for how to enable updates for your own Spectrum images. + +== Updating the system + +If you have built your image with updates enabled, you can update the +system using the `spectrum-update` command. This takes the path to a +staging directory as argument. This directory must be on a BTRFS +filesystem. It is strongly recommended to not use this directory +for any other purpose. However, it's safe to rename the directory +and use `spectrum-update` with the new path afterwards. + +If there is a problem with the update, it's safe to try again. +If that still doesn't work, you can delete the directory and +try again with an empty one. This will cause `spectrum-update` +to download the latest version even if it is already installed, but +is otherwise harmless. + +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. It is safe to resume +an interrupted update. + +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. + +See the documentation of +https://www.freedesktop.org/software/systemd/man/systemd-sysupdate.html[systemd-sysupdate]. +for some of the details. diff --git a/Documentation/installation/index.adoc b/Documentation/installation/index.adoc index d67c88dda062066c19c3b21e699f074cc18a6dbc..d1df2edc9b0ca902824ff729eec139270fb40777 100644 --- a/Documentation/installation/index.adoc +++ b/Documentation/installation/index.adoc @@ -18,6 +18,10 @@ development. == Uninstalling and Updating -Currently, there is no implementation for a software update. +Software updates are a work in progress and are not currently available. + +If you built Spectrum yourself, see +xref:../development/build-configuration.adoc[Build configuration] for how +to enable updates for it. You can replace Spectrum by installing another OS. -- 2.52.0