From fd2edb9c07bbc2248a9bebe11a27ed886eee3717 Mon Sep 17 00:00:00 2001 From: Mic Johnson Date: Fri, 17 Oct 2025 13:49:41 -0400 Subject: [PATCH 1/6] PD-2172 25.04 Manual Backport of Instance VM zvol Migration This PR manually backports the VM changes made in the 25.10 branch into the 25.04 branch. It updates the Release Notes with information about migrating Instance VM zvols and adds the procedure to the /virtuatlMachines/_index.md tutorial. --- content/GettingStarted/SCALEReleaseNotes.md | 4 + .../SCALETutorials/VirtualMachines/_index.md | 167 ++++++++++++++++++ static/includes/25.04Virtualization.md | 13 +- 3 files changed, 177 insertions(+), 7 deletions(-) diff --git a/content/GettingStarted/SCALEReleaseNotes.md b/content/GettingStarted/SCALEReleaseNotes.md index b758c0c4a9..6f76a59edc 100644 --- a/content/GettingStarted/SCALEReleaseNotes.md +++ b/content/GettingStarted/SCALEReleaseNotes.md @@ -173,6 +173,8 @@ TrueNAS 25.04.2 is not recommended for TrueNAS Enterprise customers with High Av Virtual machines automatically migrate from TrueNAS 24.10 to 25.04.2. No manual migration of virtual machines is required. +* Virtual machines created in 25.04 (pre-25.04.2) and displayed on the **Containers** screen do not automatically start on system boot to prevent conflicts with VMs on the **Virtual Machines** screen that might use the same zvols ([NAS-136946](https://ixsystems.atlassian.net/browse/NAS-136946)). +* Virtual machines created in 25.04.0 or 25.04.1 using the **Instances** (now **Containers**) screen can be migrated to conventional VMs in 25.10 and later using the process described in the [**Migrating Instance VMs**]({{< ref "/scaletutorials/virtualMachines/_index" >}}) section of the Virtual Machines tutorial. * Adds the ability to enter optional custom endpoints in cloud sync credentials that support **Global** and **Select** tiers in Storj ([NAS-133835](https://ixsystems.atlassian.net/browse/NAS-133835)). * Adds a Secure Boot checkbox to the **Add Virtual Machine** wizard and **Edit Virtual Machine** form ([NAS-136466](https://ixsystems.atlassian.net/browse/NAS-136466)). * Passes the Storj/iX cloud sync credential access key and secret access key in the UI when creating the credential ([NAS-135837](https://ixsystems.atlassian.net/browse/NAS-135837)). @@ -226,6 +228,8 @@ TrueNAS 25.04.2 is not recommended for TrueNAS Enterprise customers with High Av The TrueNAS team is pleased to release TrueNAS 25.04.1! This is a maintenance release and includes refinements and fixes for issues discovered after 24.04.0. + + ### 25.04.1 Notable Changes {{< enterprise >}} diff --git a/content/SCALETutorials/VirtualMachines/_index.md b/content/SCALETutorials/VirtualMachines/_index.md index 2872d4df74..b980685c40 100644 --- a/content/SCALETutorials/VirtualMachines/_index.md +++ b/content/SCALETutorials/VirtualMachines/_index.md @@ -397,6 +397,173 @@ If your system has more than one physical interface, you can assign your VMs to To create a bridge interface for the VM to use if you have only one physical interface, stop all existing apps, VMs, and services using the current interface, edit the interface and VMs, create the bridge, and add the bridge to the VM device. See [Accessing NAS from VM]({{< ref "ContainerNASBridge" >}}) for more information. +## Migrating Instances VMs + +The storage volumes (zvols) for virtual machines created using the **Instances** option in TrueNAS 25.04.0 or 25.04.1 can migrate to new VMs created in using the **Virtual Machines** screen options in 25.10 and later. +The process involves: + +* Identifying the hidden storage volumes (zvols) associated with the Instance VMs. +* Renaming (and moving) the zvols to a new dataset where they can be seen and used by a new VM. +* Verifying the `volmode` for the zvol is correctly configured. +* Creating a new VM and selecting the migrated zvol as the storage volume. + +### Before You Begin + +Before beginning the process, and while in 25.04.0 or the latest maintenance release: + +1. Identify the zvol names associated with the Instance VM. +2. Take a snapshot or back up the zvol for the Instance VM. + Using ZFS commands to rename and move an existing zvol can damage data stored in the volume. Having a backup is a critical step to restoring data if something goes wrong in the process. +3. Verify the VM is operational and has Internet access, then stop the VM before you upgrade to the 25.10 or a later release. +4. Identify the dataset where you want to move the volume in 25.10 or later. + We do not recommend renaming or moving the volume more than once, as it increases the risk of possible data corruption or loss. + +You do not need to log in as the root user if the logged-in admin user has permission to use `sudo` commands. +If not, go to **Credentials > Users**, edit the user to allow `sudo` commands, or verify the root user has an active password to switch to this user when entering commands in the **Shell** screen. + +### Migrating a Zvol for an Instance VM + +This procedure applies to the zvol for an Instance VM that has data you want to preserve, and access from a new VM in 25.10 or later. + +While in a 25.04.01 or a later maintenance release: + +1. Go to **Instances**, click on **Configuration**, and then **Manage Volumes** to open the **Volumes** window. + The **Volumes** window lists all Instance VMs and the storage volumes associated with each. + + {{< hint type="tip" >}} + Take a screenshot of the information to refer to later when entering commands in the **Shell** screen. + Optionally, you can highlight all the listed information and copy/paste it into a text file, but this is not necessary. + {{< /hint >}} + +2. While on the **Instances** screen, verify the VM is operational and has Internet access, and then stop the VM. + Repeat for each zvol for an Instance VM that you plan to migrate into a new VM in 25.10 or later. + +3. Go to **Datasets**, locate the zvol for the Instance VM, and take a snapshot of the volume as a backup. + Repeat for each VM zvol you want to migrate. + +4. Go to **System > Update**, and update to the next publicly available maintenance or major version release. + Follow the release migration paths outlined in the version release notes or the [Software Releases](https://www.truenas.com/docs/softwarereleases/) article. + + After updating from a 25.04.x release, VMs created using **Instances** screens show on the **Containers** screen, and are stopped. + Some VMs experience issues various issues like network connectivity, or are stopped and do not start. + Refer to the troubleshooting tips below for more information. 25.10 releases correct some issues encountered in 25.04.2.4 VMs that are migrated. + + {{< expand "Troubleshooting VM Issues" "v" >}} + After upgrading from 24.10 to 25.04, VMs are visible and running, but are expected to have issues because 25.04 release does not fully support these older VMs. + + VMs with a Windows OS installed could require converting to VirtIO-SCSI disks to get reconnected to the Internet. + To restore connectivity, try clean-mounting the system from the mounted drive from within the VM, and then on the TrueNAS system (host). + Follow this by removing driver syntax added to raw qem files. + + If a new VM is created in 25.04.2.1 and it fails to run, stop all containers. + In the VM configuration, delete the current NIC, then select the bridge before selecting the NIC again to restore functionality. + + VMs created using the Instances feature initially show on the **Virtual Machine** screen as running when they are not running, but this state corrects on its own. + + If a VM with Windows OS is created in 25.04.0 using the **Virtual Machine** screens (not **Instances** in 25.04.1) the VM should run. + If this VM cannot find the NIC, delete the NIC in the configuration from the **Devices** screen for that VM, and then reconfigure it to restore functionality. + {{< /expand >}} + +After updating to 25.10 or later: + +5. Go to **Containers** to see which VMs are listed, then click **Configuration**, and then **Manage Volumes** to open the **Volumes** window. + Take a screenshot of the volumes listed, or copy/paste the volumes and VM information into a text file to use later in this procedure. + +6. Go to **Virtual Machines** to see which are listed. + +7. Go to **System > Shell**. Exit to the Linux prompt for the system. + + Note: This is where the logged in admin user needs `sudo` permissions, or where the root user must have a password configured to enter the following commands to find, rename/move, and verify each Instance zvol is properly configured. + + Enter the following commands at the Linux system prompt: + + a. Locate the hidden zvols for the Instance VMs, by entering: + + sudo zfs list -t volume -r -d 10 poolname + + Where: + * `-d 10` shows datasets up to 10 levels deep + * *poolname* is the name of the pool associated with the Instance VMs. + If you have multiple pools associated with the Instance VMs, repeat this command with the name of that pool to show hidden zvols in that pool. + + The **.ix-virt** directory contains the zvols use in Instance VMs. Ignore the entries with the **.block** extension. + The output includes other zvols in the pool if your system has non-instance VMs configured in the pool name entered in the command. + + {{< expand "Example Command Output" "v" >}} + + ``` + re-minir-102% sudo zfs list -t volume -r tank + NAME USED AVAIL REFER MOUNTPOINT + tank/.ix-virt/custom/default_vm2410linux-8cppg_vm2410linuxclone1 0B 1.66T 56K - + tank/.ix-virt/custom/default_vm2410win-mvqznj_vm2410winclone1 0B 1.66T 56K - + tank/.ix-virt/custom/default_vm2410win-mvqznj_vm2410winclone2 0B 1.66T 56K - + tank/.ix-virt/virtual-machines/vm25041linux.block 56K 1.66T 56K - + tank/.ix-virt/virtual-machines/vm25041linuxclone.block 56K 1.66T 56K - + tank/.ix-virt/virtual-machines/vm25041win.block 56K 1.66T 56K - + tank/.ix-virt/virtual-machines/vm25041winclone.block 56K 1.66T 56K - + tank/default_vm2410linux-8cppg_vm2410linuxclone2 0B 1.66T 56K - + tank/vms/vm2410linux-8cppg 40.6G 1.70T 56K - + tank/vms/vm2410linux-8cppg_vm2410linuxclone2 0B 1.66T 56K - + tank/vms/vm2410win-mvqznj 40.6G 1.70T 56K - + tank/vms/vm2410win-mvqznj_vm2410winclone2 0B 1.66T 56K - + ``` + + The zvols in the command output above with `tank/.ix-virt/custom` in the path are the zvols to migrate if these are associated with the VM you want to migrate to new VMs in the 25.10.0 or later release. + {{< /expand >}} + + b. Rename (and move) each volume in the **.ix-virt** directory to a new location where you can select it when configuration a new VM. + Repeat for each volume you want to migrate to a new VM. Do not rename or move the .block volumes. + Enter the following command: + + sudo zfs rename tank/.ix-virt/custom/default_vm2410linux-icppg_vm2410linuxclone1 tank/vms/default_vm2410linux-icppg_vm2410linuxclone1 + + Where: + * *tank* is the pool name in the example. + * *default_vm2410linux-icppg_vm2410linuxclone1* is the name of a hidden zvol in the example, and the name given to the migrated zvol. + We do not recommend renaming the migrated zvol to minimize potential issues with the migration process. + * *vms* is the dataset in the example as the location to store the migrated zvols for VMs. Change this to the location on your system. + + This renames and moves it to the specified location, and returns to the system Linux prompt. + To verify the zvol moved, enter the sudo zfs list -t volume -r tank command again. The output should show the zvol in the new location. + + c. Verify the `volmode`. Enter the following command for each zvol you rename. + + sudo zfs get volmode tank/vms/efault_vm2410linux-icppg_vm2410linuxclone1 + + Where: + * *tank* is the pool name. + * *vms* is the dataset where the zvol is stored. + * *default_vm2410linux-icppg_vm2410linuxclone1* is the name of the zvol + + This returns the `volmode` for the volume. It should be set to `dev`. If not, enter the following command to set it to `dev`: + + sudo zfs set volmode=dev tank/vms/efault_vm2410linux-icppg_vm2410linuxclone1 + + After completing the commands listed above for each zvol you want to migrate. Go to **Datasets** and verify all volumes you migrated show on the screen. + +8. Create the new VM using the migrated zvol. Repeat these steps for each zvol you migrated. + Go to **Virtual Machines**, click on **Add** to open the **Create Virtual Machine** wizard. + + a. Complete the first screen by entering a name for the new VM, select the operating system used by the Instances VM, enter a brief description, then if using the **Bind** setting, enter a password. Click **Next**. + + b. Configure the CPU and Memory settings, and then click **Next**. + + c. On the **Disks** wizard screen, select **Use existing disk image**, click in **Select Existing Zvol** and select the volume moved from the Instances VM. + If you move multiple zvols, refer to the screenshot or text file with the VM/zvol list to select the correct zvol for this new VM. + + d. Click **Next** until you get to the confirmation screen, then click **Create** to add the VM. + + After adding the new VM, click on it to expand it, and click **Devices**. + Click **Edit** for the **Disk** device, and enter **1000** in the **Device Order** field. + Click **Save**. + This sets the VM to boot from the disk, which prevents the volume from being overwritten by booting from the CD-ROM device with an OS image file on it (if you added one in the creation wizard). + +9. Return to the **Virtual Machines** screen, expand the VM, then click **Start** to verify it opens as expected and has Internet access. +Footer +© 2025 GitHub, Inc. +Footer navigation +Terms +
## Virtual Machines Contents diff --git a/static/includes/25.04Virtualization.md b/static/includes/25.04Virtualization.md index 06a3e037e1..68bf42c5f0 100644 --- a/static/includes/25.04Virtualization.md +++ b/static/includes/25.04Virtualization.md @@ -2,10 +2,14 @@ {{< hint type=important icon=gdoc_notification title="Virtual Machines and Containers in TrueNAS 25.04" >}} -TrueNAS 25.04 introduces support for [**Containers**]({{< ref "/scaletutorials/containers/" >}}) (Linux system containers), enabling lightweight isolation similar to jails in TrueNAS CORE. +rueNAS 25.04.0 introduced support for **Containers** (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in TrueNAS CORE. TrueNAS 25.04.2 reintroduces "classic virtualization" with the [**Virtual Machines**]({{< ref"/scaletutorials/virtualmachines/" >}}) feature. +In TrueNAS 25.04.2 (and later) virtual machines are created and appear on the **Virtual Machines** screen. +Legacy VMs created in 25.04.0 or 25.04.1 using the Instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the **Containers** screen. +Legacy VMs on the **Containers** screen do not autostart in 25.10 or later. + Virtual machines in 25.04.2 (or later) are created and appear on the **Virtual Machines** screen. VMs created in 25.04.0 or 25.04.1 using the **Instances** feature continue to function and appear on the **Containers** screen. @@ -21,12 +25,7 @@ VMs created in 24.10 or earlier are located depending on migration path: - VMs on 24.10 systems that upgrade directly to 25.04.2 (skipping 25.04.0/25.04.1) automatically migrate to the **Virtual Machines** screen without manual action. {{< /expand >}} -You do not need to migrate existing VMs from the **Containers** screen to the **Virtual Machines** screen at this time. -We are developing additional guidance for these legacy VMs for the TrueNAS 25.10 release. - -We are actively updating Tutorials and UI Reference articles to reflect these changes. -Please use the Docs Hub **Feedback** button (located to the right of any article) to report documentation issues or -request improvements to the **Containers** or **Virtual Machines** documentation. +You do not need to migrate existing VMs from the **Containers** screen to the **Virtual Machines** screen at this time, but 25.10 and future releases allow migrating the storage zvols to new VMs created in 25.10 and later. For more information, see **[Migrating Instance VMs]({{< relref "/SCALE/SCALETutorials/VirtualMachines/_index.md" >}})**. {{< /hint >}} From f0f40de57ed366bf1f83c72dcceca8e4b2bc9c0c Mon Sep 17 00:00:00 2001 From: Mic Johnson Date: Fri, 17 Oct 2025 13:54:46 -0400 Subject: [PATCH 2/6] PD-2172 Fix broken links --- content/GettingStarted/SCALEReleaseNotes.md | 2 +- static/includes/25.04Virtualization.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/GettingStarted/SCALEReleaseNotes.md b/content/GettingStarted/SCALEReleaseNotes.md index 6f76a59edc..d6ecc30d18 100644 --- a/content/GettingStarted/SCALEReleaseNotes.md +++ b/content/GettingStarted/SCALEReleaseNotes.md @@ -174,7 +174,7 @@ TrueNAS 25.04.2 is not recommended for TrueNAS Enterprise customers with High Av Virtual machines automatically migrate from TrueNAS 24.10 to 25.04.2. No manual migration of virtual machines is required. * Virtual machines created in 25.04 (pre-25.04.2) and displayed on the **Containers** screen do not automatically start on system boot to prevent conflicts with VMs on the **Virtual Machines** screen that might use the same zvols ([NAS-136946](https://ixsystems.atlassian.net/browse/NAS-136946)). -* Virtual machines created in 25.04.0 or 25.04.1 using the **Instances** (now **Containers**) screen can be migrated to conventional VMs in 25.10 and later using the process described in the [**Migrating Instance VMs**]({{< ref "/scaletutorials/virtualMachines/_index" >}}) section of the Virtual Machines tutorial. +* Virtual machines created in 25.04.0 or 25.04.1 using the **Instances** (now **Containers**) screen can be migrated to conventional VMs in 25.10 and later using the process described in the [**Migrating Instance VMs**]({{< ref "/scaletutorials/virtualmachines/" >}}) section of the Virtual Machines tutorial. * Adds the ability to enter optional custom endpoints in cloud sync credentials that support **Global** and **Select** tiers in Storj ([NAS-133835](https://ixsystems.atlassian.net/browse/NAS-133835)). * Adds a Secure Boot checkbox to the **Add Virtual Machine** wizard and **Edit Virtual Machine** form ([NAS-136466](https://ixsystems.atlassian.net/browse/NAS-136466)). * Passes the Storj/iX cloud sync credential access key and secret access key in the UI when creating the credential ([NAS-135837](https://ixsystems.atlassian.net/browse/NAS-135837)). diff --git a/static/includes/25.04Virtualization.md b/static/includes/25.04Virtualization.md index 68bf42c5f0..423bce85f9 100644 --- a/static/includes/25.04Virtualization.md +++ b/static/includes/25.04Virtualization.md @@ -25,7 +25,7 @@ VMs created in 24.10 or earlier are located depending on migration path: - VMs on 24.10 systems that upgrade directly to 25.04.2 (skipping 25.04.0/25.04.1) automatically migrate to the **Virtual Machines** screen without manual action. {{< /expand >}} -You do not need to migrate existing VMs from the **Containers** screen to the **Virtual Machines** screen at this time, but 25.10 and future releases allow migrating the storage zvols to new VMs created in 25.10 and later. For more information, see **[Migrating Instance VMs]({{< relref "/SCALE/SCALETutorials/VirtualMachines/_index.md" >}})**. +You do not need to migrate existing VMs from the **Containers** screen to the **Virtual Machines** screen at this time, but 25.10 and future releases allow migrating the storage zvols to new VMs created in 25.10 and later. For more information, see **[Migrating Instance VMs]({{< ref "/scaletutorials/virtualmachines/" >}})**. {{< /hint >}} From 2bcd942fdf24281a0911ca8eec0c8dda6c4eaccb Mon Sep 17 00:00:00 2001 From: Mic Johnson Date: Tue, 28 Oct 2025 11:33:35 -0400 Subject: [PATCH 3/6] PD-2172 Manual Backport of Changes This commit makes changes to the 25.04 branch based on merged changes in 25.10 but modified for the 25.04 branch. --- content/GettingStarted/SCALEReleaseNotes.md | 7 ++- content/SCALETutorials/Containers/_index.md | 2 + .../Network/ContainerNASBridge.md | 1 - .../SCALETutorials/VirtualMachines/_index.md | 47 ++++++++----------- static/includes/25.04Virtualization.md | 9 ++-- words-to-ignore.txt | 3 ++ 6 files changed, 32 insertions(+), 37 deletions(-) diff --git a/content/GettingStarted/SCALEReleaseNotes.md b/content/GettingStarted/SCALEReleaseNotes.md index d6ecc30d18..33bacbea08 100644 --- a/content/GettingStarted/SCALEReleaseNotes.md +++ b/content/GettingStarted/SCALEReleaseNotes.md @@ -173,10 +173,11 @@ TrueNAS 25.04.2 is not recommended for TrueNAS Enterprise customers with High Av Virtual machines automatically migrate from TrueNAS 24.10 to 25.04.2. No manual migration of virtual machines is required. + * Virtual machines created in 25.04 (pre-25.04.2) and displayed on the **Containers** screen do not automatically start on system boot to prevent conflicts with VMs on the **Virtual Machines** screen that might use the same zvols ([NAS-136946](https://ixsystems.atlassian.net/browse/NAS-136946)). -* Virtual machines created in 25.04.0 or 25.04.1 using the **Instances** (now **Containers**) screen can be migrated to conventional VMs in 25.10 and later using the process described in the [**Migrating Instance VMs**]({{< ref "/scaletutorials/virtualmachines/" >}}) section of the Virtual Machines tutorial. -* Adds the ability to enter optional custom endpoints in cloud sync credentials that support **Global** and **Select** tiers in Storj ([NAS-133835](https://ixsystems.atlassian.net/browse/NAS-133835)). +* Virtual machines created in 25.04.0 or 25.04.1 using the **Instances** (now **Containers**) screen can be migrated to conventional VMs in 25.10 and later using the process described in the [**Migrating Containers VMs**]({{< ref "/scaletutorials/virtualmachines/#migrating-containers-vms" >}}) tutorial. * Adds a Secure Boot checkbox to the **Add Virtual Machine** wizard and **Edit Virtual Machine** form ([NAS-136466](https://ixsystems.atlassian.net/browse/NAS-136466)). +* Adds the ability to enter optional custom endpoints in cloud sync credentials that support **Global** and **Select** tiers in Storj ([NAS-133835](https://ixsystems.atlassian.net/browse/NAS-133835)). * Passes the Storj/iX cloud sync credential access key and secret access key in the UI when creating the credential ([NAS-135837](https://ixsystems.atlassian.net/browse/NAS-135837)). * Removes the **Mega** cloud service provider for rclone. Mega Technical Support states they no longer support rclone due to bugs in their implementation and requirements to properly troubleshoot issues ([NAS-135844](https://ixsystems.atlassian.net/browse/NAS-135844)). @@ -228,8 +229,6 @@ TrueNAS 25.04.2 is not recommended for TrueNAS Enterprise customers with High Av The TrueNAS team is pleased to release TrueNAS 25.04.1! This is a maintenance release and includes refinements and fixes for issues discovered after 24.04.0. - - ### 25.04.1 Notable Changes {{< enterprise >}} diff --git a/content/SCALETutorials/Containers/_index.md b/content/SCALETutorials/Containers/_index.md index 34a7816771..6cd30e538d 100644 --- a/content/SCALETutorials/Containers/_index.md +++ b/content/SCALETutorials/Containers/_index.md @@ -18,6 +18,8 @@ keywords: {{< include file="/static/includes/25.04Virtualization.md" >}} +{{< include file="/static/includes/InstanceWarning.md" >}} + **Containers** allow users to configure linux containers in TrueNAS. *Linux containers*, powered by LXC, offer a lightweight, isolated environment that shares the host system kernel while maintaining its own file system, processes, and network settings. diff --git a/content/SCALETutorials/Network/ContainerNASBridge.md b/content/SCALETutorials/Network/ContainerNASBridge.md index cd9aa7c502..5936891c18 100644 --- a/content/SCALETutorials/Network/ContainerNASBridge.md +++ b/content/SCALETutorials/Network/ContainerNASBridge.md @@ -13,7 +13,6 @@ keywords: - storage container virtualization --- -{{< include file="/static/includes/25.04Virtualization.md" >}} If you want to access your TrueNAS directories from within a virtual machine or container hosted on the system, you have multiple options: diff --git a/content/SCALETutorials/VirtualMachines/_index.md b/content/SCALETutorials/VirtualMachines/_index.md index b980685c40..2083d66c68 100644 --- a/content/SCALETutorials/VirtualMachines/_index.md +++ b/content/SCALETutorials/VirtualMachines/_index.md @@ -262,7 +262,7 @@ Modify settings as needed to suit your use case. a. Enter your localization settings for **Language**, **Location**, and **Keymap**. b. Debian automatically configures networking and assigns an IP address with DHCP. - * If the network configuration fails, click **Continue** and do not configure the network yet. + If the network configuration fails, click **Continue** and do not configure the network yet. c. Enter a name in **Hostname**. @@ -313,10 +313,10 @@ Modify settings as needed to suit your use case. b. Remove the CD-ROM device containing the install media or edit the device order to boot from the Disk device. - * To remove the CD-ROM from the devices, click the   and select **Delete**. + To remove the CD-ROM from the devices, click the   and select **Delete**. Click **Delete Device**. - * To edit the device boot order, click the   and select **Edit**. + To edit the device boot order, click the   and select **Edit**. Change the CD-ROM **Device Order** to a value greater than that of the existing Disk device, such as *1005*. Click **Save**. @@ -407,9 +407,7 @@ The process involves: * Verifying the `volmode` for the zvol is correctly configured. * Creating a new VM and selecting the migrated zvol as the storage volume. -### Before You Begin - -Before beginning the process, and while in 25.04.0 or the latest maintenance release: +Before beginning the process: 1. Identify the zvol names associated with the Instance VM. 2. Take a snapshot or back up the zvol for the Instance VM. @@ -428,18 +426,19 @@ This procedure applies to the zvol for an Instance VM that has data you want to While in a 25.04.01 or a later maintenance release: 1. Go to **Instances**, click on **Configuration**, and then **Manage Volumes** to open the **Volumes** window. - The **Volumes** window lists all Instance VMs and the storage volumes associated with each. + The **Volumes** window lists all Instance VMs and the assoicated storage volumes (zvols). - {{< hint type="tip" >}} - Take a screenshot of the information to refer to later when entering commands in the **Shell** screen. + Record the volume name or take a screenshot of the information to refer to later when entering commands in the **Shell** screen. + Zvol names are similar to the VM name but not identical. Optionally, you can highlight all the listed information and copy/paste it into a text file, but this is not necessary. - {{< /hint >}} -2. While on the **Instances** screen, verify the VM is operational and has Internet access, and then stop the VM. - Repeat for each zvol for an Instance VM that you plan to migrate into a new VM in 25.10 or later. +2. While on the **Instances** screen, verify the VM is operational and the network is operating as expected. + One way to verify external network access is to check Internet access. Stop the VM before upgrading. + Repeat for each zvol that you plan to migrate into a new VM in later releases. -3. Go to **Datasets**, locate the zvol for the Instance VM, and take a snapshot of the volume as a backup. - Repeat for each VM zvol you want to migrate. +3. Go to **Datasets**, locate the pool associated with Instances (Containers), and take a recursive snapshot to back up all Instances VM zvols. + These zvols are in the hidden **.ix-virt** directory created in the pool Instances uses, selected when you configure the feature. + To verify the pool, you can go to **Containers > Configure > Global Settings** and look at the **Pool** setting. 4. Go to **System > Update**, and update to the next publicly available maintenance or major version release. Follow the release migration paths outlined in the version release notes or the [Software Releases](https://www.truenas.com/docs/softwarereleases/) article. @@ -449,7 +448,7 @@ While in a 25.04.01 or a later maintenance release: Refer to the troubleshooting tips below for more information. 25.10 releases correct some issues encountered in 25.04.2.4 VMs that are migrated. {{< expand "Troubleshooting VM Issues" "v" >}} - After upgrading from 24.10 to 25.04, VMs are visible and running, but are expected to have issues because 25.04 release does not fully support these older VMs. + If upgrading from 24.10 to 25.04, VMs are visible and running, but are expected to have issues because 25.04 release does not fully support these older VMs. VMs with a Windows OS installed could require converting to VirtIO-SCSI disks to get reconnected to the Internet. To restore connectivity, try clean-mounting the system from the mounted drive from within the VM, and then on the TrueNAS system (host). @@ -464,14 +463,10 @@ While in a 25.04.01 or a later maintenance release: If this VM cannot find the NIC, delete the NIC in the configuration from the **Devices** screen for that VM, and then reconfigure it to restore functionality. {{< /expand >}} -After updating to 25.10 or later: - 5. Go to **Containers** to see which VMs are listed, then click **Configuration**, and then **Manage Volumes** to open the **Volumes** window. Take a screenshot of the volumes listed, or copy/paste the volumes and VM information into a text file to use later in this procedure. -6. Go to **Virtual Machines** to see which are listed. - -7. Go to **System > Shell**. Exit to the Linux prompt for the system. +6. Go to **System > Shell**. Exit to the Linux prompt for the system. Note: This is where the logged in admin user needs `sudo` permissions, or where the root user must have a password configured to enter the following commands to find, rename/move, and verify each Instance zvol is properly configured. @@ -541,7 +536,8 @@ After updating to 25.10 or later: After completing the commands listed above for each zvol you want to migrate. Go to **Datasets** and verify all volumes you migrated show on the screen. -8. Create the new VM using the migrated zvol. Repeat these steps for each zvol you migrated. +7. Create the new VM using the migrated zvol. Repeat these steps for each zvol you migrated. + Go to **Virtual Machines**, click on **Add** to open the **Create Virtual Machine** wizard. a. Complete the first screen by entering a name for the new VM, select the operating system used by the Instances VM, enter a brief description, then if using the **Bind** setting, enter a password. Click **Next**. @@ -555,14 +551,11 @@ After updating to 25.10 or later: After adding the new VM, click on it to expand it, and click **Devices**. Click **Edit** for the **Disk** device, and enter **1000** in the **Device Order** field. + Setting the disk to **1000** makes the disk device the first in the boot order for the VM. + Setting the disk to first in boot order over a CD-ROM device with an OS on it, if added when creating the VM, prevents the volume from being overwritten by booting from that CD-ROM device. Click **Save**. - This sets the VM to boot from the disk, which prevents the volume from being overwritten by booting from the CD-ROM device with an OS image file on it (if you added one in the creation wizard). -9. Return to the **Virtual Machines** screen, expand the VM, then click **Start** to verify it opens as expected and has Internet access. -Footer -© 2025 GitHub, Inc. -Footer navigation -Terms +8. Return to the **Virtual Machines** screen, expand the VM, then click **Start** to verify it opens as expected and has Internet access.
diff --git a/static/includes/25.04Virtualization.md b/static/includes/25.04Virtualization.md index 423bce85f9..64ea8c07bb 100644 --- a/static/includes/25.04Virtualization.md +++ b/static/includes/25.04Virtualization.md @@ -1,10 +1,8 @@ -{{< hint type=important icon=gdoc_notification title="Virtual Machines and Containers in TrueNAS 25.04" >}} +{{< hint type=important icon=gdoc_info_outline title="Virtual Machines and Containers in TrueNAS 25.04" >}} -rueNAS 25.04.0 introduced support for **Containers** (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in TrueNAS CORE. - -TrueNAS 25.04.2 reintroduces "classic virtualization" with the [**Virtual Machines**]({{< ref"/scaletutorials/virtualmachines/" >}}) feature. +TrueNAS 25.04 introduces support for **Containers** (named Instances in pre-25.04.2 releases), enabling lightweight isolation similar to jails in TrueNAS CORE. In TrueNAS 25.04.2 (and later) virtual machines are created and appear on the **Virtual Machines** screen. Legacy VMs created in 25.04.0 or 25.04.1 using the Instances feature and some VMs migrated to those versions from TrueNAS 24.10 continue to function and appear on the **Containers** screen. @@ -25,7 +23,8 @@ VMs created in 24.10 or earlier are located depending on migration path: - VMs on 24.10 systems that upgrade directly to 25.04.2 (skipping 25.04.0/25.04.1) automatically migrate to the **Virtual Machines** screen without manual action. {{< /expand >}} -You do not need to migrate existing VMs from the **Containers** screen to the **Virtual Machines** screen at this time, but 25.10 and future releases allow migrating the storage zvols to new VMs created in 25.10 and later. For more information, see **[Migrating Instance VMs]({{< ref "/scaletutorials/virtualmachines/" >}})**. +Users with existing VMs on the **Containers** screen should consider migrating associated zvols to the **Virtual Machines** screen at this time to ensure compatibility with future TrueNAS releases. +For more information, see **[Migrating Containers VMs]({{< ref "/SCALETutorials/VirtualMachines/#migrating-containers-vms" >}})**. {{< /hint >}} diff --git a/words-to-ignore.txt b/words-to-ignore.txt index bb785bc7e0..24e28683f3 100644 --- a/words-to-ignore.txt +++ b/words-to-ignore.txt @@ -2318,3 +2318,6 @@ Netlogon ENOENT incus hostnqn +InstanceWarning +VirtualMachines +virtualmachines From deb2f603dac20559ae36d00e77de837086474a1d Mon Sep 17 00:00:00 2001 From: Mic Johnson Date: Thu, 30 Oct 2025 16:27:21 -0400 Subject: [PATCH 4/6] PD-2172 Updates to match 25.10 Branch Changes This commit adds information and a new command to set zvol properties to match those of natively-created VM zvols. --- content/SCALETutorials/VirtualMachines/_index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/SCALETutorials/VirtualMachines/_index.md b/content/SCALETutorials/VirtualMachines/_index.md index 2083d66c68..8255757334 100644 --- a/content/SCALETutorials/VirtualMachines/_index.md +++ b/content/SCALETutorials/VirtualMachines/_index.md @@ -404,7 +404,7 @@ The process involves: * Identifying the hidden storage volumes (zvols) associated with the Instance VMs. * Renaming (and moving) the zvols to a new dataset where they can be seen and used by a new VM. -* Verifying the `volmode` for the zvol is correctly configured. +* (Highly Recommended) Configuring zvol properties to match those of natively-created VM zvols. * Creating a new VM and selecting the migrated zvol as the storage volume. Before beginning the process: @@ -521,18 +521,18 @@ While in a 25.04.01 or a later maintenance release: This renames and moves it to the specified location, and returns to the system Linux prompt. To verify the zvol moved, enter the sudo zfs list -t volume -r tank command again. The output should show the zvol in the new location. - c. Verify the `volmode`. Enter the following command for each zvol you rename. + c. (Highly Recommended) Set zvol properties to match those of natively-created VM zvols. + Enter the following command for each zvol you migrated: - sudo zfs get volmode tank/vms/efault_vm2410linux-icppg_vm2410linuxclone1 + sudo zfs set volmode=default primarycache=all secondarycache=all tank/vms/default_debian1-urec9f Where: * *tank* is the pool name. * *vms* is the dataset where the zvol is stored. * *default_vm2410linux-icppg_vm2410linuxclone1* is the name of the zvol - This returns the `volmode` for the volume. It should be set to `dev`. If not, enter the following command to set it to `dev`: - - sudo zfs set volmode=dev tank/vms/efault_vm2410linux-icppg_vm2410linuxclone1 + This command sets the volume properties to match those used by zvols created through the **Virtual Machines** screen, ensuring optimal performance and behavior. + Containers VMs used different property settings that are not optimal for virtual machine workloads. After completing the commands listed above for each zvol you want to migrate. Go to **Datasets** and verify all volumes you migrated show on the screen. From 106248f8c98f764c92c79f4dcab0431ba66642d5 Mon Sep 17 00:00:00 2001 From: tonyriv3 <75626853+tonyriv3@users.noreply.github.com> Date: Thu, 30 Oct 2025 19:59:25 -0400 Subject: [PATCH 5/6] Update _index.md --- .../SCALETutorials/VirtualMachines/_index.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/content/SCALETutorials/VirtualMachines/_index.md b/content/SCALETutorials/VirtualMachines/_index.md index 8255757334..ac2ae43af9 100644 --- a/content/SCALETutorials/VirtualMachines/_index.md +++ b/content/SCALETutorials/VirtualMachines/_index.md @@ -18,11 +18,11 @@ keywords: TrueNAS includes built-in virtualization capabilities that let you run multiple operating systems on a single system, maximizing hardware utilization and consolidating workloads. -A *virtual machine (VM)* is a software-based computer that runs inside your TrueNAS system, appearing as a separate physical machine to the operating system installed within it. VMs use virtualized hardware components including network interfaces, storage, graphics adapters, and other devices, providing complete isolation between different operating systems and applications. +A *virtual machine (VM)* is a software-based computer that runs inside your TrueNAS system, appearing as a separate physical machine to the operating system installed within it. VMs use virtualized hardware components, including network interfaces, storage, graphics adapters, and other devices, providing complete isolation between different operating systems and applications. VMs offer stronger isolation than [containers](/scaletutorials/containers/) but require more system resources, making them ideal for running full operating systems, legacy applications, or services that need dedicated environments. -Enterprise licensed High Availability (HA) systems do not support virtual machines. +Enterprise-licensed High Availability (HA) systems do not support virtual machines. {{< expand "What system resources do VMs require?" "v" >}} {{< include file="/static/includes/VMRequirements.md" >}} @@ -55,7 +55,7 @@ If you have not yet added a virtual machine to your system, click **Add Virtual Secure Boot is required for Windows 11 and some Linux distributions, and can be optional or unsupported for older operating systems. Select **Enable Trusted Platform Module (TPM)** to provide a virtual TPM 2.0 device for the VM. - TPM provides hardware-based security functions including secure key storage, cryptographic operations, and platform attestation. + TPM provides hardware-based security functions, including secure key storage, cryptographic operations, and platform attestation. This is required for Windows 11 and enhances security for other operating systems that support TPM. Select **Enable Display** to enable a SPICE Virtual Network Computing (VNC) remote connection for the VM. @@ -63,7 +63,7 @@ If you have not yet added a virtual machine to your system, click **Add Virtual Enter a display **Password** - Use the dropdown menu to change the default IP address in **Bind** if you want to use a specific address as the display network interface, otherwise leave it set to **0.0.0.0**. + Use the dropdown menu to change the default IP address in **Bind** if you want to use a specific address as the display network interface. Otherwise, leave it set to **0.0.0.0**. The **Bind** menu populates any existing logical interfaces, such as static routes, configured on the system. **Bind** cannot be edited after VM creation. @@ -84,7 +84,7 @@ If you have not yet added a virtual machine to your system, click **Add Virtual To dedicate a fixed amount of RAM, enter a value (minimum 256 MiB) in the **Memory Size** field and leave **Minimum Memory Size** empty. To allow for memory usage flexibility (sometimes called ballooning), define a specific value in the **Minimum Memory Size** field and a larger value in **Memory Size**. - The VM uses the **Minimum Memory Size** for normal operations but can dynamically allocate up to the defined **Memory Size** value in situations where the VM requires additional memory. + The VM uses the **Minimum Memory Size** for normal operations, but can dynamically allocate up to the defined **Memory Size** value in situations where the VM requires additional memory. Reviewing available memory from within the VM typically shows the **Minimum Memory Size**. Click **Next**. @@ -121,7 +121,7 @@ If you have not yet added a virtual machine to your system, click **Add Virtual {{< trueimage src="/images/SCALE/Virtualization/AddVMInstallMedia.png" alt="Installation Media" id="Installation Media" >}} - You can create the VM without an OS installed. To add it either type the path or browse to the location and select it. + You can create the VM without an OS installed. To add it, either type the path or browse to the location and select it. To upload an iso select **Upload New Image File** and either enter the path or browse to the location of the file. @@ -134,7 +134,7 @@ If you have not yet added a virtual machine to your system, click **Add Virtual {{< trueimage src="/images/SCALE/Virtualization/AddVMGPU.png" alt="GPU Screen" id="GPU Screen" >}} {{< hint type="note" title="Supported GPUs" >}} - TrueNAS does not have a list of approved GPUs at this time but TrueNAS does support various GPUs from NVIDIA, Intel, and AMD. + TrueNAS does not have a list of approved GPUs at this time, but TrueNAS does support various GPUs from NVIDIA, Intel, and AMD. As of 24.10, TrueNAS does not automatically install NVIDIA drivers. Instead, users must manually install drivers from the UI. For detailed instructions, see [Installing NVIDIA Drivers](https://apps.truenas.com/getting-started/initial-setup/#installing-nvidia-drivers). {{< /hint >}} @@ -182,7 +182,7 @@ Use the **Power Off** button instead. ## Installing an OS -After configuring the VM in TrueNAS and an OS .iso file is attached, start the VM and begin installing the operating system. +After configuring the VM in TrueNAS and attaching an OS .iso file, start the VM and begin installing the operating system. {{< hint type="note" title="OS Specific Settings" >}} Some operating systems can require specific settings to function properly in a virtual machine. @@ -337,9 +337,9 @@ To ensure it starts automatically, create the startup.nsh file at t 1. Go to the **Shell**. -2. At the shell prompt enter `edit startup.nsh`. +2. At the shell prompt, enter `edit startup.nsh`. -3. In the editor enter: +3. In the editor, enter: a. Enter `FS0:` and press Enter. @@ -426,7 +426,7 @@ This procedure applies to the zvol for an Instance VM that has data you want to While in a 25.04.01 or a later maintenance release: 1. Go to **Instances**, click on **Configuration**, and then **Manage Volumes** to open the **Volumes** window. - The **Volumes** window lists all Instance VMs and the assoicated storage volumes (zvols). + The **Volumes** window lists all Instance VMs and the associated storage volumes (zvols). Record the volume name or take a screenshot of the information to refer to later when entering commands in the **Shell** screen. Zvol names are similar to the VM name but not identical. @@ -448,11 +448,11 @@ While in a 25.04.01 or a later maintenance release: Refer to the troubleshooting tips below for more information. 25.10 releases correct some issues encountered in 25.04.2.4 VMs that are migrated. {{< expand "Troubleshooting VM Issues" "v" >}} - If upgrading from 24.10 to 25.04, VMs are visible and running, but are expected to have issues because 25.04 release does not fully support these older VMs. + If upgrading from 24.10 to 25.04, VMs are visible and running, but are expected to have issues because the 25.04 release does not fully support these older VMs. VMs with a Windows OS installed could require converting to VirtIO-SCSI disks to get reconnected to the Internet. To restore connectivity, try clean-mounting the system from the mounted drive from within the VM, and then on the TrueNAS system (host). - Follow this by removing driver syntax added to raw qem files. + Follow this by removing driver syntax added to raw QEM files. If a new VM is created in 25.04.2.1 and it fails to run, stop all containers. In the VM configuration, delete the current NIC, then select the bridge before selecting the NIC again to restore functionality. @@ -472,7 +472,7 @@ While in a 25.04.01 or a later maintenance release: Enter the following commands at the Linux system prompt: - a. Locate the hidden zvols for the Instance VMs, by entering: + a. Locate the hidden zvols for the Instance VMs by entering: sudo zfs list -t volume -r -d 10 poolname @@ -481,7 +481,7 @@ While in a 25.04.01 or a later maintenance release: * *poolname* is the name of the pool associated with the Instance VMs. If you have multiple pools associated with the Instance VMs, repeat this command with the name of that pool to show hidden zvols in that pool. - The **.ix-virt** directory contains the zvols use in Instance VMs. Ignore the entries with the **.block** extension. + The **.ix-virt** directory contains the zvols used in Instance VMs. Ignore the entries with the **.block** extension. The output includes other zvols in the pool if your system has non-instance VMs configured in the pool name entered in the command. {{< expand "Example Command Output" "v" >}} @@ -506,7 +506,7 @@ While in a 25.04.01 or a later maintenance release: The zvols in the command output above with `tank/.ix-virt/custom` in the path are the zvols to migrate if these are associated with the VM you want to migrate to new VMs in the 25.10.0 or later release. {{< /expand >}} - b. Rename (and move) each volume in the **.ix-virt** directory to a new location where you can select it when configuration a new VM. + b. Rename (and move) each volume in the **.ix-virt** directory to a new location where you can select it when configuring a new VM. Repeat for each volume you want to migrate to a new VM. Do not rename or move the .block volumes. Enter the following command: @@ -532,15 +532,15 @@ While in a 25.04.01 or a later maintenance release: * *default_vm2410linux-icppg_vm2410linuxclone1* is the name of the zvol This command sets the volume properties to match those used by zvols created through the **Virtual Machines** screen, ensuring optimal performance and behavior. - Containers VMs used different property settings that are not optimal for virtual machine workloads. + Containers VMs use different property settings that are not optimal for virtual machine workloads. - After completing the commands listed above for each zvol you want to migrate. Go to **Datasets** and verify all volumes you migrated show on the screen. + After completing the commands listed above for each zvol you want to migrate. Go to **Datasets** and verify that all volumes you migrated show on the screen. 7. Create the new VM using the migrated zvol. Repeat these steps for each zvol you migrated. Go to **Virtual Machines**, click on **Add** to open the **Create Virtual Machine** wizard. - a. Complete the first screen by entering a name for the new VM, select the operating system used by the Instances VM, enter a brief description, then if using the **Bind** setting, enter a password. Click **Next**. + a. Complete the first screen by entering a name for the new VM. Select the operating system used by the Instances VM, enter a brief description, then, if using the **Bind** setting, enter a password. Click **Next**. b. Configure the CPU and Memory settings, and then click **Next**. From d12dce64ef0eba8c8f029ed7ade6f5d1af2e08bb Mon Sep 17 00:00:00 2001 From: tonyriv3 <75626853+tonyriv3@users.noreply.github.com> Date: Fri, 31 Oct 2025 09:25:31 -0400 Subject: [PATCH 6/6] Update _index.md --- content/SCALETutorials/VirtualMachines/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/SCALETutorials/VirtualMachines/_index.md b/content/SCALETutorials/VirtualMachines/_index.md index ac2ae43af9..3b6c2d32e4 100644 --- a/content/SCALETutorials/VirtualMachines/_index.md +++ b/content/SCALETutorials/VirtualMachines/_index.md @@ -339,7 +339,7 @@ To ensure it starts automatically, create the startup.nsh file at t 2. At the shell prompt, enter `edit startup.nsh`. -3. In the editor, enter: +3. In the editor: a. Enter `FS0:` and press Enter.