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 A6CD51CA6B; Sat, 29 Nov 2025 09:51:29 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 993) id D57781CA36; Sat, 29 Nov 2025 09:51:25 +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-yx1-xb135.google.com (mail-yx1-xb135.google.com [IPv6:2607:f8b0:4864:20::b135]) by atuin.qyliss.net (Postfix) with ESMTPS id 345B41C9DB for ; Sat, 29 Nov 2025 09:51:21 +0000 (UTC) Received: by mail-yx1-xb135.google.com with SMTP id 956f58d0204a3-6420c0cf4abso2449802d50.1 for ; Sat, 29 Nov 2025 01:51:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1764409879; x=1765014679; 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=geUhBsnK8zgAPXsSrlZUKEMXBbHW8nKRVkMvzvSqIg8=; b=FuoXvMY6JdoM1UnVFbxIQ6lANXs+yZK3kLjwgRncmd+ujL0Nr8eSh1jCZJ7YIQUVsD du3kLbxUsNJexIxiIYSUkEIBeHkFT+lVbSlsaAbzq8k/9GdXtnnSdJ9BmYwemcHlx1Ah +N31H/Ebmz4GEEXw66aK+WEeHhJNXeYePP0J3KLnCpCutkhP26F6mtYeyNrw+JmNPYWN l/tGmwhxjlEIJIR9iho80pA/xjhvl7JtEsvybzijsLBfGh2D0IhqW3fdxkLG4JGifMFx lxKgT0HWrS1rpq0VPGMlVLwx3QCBixxiMCoDAiVV9zNLLgJIJeEhU5I1fBZwnmsKPdlQ ob+g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1764409879; x=1765014679; 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=geUhBsnK8zgAPXsSrlZUKEMXBbHW8nKRVkMvzvSqIg8=; b=Lm30mkQmojcQkrjwwxoqz8jb/QdLfbth7bbLB6GYdtwDXybsD9qvK0sqz/njeiszGW B0sm0+J1t2b3tIU2j7YlbQioqES1B1dyca/pi4ZAqPVyfgXGXOAaCVl4KYIfa6z6XwZv 11fyOpIBYImzu1HmmKAs6us3IyjxBjeTd4hYD9R92QGB5HxQcHyCcgkow0802kEZm/mw S26eqDIsmXTSYN3IlZWvqN5x23BUreoLFqHybTOsTx1nhl6Zikdw6CE9Ld1QFC/zU0gU lzj5lO6VdqUxsTrHvWrbokjZ5L0KrLodU/6EoMJ3WguD3cQLUWhCXhgKmefNGWQpE/jM 4XTA== X-Gm-Message-State: AOJu0YzQzq228ys5o/mvMg+VoNwwj68LlYZ99+TrCgsBbPP+6OjYl5Ob hPYy/5ajNcbdivV6nN6w+X8mBRpvs5bKp+WUDPha/V8h1GLjNiGoTpz4H1aEmg== X-Gm-Gg: ASbGncsNPydJzfYqr5CGyC0gQ8Q3snyxtP0bhORmjImDUHK+AQzviJKKw+SxFcbTr2q v6IAF00MZJPLkcOYhxbn4kRpKevznBd9AlF+ddpnIxoypoikrc9g2DcCcs17N1ZQzGH+Llh3gVy s+TSucw9mDgUj7Fr8oWJ67CBbfBBsl3Fz6ZP1f9HN3OgTAEY3RZogMrccn6sYJsTyp5LSeJXnvn 0uffsX+6gbhEhX2x+p1MV5BAH8+xT0IcSEQ63YoxZHq6rcY8kUnAL446hcEIDc+Dw92i2i54dTV KdzjjqLgkYgObXk0R7285dAd/5Zm0X+Htl+DRh0RvFZKFrsvpBrxzC1wum8BOhGcGdeYtJoD8zi GwITYGXI6YBFM9NEP+I3ury0SSzHm2I+4/VAaKQiUmzCsEs1JuoA9HXg6dJC0rQZmCw8AIvjt/g ZciyA959C4lLJ5I3N5n6LKNno6biFxYOC2YRqyzsePgJcWewtUyBE4anWM57pb27D8x85DHlmmJ eDYy5xu5Mc5XgzaWpIrdNdPEAQYqmksbsU= X-Google-Smtp-Source: AGHT+IFxaXe2XkaRe4t0CXW/IeUZrTj6MIX6BD4m3M4DZN1CLV7JI/KVFzH5/pQSyFm7hAFNFfUXtw== X-Received: by 2002:a05:690e:4007:b0:640:d207:998a with SMTP id 956f58d0204a3-64302aa85e0mr22131147d50.24.1764409878787; Sat, 29 Nov 2025 01:51:18 -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 00721157ae682-78ad0c25ae5sm24348747b3.0.2025.11.29.01.51.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 29 Nov 2025 01:51:17 -0800 (PST) From: Demi Marie Obenour Date: Sat, 29 Nov 2025 04:50:04 -0500 Subject: [PATCH v6 7/8] Documentation: Update support MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20251129-updates-v6-7-9edb87a2e509@gmail.com> References: <20251129-updates-v6-0-9edb87a2e509@gmail.com> In-Reply-To: <20251129-updates-v6-0-9edb87a2e509@gmail.com> To: Spectrum OS Development X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1764409797; l=6289; i=demiobenour@gmail.com; s=20250729; h=from:subject:message-id; bh=S3c5bF0iKYmREnmq5gTcsOIlGAAr3SoDLxo9fnamADo=; b=hltg+Yixjd/1FvoCU/zKd2auUDrpWSAOQfqVQdrWd8Fq3nW+zIudRqiGhi6oIm2TrdeGRSXJg yNBW9tpW3+LAbv3TIursnggGtkyMAXf+oci6qV7WYA7Ew8qGe7LeMeo X-Developer-Key: i=demiobenour@gmail.com; a=ed25519; pk=X57Q4/YQDj9t4SBeKaDwvXYKB6quZJVx/DE2Ly2out0= Message-ID-Hash: WKTQZUW6F2JGRTKN7C5OFQ2HWNRBWNDX X-Message-ID-Hash: WKTQZUW6F2JGRTKN7C5OFQ2HWNRBWNDX 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. --- 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