TrueNAS Documentation Archive
This content follows the TrueNAS 23.10 (Cobia) releases. Archival documentation is provided for reference only and not actively maintained. Use the Product and Version selectors above to view content specific to different TrueNAS software or major version.
Managing Boot Environments
6 minute read.
Last Modified 2023-07-24 15:49 EDTTrueNAS supports a ZFS feature known as boot environments. These are snapshot clones that TrueNAS can boot into. Only one boot environment can be used for booting.
To view the list of boot environments on the system, go to System Settings > Boot. Each boot environment entry contains this information:
- Name: the name of the boot entry as it appears in the boot menu.
- Active: indicates which entry boots by default if a boot environment is not active.
- Date Created: indicates the boot environment creation date and time.
- Space: shows boot environment size.
- Keep: indicates whether or not TrueNAS deletes this boot environment when a system update does not have enough space to proceed.
To access more options for a boot environment, click to display the list of options.
The option to activate a boot environment only displays for boot entries not set to Active
Activating an environment means the system boots into the point of time saved in that environment the next time it is started. Click the for an inactive boot environment, and then select Activate to open the Activate dialog.
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 is not used on next boot.
Cloning copies the selected boot environment into a new entry.
Click the for a boot environment, and then select Clone to open the Clone Boot Environment window.
Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
The Source field displays the boot environment you are cloning. If the displayed name is incorrect, close the window and select the correct boot environment to clone.
Click Save.
You can change the name of any boot environment on the System Settings > Boot screen.
Click the for a boot environment, and then select Rename to open the Rename Boot Environment window.
Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
Verify the boot environment in Name is the one you want to rename.
Click Save.
Deleting a boot environment removes it from the System Settings > Boot screen and from the boot menu.
Click the for a boot environment, and then select Delete to open the Delete dialog. Select Confirm and then click Delete.
You cannot delete the default or any active entries. Because you cannot delete an activated boot entry, this option does not display for activated boot environments To delete the active boot environment, first activate another entry and then delete the environment you want to remove.
Keep toggles with the Unkeep option, and they determine whether the TrueNAS updater can automatically delete this boot environment if there is not enough space to proceed with an update.
Click the for a boot environment, and then select Keep to open the Keep dialog. Select Confirm and then click Keep Flag.
The boot environment action list removes the Keep option and adds Unkeep.
This makes the boot environment subject to automatic deletion if the TrueNAS updater needs space for an update.
You can make a new boot environment to your TrueNAS.
To add a new boot environment, from the System Settings > Boot screen, click the Add button to open the Create Boot Environment window.
Enter a new name using only alphanumeric characters, and/or the allowed dashes (-), underscores (_), and periods (.) characters.
Click Save.
The Stats/Settings option displays current system statistics and provides the option to change the scrub interval, or how often the system runs a data integrity check on the operating system device.
Go to System Settings > Boot screen and click Stats/Settings. The Stats/Settings window displays statistics for the operating system device: Boot pool Condition as ONLINE or OFFLINE, Size in GiB and the space in use in Used, and Last Scrub Run with the date and time of the scrub. By default, the operating system device is scrubbed every 7 days.
To change the default scrub interval, input a different number in Scrub interval (in days) and click Update Interval.
You an attach or replace the boot environment.
From the System Settings > Boot screen, click the Boot Pool Status button to open the Boot Pool Status screen. This screen shows the current operating system device (boot pool), the path for the pool, and the read, write, or checksum errors for the device.
Click the to open the Actions options.
Click Attach, then select a device from the Member Disk dropdown.
Select Use all disk space to use the entire capacity of the new device.
Click Save.
If you want to replace the device, click the to open the Actions options. Click Replace, select the device from the Member Disk dropdown, and then click Save.
You can perform a manual data integrity check (scrub) of the operating system device at any time.
On the System Settings > Boot screen, and click Scrub Boot Pool to open the Scrub dialog.
Click Confirm and then Start Scrub.
Sometimes, rolling back to an older boot environment can be useful. For example, if an update process does not go as planned, it is easy to roll back to a previous boot environment. TrueNAS automatically creates a boot environment when the system updates.
Use the Activate option on the more_vert for the desired boot environment.
This changes the Active column to Reboot for the boot environment, and means the boot environment becomes active on the next system boot. The system configuration also changes to the state it was in when the boot environment was created.