From 7c4efd6834c8fdce15d5ee7114032c7e873c303d Mon Sep 17 00:00:00 2001 From: linzi-ix Date: Tue, 30 Sep 2025 11:46:38 -0400 Subject: [PATCH 1/2] PD-2231-we-should-set-user-expectations-appropriately-for-managing-configs-in-old-boot-environments (cherry picked from commit 88791cddc3909abe413f8dfa5f8028c8c172a023) --- .../SystemSettings/ManageBootEnvironSCALE.md | 12 ++++++++++++ .../SystemSettings/SystemBootScreensSCALE.md | 4 ++++ static/includes/BootPoolRecoveryProcess.md | 2 +- 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md b/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md index 40b75e580a..5ab5df900c 100644 --- a/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md +++ b/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md @@ -89,6 +89,14 @@ Each boot environment entry contains this information: Use the icons row to take different actions for a boot environment. +### Following Best Practices + +Boot environments do not share all system information. TrueNAS carries over central database and configuration elements into a new environment during an update, but other state changes made in one environment do not appear in another. + +Changes in a new boot environment do not exist in older environments. Similarly, changes made while booted into an old environment do not propagate forward into new boot environments. + +The isolation among different boot environments means that frequent switching between environments can lead configuration divergence and missing audit information. Because of this, it is only recommended to revert a boot pool upgrade if the new version introduces a problem or to recover from a broken configuration if the system console or IPMI is unavailable. + ### Activating a Boot Environment The option to activate a boot environment only displays for boot entries not set to **Active** @@ -102,6 +110,10 @@ Click **Confirm**, and then click **Activate**. The **System Boot** screen status changes to **Reboot** and the current **Active** entry changes from **Now/Reboot** to **Now**, indicating that it is the current boot environment but it is not used on the next system restart (boot operation). +{{< hint warning >}} +Activating and booting into an older environment restores only that environment state. Any changes made there do not carry forward into newer environments. +{{< /hint >}} + ### Cloning a Boot Environment Cloning copies the selected boot environment into a new inactive boot environment that preserves the **boot-pool** state at the clone-creation time. diff --git a/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md b/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md index 2998ce4051..c3e6929b96 100644 --- a/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md +++ b/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md @@ -9,6 +9,10 @@ tags: The **Boot Environment** screen lists boot environments created by updates performed on the system. It has options for monitoring and maintaining the TrueNAS install pool and disks, and includes managing OS restore points(called boot environments) for the TrueNAS system. +{{< hint warning >}} +Boot environments do not share all configuration information. Updates create a new environment and carry forward core configuration, but other state changes do not propagate across environments. Switching between environments frequently creates configuration divergence and splits audit logs between environments. +{{< /hint >}} + {{< trueimage src="/images/SCALE/SystemSettings/BootEnvironmentListingSCALE.png" alt="System Boot Screen" id="System Boot Screen" >}} Screen options shown at the top right of the screen are: diff --git a/static/includes/BootPoolRecoveryProcess.md b/static/includes/BootPoolRecoveryProcess.md index 10af4efc6e..0293488525 100644 --- a/static/includes/BootPoolRecoveryProcess.md +++ b/static/includes/BootPoolRecoveryProcess.md @@ -20,7 +20,7 @@ When the TrueNAS boot pool fails and cannot be repaired, reinstall TrueNAS and r ### Important Considerations {{< hint type=warning >}} -This recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists. +By default, TrueNAS creates a new boot environment when you update or reinstall the system, and changes made in a previous boot environment do not automatically appear in a new environment after updates or reinstallation. Because of this, the recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists. {{< /hint >}} - **Keep external backups** - Always maintain current configuration backups stored outside the TrueNAS system From 0ba2956e2b5f03f3d1a84ebb191e788711229e96 Mon Sep 17 00:00:00 2001 From: linzi-ix Date: Tue, 7 Oct 2025 11:04:29 -0400 Subject: [PATCH 2/2] minor updates --- .../SystemSettings/ManageBootEnvironSCALE.md | 8 +++++--- .../SystemSettings/SystemBootScreensSCALE.md | 2 +- static/includes/BootPoolRecoveryProcess.md | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md b/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md index 5ab5df900c..2109ff4822 100644 --- a/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md +++ b/content/SCALETutorials/SystemSettings/ManageBootEnvironSCALE.md @@ -91,11 +91,13 @@ Use the icons row to take different actions for a boot environment. ### Following Best Practices -Boot environments do not share all system information. TrueNAS carries over central database and configuration elements into a new environment during an update, but other state changes made in one environment do not appear in another. +Boot environments do not share all system information. TrueNAS carries over central database and configuration elements into a new environment during an update, but not all state changes made in an environment appear in another. -Changes in a new boot environment do not exist in older environments. Similarly, changes made while booted into an old environment do not propagate forward into new boot environments. +Changes made in a new boot environment do not subsequently appear in older environments of earlier releases. Similarly, changes made while booted into a previous environment do not automatically appear in the upgraded boot environment. -The isolation among different boot environments means that frequent switching between environments can lead configuration divergence and missing audit information. Because of this, it is only recommended to revert a boot pool upgrade if the new version introduces a problem or to recover from a broken configuration if the system console or IPMI is unavailable. +The isolation among different boot environments means that frequent switching between environments can lead configuration divergence and missing audit information. + +We recommend only reverting to an earlier boot environment when a pool upgrade in the new version introduces a problem, or to recover from a broken configuration if the system console or IPMI is unavailable. ### Activating a Boot Environment diff --git a/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md b/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md index c3e6929b96..59ab4a8a02 100644 --- a/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md +++ b/content/SCALEUIReference/SystemSettings/SystemBootScreensSCALE.md @@ -10,7 +10,7 @@ The **Boot Environment** screen lists boot environments created by updates perfo It has options for monitoring and maintaining the TrueNAS install pool and disks, and includes managing OS restore points(called boot environments) for the TrueNAS system. {{< hint warning >}} -Boot environments do not share all configuration information. Updates create a new environment and carry forward core configuration, but other state changes do not propagate across environments. Switching between environments frequently creates configuration divergence and splits audit logs between environments. +System updates create a new boot environment and carry forward core configuration, but other state changes do not carry forward to new environments. Switching between environments frequently creates configuration divergence and splits audit logs between environments. {{< /hint >}} {{< trueimage src="/images/SCALE/SystemSettings/BootEnvironmentListingSCALE.png" alt="System Boot Screen" id="System Boot Screen" >}} diff --git a/static/includes/BootPoolRecoveryProcess.md b/static/includes/BootPoolRecoveryProcess.md index 0293488525..0eaed282be 100644 --- a/static/includes/BootPoolRecoveryProcess.md +++ b/static/includes/BootPoolRecoveryProcess.md @@ -20,7 +20,7 @@ When the TrueNAS boot pool fails and cannot be repaired, reinstall TrueNAS and r ### Important Considerations {{< hint type=warning >}} -By default, TrueNAS creates a new boot environment when you update or reinstall the system, and changes made in a previous boot environment do not automatically appear in a new environment after updates or reinstallation. Because of this, the recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists. +By default, TrueNAS creates a new boot environment when you update or reinstall the system, but if you revert to an earlier environment and make changes, those changes do not carry into the newer environment. Because of this, the recovery process depends entirely on having a current configuration backup saved externally. Boot pool failures result in a complete loss of system configuration if no backup exists. {{< /hint >}} - **Keep external backups** - Always maintain current configuration backups stored outside the TrueNAS system