Alexander John

Thoughts, notes & the occasional opinion.

Tag: TrueNAS

Manually removing TrueNAS Boot Environments

5 December 2025 / / 0 Comments

TrueNAS automatically retains copies of previous boot environments following updates and should automatically delete them if there are space constraints. However, in my experience, it rarely does and attempts to manually delete them via the GUI frequently fail with no given or logged cause.

Thankfully, and if you are brave enough, you can manually delete old and redundant boot environments via the CLI.

As always, this post is provided AS IS and you use it at your risk. If your TrueNAS box turns into a lump of glowing slag, it’s on you.

Listing the Boot Environments

Although you may view the current Boot Environments via System > Boot, the most detailed information via the shell. Open a shell via System > Shell. Enter the command zfs list -r boot-pool/ROOT to generate a list of all current boot environments.

Don’t be surprised if you get a list far larger than that shown in the TrueNAS GUI. The generated list will include subsets for each version of TrueNAS installed.

For example, running zfs list -r boot-pool/ROOT on my TrueNAS will return:

root@nyx[~]# zfs list -r boot-pool/ROOT
NAME USED AVAIL REFER MOUNTPOINT
boot-pool/ROOT 8.36G 17.8G 96K none
boot-pool/ROOT/25.04.2.3 2.78G 17.8G 176M legacy
boot-pool/ROOT/25.04.2.3/audit 164K 17.8G 5.02M /audit
boot-pool/ROOT/25.04.2.3/conf 7.15M 17.8G 7.15M /conf
boot-pool/ROOT/25.04.2.3/data 100K 17.8G 360K /data
boot-pool/ROOT/25.04.2.3/etc 7.52M 17.8G 6.55M /etc
boot-pool/ROOT/25.04.2.3/home 0B 17.8G 124K /home
boot-pool/ROOT/25.04.2.3/mnt 96K 17.8G 96K /mnt
boot-pool/ROOT/25.04.2.3/opt 96K 17.8G 96K /opt
boot-pool/ROOT/25.04.2.3/root 72K 17.8G 144K /root
boot-pool/ROOT/25.04.2.3/usr 2.56G 17.8G 2.56G /usr
boot-pool/ROOT/25.04.2.3/var 36.8M 17.8G 3.50M /var
boot-pool/ROOT/25.04.2.3/var/ca-certificates 96K 17.8G 96K /var/local/ca-certificates
boot-pool/ROOT/25.04.2.3/var/lib 27.5M 17.8G 27.2M /var/lib
boot-pool/ROOT/25.04.2.3/var/lib/incus 96K 17.8G 96K /var/lib/incus
boot-pool/ROOT/25.04.2.3/var/log 4.77M 17.8G 4.54M /var/log
boot-pool/ROOT/25.04.2.3/var/log/journal 4.46M 17.8G 4.46M /var/log/journal
boot-pool/ROOT/25.04.2.4 2.78G 17.8G 176M legacy
boot-pool/ROOT/25.04.2.4/audit 172K 17.8G 5.50M /audit
boot-pool/ROOT/25.04.2.4/conf 7.15M 17.8G 7.15M /conf
boot-pool/ROOT/25.04.2.4/data 108K 17.8G 360K /data
boot-pool/ROOT/25.04.2.4/etc 7.54M 17.8G 6.55M /etc
boot-pool/ROOT/25.04.2.4/home 0B 17.8G 124K /home
boot-pool/ROOT/25.04.2.4/mnt 96K 17.8G 96K /mnt
boot-pool/ROOT/25.04.2.4/opt 96K 17.8G 96K /opt
boot-pool/ROOT/25.04.2.4/root 8K 17.8G 152K /root
boot-pool/ROOT/25.04.2.4/usr 2.56G 17.8G 2.56G /usr
boot-pool/ROOT/25.04.2.4/var 36.0M 17.8G 3.51M /var
boot-pool/ROOT/25.04.2.4/var/ca-certificates 96K 17.8G 96K /var/local/ca-certificates
boot-pool/ROOT/25.04.2.4/var/lib 27.5M 17.8G 27.2M /var/lib
boot-pool/ROOT/25.04.2.4/var/lib/incus 96K 17.8G 96K /var/lib/incus
boot-pool/ROOT/25.04.2.4/var/log 4.04M 17.8G 5.21M /var/log
boot-pool/ROOT/25.04.2.4/var/log/journal 3.77M 17.8G 3.77M /var/log/journal
boot-pool/ROOT/25.04.2.6 2.80G 17.8G 176M legacy
boot-pool/ROOT/25.04.2.6/audit 6.20M 17.8G 5.50M /audit
boot-pool/ROOT/25.04.2.6/conf 7.15M 17.8G 7.15M /conf
boot-pool/ROOT/25.04.2.6/data 848K 17.8G 360K /data
boot-pool/ROOT/25.04.2.6/etc 7.47M 17.8G 6.55M /etc
boot-pool/ROOT/25.04.2.6/home 252K 17.8G 124K /home
boot-pool/ROOT/25.04.2.6/mnt 96K 17.8G 96K /mnt
boot-pool/ROOT/25.04.2.6/opt 96K 17.8G 96K /opt
boot-pool/ROOT/25.04.2.6/root 340K 17.8G 152K /root
boot-pool/ROOT/25.04.2.6/usr 2.56G 17.8G 2.56G /usr
boot-pool/ROOT/25.04.2.6/var 38.7M 17.8G 4.31M /var
boot-pool/ROOT/25.04.2.6/var/ca-certificates 96K 17.8G 96K /var/local/ca-certificates
boot-pool/ROOT/25.04.2.6/var/lib 27.5M 17.8G 27.2M /var/lib
boot-pool/ROOT/25.04.2.6/var/lib/incus 96K 17.8G 96K /var/lib/incus
boot-pool/ROOT/25.04.2.6/var/log 6.68M 17.8G 5.31M /var/log
boot-pool/ROOT/25.04.2.6/var/log/journal 544K 17.8G 544K /var/log/journal

In the example above, there are three distinct boot environments: 25.04.2.3, 25.04.2.4 and 25.04.2.6

Deleting a Boot Environment

!! IMPORTANT !!

  1. Make a backup of your TrueNAS configuration before proceeding. See https://www.truenas.com/docs/scale/gettingstarted/configure/setupbackupscale/#backing-up-the-system-configuration
  2. Make a note of your current boot environment name and do not delete it.
  3. I recommend retaining at least one previous known good boot environment.

From the list of boot environments (see above), enter the command zfs destroy -r boot-pool/ROOT/boot_name where boot_name is the principal boot name to delete. For example, if I wanted to delete the boot environment named 25.04.2.3 the command would be:

zfs destroy -r boot-pool/ROOT/25.04.2.3

At the time of writing, there is no confirmation shown when deleting a boot environment. To check if an environment has been deleted, use zfs list -r boot-pool/ROOT command

Final Thoughts

As a general sanity check, I always restart a TrueNAS instance once I have deleted any boot environments. If your TrueNAS box fails reboot, then you’ve probably managed to delete your current boot environment..

Renaming a TrueNAS storage pool where the name contains spaces or special characters

3 December 2025 / / 0 Comments

Renaming a TrueNAS pool is fairly simple, but it gets a little bit more complicated if the pool name contains spaces or other special characters. Pool names really should contain neither of these and arguably TrueNAS shouldn’t allow you to enter them in the first place.

If you’ve been a bit dense (i.e. like me), and you have used spaces, then you may have experienced some glitches with pool names if they contain spaces. In brief, you cannot import a pool by using its’ name if it contains spaces. You can import if you know the pool’s Id. These are steps I used to rename my pool from Pool 1 – 1TB Drives to archive.

As always, these notes are provided AS IS. and you use them at your risk. This post relates to TrueNAS version 25.04.2.4 which is the version I was using at the time of writing. You may need to check documentation if you are using a different version of TrueNAS.

Step 1: Backup & Preparation

Backup your TrueNAS configuration via the GUI – see https://www.truenas.com/docs/scale/25.04/gettingstarted/configure/setupbackupscale/

Wherever possible, disconnect any remote devices or users that are accessing the pool.

Step 2: Export / Disconnect Pool

Important: the export/disconnect of a pool will remove all references to services that use that pool (shares, containers, virtual machines etc.) If you wish to persist any of these, move them to another pool first.

In TrueNAS, got to Storage and select the pool in question. Then click on the Export/Disconnect button.

Check/tick the options Delete saved configuration from TrueNASand Confirm Export/Disconnect.

Then click on the Export/Disconnect button.

Step 3: Determine the Pool Id

Still within the Storage Dashboard, click on Import Pool

Click on the Pool drop down and you should see the pool you just exported. It’s name should be something like VerbosePoolName | SomeLongNumber. So, for me it was:

Pool 1 - 1TB Drives | 14645091355551590814

The value of SomeLongNumber is the pool Id. Either write down or copy the number – I was able to copy the text directly.

Step 4: Renaming the pool

In TrueNAS open a shell by going to System > Shell.

Import the pool by using the -f parameter to specify the pool Id. The command format is:

 zpool import -f pool_id new_pool_name

So, for me to rename my pool to archive, I used:

zpool import -f 14645091355551590814 archive

You should then get a message along the lines of:

cannot mount '/archive': failed to create mountpoint: Read-only file system
Import was successful, but unable to mount some datasets

If you see this – despite the first message – the import was successful. Check the status using zpool status new_pool_name, for example:

zpool status archive

You will get an output that should contain the text state: ONLINE. For example:

zpool status archive
pool: archive
state: ONLINE
scan: scrub repaired 920K in 01:49:24 with 0 errors on Sun Jan 7 15:05:27 2024
...

To complete the process export using the command zpool export new_pool_name

zpool export archive

Step 5: Importing back into TrueNAS

Go to Storage and then click on Import Pool

Select the pool from the drop down menu and then click on Import. Depending on the size and complexity of the pool, this may take a few minutes to complete.

Once the import has completed, the Storage Dashboard will automatically update to show the imported and renamed pool.

Final Notes

If you were running Apps or Containers on the renamed pool – for example Docker – you can import the apps by going to Apps > Configuration > Choose Pool. However, you may need to manually update any configuration paths to reflect the new pool name.

© 2025 Alexander John

Theme by Anders Norén — Up ↑