From 996cf6ac56692656f0f0484b5a50ee7df135c23d Mon Sep 17 00:00:00 2001
From: nikstur <nikstur@outlook.com>
Date: Thu, 26 Oct 2023 18:15:50 +0200
Subject: [PATCH] nixos/docs: add non-switchable-systems section

---
 .../non-switchable-systems.section.md         | 21 +++++++++++++++++++
 ...-happens-during-a-system-switch.chapter.md |  1 +
 2 files changed, 22 insertions(+)
 create mode 100644 nixos/doc/manual/development/non-switchable-systems.section.md

diff --git a/nixos/doc/manual/development/non-switchable-systems.section.md b/nixos/doc/manual/development/non-switchable-systems.section.md
new file mode 100644
index 000000000000..87bb46c78909
--- /dev/null
+++ b/nixos/doc/manual/development/non-switchable-systems.section.md
@@ -0,0 +1,21 @@
+# Non Switchable Systems {#sec-non-switchable-system}
+
+In certain systems, most notably image based appliances, updates are handled
+outside the system. This means that you do not need to rebuild your
+configuration on the system itself anymore.
+
+If you want to build such a system, you can use the `image-based-appliance`
+profile:
+
+```nix
+{ modulesPath, ... }: {
+  imports = [ "${modulesPath}/profiles/image-based-appliance.nix" ]
+}
+```
+
+The most notable deviation of this profile from a standard NixOS configuration
+is that after building it, you cannot switch *to* the configuration anymore.
+The profile sets `config.system.switch.enable = false;`, which excludes
+`switch-to-configuration`, the central script called by `nixos-rebuild`, from
+your system. Removing this script makes the image lighter and slightly more
+secure.
diff --git a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md
index 5d6d67f1aa92..7aa84bbdb95b 100644
--- a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md
+++ b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md
@@ -51,4 +51,5 @@ explained in the next sections.
 ```{=include=} sections
 unit-handling.section.md
 activation-script.section.md
+non-switchable-systems.section.md
 ```