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 13ED2B5E1; Wed, 26 Nov 2025 19:37:32 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 993) id 288E4B4CA; Wed, 26 Nov 2025 19:37: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.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-xb136.google.com (mail-yx1-xb136.google.com [IPv6:2607:f8b0:4864:20::b136]) by atuin.qyliss.net (Postfix) with ESMTPS id B7DE4B42B for ; Wed, 26 Nov 2025 19:37:06 +0000 (UTC) Received: by mail-yx1-xb136.google.com with SMTP id 956f58d0204a3-642fcb38f35so103127d50.1 for ; Wed, 26 Nov 2025 11:37:05 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1764185824; x=1764790624; 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=I/59dXrLtp4V9Z7k/Gf3HH8IENz3S4AY4+Pi5MlbD4J1kUN9NNVO4eP8tMQTKgPZd7 yvlrBcbT7/SkrVqulBM6NSExoLpVkcPcWe7jkl055H/azQxmgVma4WzpWUxPmQiDwOU9 8GDRngwXafcz7lU6fL4puzTlYfxokaUCYLXeqWbtckjW1xd/w0BFZq38dq9zbMX/r/eJ Z4C7wQY1wzPcX+VHuLvm50PJs5I8Ih7abFX4O4oYAMLrxvwB6NjXj1m4V+t03eY8i09q vNYfX08RYIt1Jn43p+8Yh4W86U7eCtISbU5TLiGmjlvVGY5/TsjM9RVuHbp6JGrKrz+M n8Ww== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1764185824; x=1764790624; 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=A7bPQ0h1OACn/1//RwAcF1OpgwDxU97QBO2PCNvDwS1xicAViqqxuOliSwRZJLSby2 FBsTUB7M2lOf8Sa2MkOo/7aY5aogSgRJZKzO3popRTkYO531/CJsMnAvQ+7by6WLR9ae EZH2q2aFb3nCgDK044vx1fZ8auTSucGZXV6JS6Et7urjdtuydvTHqcj1Kf/I9QoDAjkq 4kkZuBNUvxQdGa+ufeyyRXlQCMIwgMk6AnLLSKfU8vGwkp+1rQr758vlIWHA9WZTRZW/ yiR7e4+DtOYOEoGCymKorVEufJOX8UjEQ/kP2jbivQFlkpSidqZ6e855P1BibNxc9bxD zOmg== X-Gm-Message-State: AOJu0Yz/Z+0tG+Nrk+3cTkEcfE8Mkig6v8XBWATbZUw/w4qLygc/tp00 M7XhTs5Kv6qieLe3CZLmZMZbbMe3re5RYfFZDBc8ZTPKmagNl9rabp2lnGHLsA== X-Gm-Gg: ASbGnctjtuvMmhHC8lExHIimehD6/LOPuf/Dnc6mbL7BaYfMU5XAaOpK8XIZT8reLWe 60Fi9BELmHxkH5Sgiqm1RfQtFJy3XCm51VghldyyMsALsnMuNcuAQbecKUvFTK8AQ8EeBbl+P8k YcteFx2QTcsS/50zCEov47K+2jgCtYF9OvRn+OmJO0umKf0+LhgXChqK3kor+jolp0UuprYG3VZ CJwJ+3Bx7OVu/qG0GYMiZL6xine9S5awkzcjAdhzZbLTaoKX3UUWxMcdWYwt1TKZsoJc8gXPoIu p7p0kIyMxCq7r3sdQ5hs+zwSzYwq3YwO44mcBeyr7pZnX676NBb0SrhtFgpx/VBUgk/VkBJPme5 QZV/uG0RIS/9je2PqQKDIe3dd2oL9qwqF+H6hL5mW1RK/fNqgruTXS0sgPjT/2HDZ2BT5mxq/Og yIVsG7PJbqGFkSf/mxGC766eZaaHKz595ADpPCIBps99Q8UxZqN8jtnwWya8vnVa8qnW74SOA6J T11DYTzRQYhDOG/PCtY2DzioAy2ib2rIUY= X-Google-Smtp-Source: AGHT+IHpUO7ZHglO+hja1dzfAf+n7vVqksE3Kh8xg/zqDMaWg1YhR9tTGIE4uczR8bbJlTRGMJxALA== X-Received: by 2002:a05:690e:d05:b0:643:2169:d6c4 with SMTP id 956f58d0204a3-6432169d83dmr6782203d50.66.1764185824338; Wed, 26 Nov 2025 11:37:04 -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-78a7987e889sm70062217b3.7.2025.11.26.11.37.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 26 Nov 2025 11:37:03 -0800 (PST) From: Demi Marie Obenour Date: Wed, 26 Nov 2025 14:34:10 -0500 Subject: [PATCH v4 12/13] Documentation: Update support MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20251126-updates-v4-12-40c438d2dcaf@gmail.com> References: <20251126-updates-v4-0-40c438d2dcaf@gmail.com> In-Reply-To: <20251126-updates-v4-0-40c438d2dcaf@gmail.com> To: Spectrum OS Development X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1764185638; l=6350; i=demiobenour@gmail.com; s=20250729; h=from:subject:message-id; bh=T7uG1qi2NwYOz3cVDirg3LnXnhsE9wNz8TyNs5Yrd/M=; b=bBZiXM7eJzcbC4QAAIkumvID0VYZi1ek7knEkwCUupUc+TvC2FjLk1Uw44ZgA86YInO9Nv7tx hJdyIWH4PfHChiPhnbWHedMywAua3/bFmgp6GpISbf/0+Hau1jy8ANa X-Developer-Key: i=demiobenour@gmail.com; a=ed25519; pk=X57Q4/YQDj9t4SBeKaDwvXYKB6quZJVx/DE2Ly2out0= Message-ID-Hash: 4GY2UNUYBAQLLLGVD4JPMFXLGKKQEAPI X-Message-ID-Hash: 4GY2UNUYBAQLLLGVD4JPMFXLGKKQEAPI 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