Virtual Machines

22 minute read.

Last Modified 2025-08-28 09:02 EDT

Virtual Machines Screen

The Virtual Machines screen allows users to add, edit, or manage virtual machines (VMs) or VM devices in TrueNAS. The No Virtual Machines screen shows when there are no VMs configured in or deleted from TrueNAS.

Add Virtual Machines and Add at the top right of the screen opens the Create Virtual Machine wizard.

Each virtual machine listed, includes the Running and Start on Boot toggles. Running shows the current state of the VM. Start on Boot automatically starts the VM after a system reboot.

Expanding a VM shows the details screen details on and options for that VM.

Virtual Machine Details Screen

The expanded Virtual Machines screen shows the details and options for a VM. Details include the basic information on the number of virtual CPUs, cores, and threads, the amount of memory, boot loader, and system clock types, the display port number, and the shutdown timeout in seconds.

Options shown change after starting a virtual machine.

VM Options

Operation	Icon	Description
Start		Starts a VM. The toggle turns blue when the VM switches to running. The Start button toggles to Stop. While running, the screens shows the Restart,Power Off, Display, and Serial Shell buttons.
Restart	replay	Stops then starts the VM. Shows for a running VM.
Power Off	power_settings_new	Shows after starting a VM. Powers off and halts the VM, similar to turning off a computer power switch. Shows only when the VM is running.
Stop		Shows after starting a VM. Stops a running VM. Virtual machines do not always respond to STOP or the command might time out if the VM does not have an OS. Use Power Off instead. Stop toggles to Start after the VM stops.
Edit	mode_edit	Opens the Edit Virtual Machine with editable VM settings. You cannot edit a VM while it is running. Stop the VM to edit the properties and settings.
Delete		Deletes a VM and removes it from the system. Opens a delete dialog. You cannot delete a virtual machine that is running. Stop the VM to delete it.
Devices		Shows after starting a VM. Opens the Virtual Machine Devices screen for the selected VM.
Clone		Shows after starting the VM. Makes an exact clone copy of the VM. Opens the Clone dialog.
Display		Shows after starting the VM. Opens the SPICE login screen in a new browser window and allows you to connect to the remote desktop after entering the password to access that remote desktop.
Serial Shell		Shows after starting the VM. Opens the TrueNAS VM Serial Shell screen.
Download Logs	content_paste	Places a copy of the .log file on the system.

Delete Virtual Machine Dialog

The Delete Virtual Machine dialog shows options when deleting the VM and removing the VM configuration from your system.

Setting	Description
Delete Virtual Machine Data	Removes the data associated with this virtual machine. Deleting a VM results in data loss if the data is not backed up. Do not select this option to keep the VM data intact.
Force Delete	Ignores the virtual machine status during the delete operation. Do not select this option to prevent deleting the VM when it is still active or the state is undefined.
*Enter vmname* below to confirm**	Blank text entry field to manually enter the name of the VM to delete. This must match the name shown in the dialog.

Clone Virtual Machine Dialog

The Clone dialog settings create an exact duplicate (clone) of the VM. The blank field allows manual entry of a name for the clone of the selected VM. Naming the clone VM is optional.

A cloned VM shows on the Virtual Machines list with the extension _clone0. Cloning the same VM again changes the extension for the second clone to clone1.

VM Serial Shell Screen

The Serial Shell button opens the VM Serial Shell screen, where you can enter commands for the selected virtual machine.

The Virtual Machines breadcrumb in the header to returns to the Virtual Machine screen.

Edit Virtual Machine Screen

The Edit VM screen shows a subset of settings in the Create Virtual Machine screens. It includes the general settings also on the wizard Operating System screen, CPU and Memory, and GPUs screen settings. To edit disks, network, or display settings, click Devices on the expanded view of the VM to open the Devices screen.

General Settings

The Edit screen General Settings specifies the basic settings for a VM. Unlike the Create Virtual Machine wizard, you cannot change the Enable or Start on Boot status or change the display type or bind address for a saved VM from this screen.

General Settings

Setting	Description
Name	Required. Enter an alphanumeric name for the virtual machine.
Description	Enter a description (optional).
System Clock	Select the VM system time from the dropdown list. Options are Local or UTC. The default is Local.
Boot Method	Select the boot method option from the dropdown list. Select UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Shutdown Timeout	Enter the time, in seconds, the system waits for the VM to cleanly shut down. During the shutdown, the system powers off the VM after the shutdown timeout entered expires.
Start on Boot	Select to start this VM when the system boots.
Enable Hyper-V Enlightenments	Shows for VMs set for Windows OS. KVM implements Hyper-V Enlightenments for Windows guests. These features make Windows think they are running on a Hyper-V-compatible hypervisor and use Hyper-V-specific features. In some cases, enabling these enlightenments might improve the usability and performance for the guest.
Enable Secure Boot	Turns on the secure boot function in TrueNAS. Some operating systems, like Windows 11, might not require secure boot.
Enable Trusted Platform Module (TPM)	Turns on the Trusted Platform Module (TPM) for enhanced security features in TrueNAS. TPM provides hardware-based cryptographic security functions, Some operating systems, like Windows 11, might require enabling this option.

Edit CPU and Memory Settings

The CPU and Memory settings on the Edit VM screen are the same as those in the Create Virtual Machine wizard.

CPU and Memory Settings

Setting	Description
Virtual CPUs	Text entry field to manually enter the number of virtual CPUs to allocate to the virtual machine. The VM operating system might have operational or licensing restrictions on the number of CPUs. Consult the documentation and requirements for the planned operating system configured for this VM.
Cores	Text entry field to manually enter the number of cores per virtual CPU socket.
Threads	Text entry field to manually enter the number of threads per core.
Optional: CPU Set (Example: 0-3,8-11)	Text entry field to manually enter the logical cores this VM can use. Better cache locality can be achieved by setting the CPU set based on the CPU topology (e.g., to assign cores 0, 1, 2, 5, 9, 10, and 11, you can enter 1-2,5,9-11).
Pinvcpus	Set to automatically pin into the CPU when the number of vcpus equals the number of CPUs in the CPU. Pinning is done by mapping each vcpu into a single CPU number following the order in CPU set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode	Sets the CPU mode to the option selected on the dropdown list. Options are: Custom, Host Model, and Host Passthrough.
Custom shows the CPU Model setting.
CPU Model	Sets the CPU model to the option selected on the dropdown list.
Memory Size	Text entry field to manually enter the amount of RAM allocated for the VM. The minimum value is 256 MiB.
Minimum Memory Size	Text entry field to manually enter the minimum amount of memory. When not specified, a guest system is given a fixed amount of memory specified above. When specified, a guest system is given memory within the range between the minimum and fixed as needed.
Optional: NUMA nodeset (Example: 0-1)	Text entry field to manually enter the node sets. The node set allows setting NUMA nodes for multi-NUMA processors when the CPU set is defined. Better memory locality can be achieved by setting the node set based on the assigned CPU set (e.g., if CPUs is 0, and 1 belongs to NUMA node 0, then setting nodeset to 0 improves memory locality).

Edit GPU Settings

The GPU settings on the Edit screen are the same as those in the Create Virtual Machine wizard.

GPU Settings

Setting	Description
Hide from MSR	Hides the GPU from the model-specific registers (MSRs). MSRs are the low-level CPU registers that enable the hardware features necessary for GPU virtualization to work properly. They control processor features and behaviors, store configuration settings, provide hardware information, and enable/disable specific GPU capabilities. In GPU passthrough configurations, MSRs control PCIe settings for direct GPU access. VMware ESXi uses MSRs for vGPU configuration, Proxmox/QEMU MSRs enable GPU passthrough, and Hyper-V MSRs control RemoteFX/GPU-P features.
Ensure Display Device	Ensures the guest always has access to a video device. For headless installations like an Ubuntu server, this is required for the guest to operate properly. However, for cases where a consumer wants to use GPU passthrough and does not want a display device added, do not enable this option.
GPUs	Sets the GPU to the option selected on the dropdown list.

Devices Screens

The Devices screen shows a table listing of VM devices configured on your system. By default, the screen shows three devices: Disks, NIC, and Display.

Add opens the Add Device screen. Settings change based on the various device types.

The more_vert at the right of each device row has three options:

Edit - Opens the Edit type Device screen where type is the device type selected. Settings vary based on the type of device selected in Device Type. See Add Device screen. Device Type only displays on the Add Device screens.
Delete - Opens the Delete Device dialog.
Details - Opens an information dialog showing the port, type, bind IP, and other details about the device.

Create Virtual Machine Wizard Screens

The Create Virtual Machine wizard includes all settings to set up a new virtual machine in TrueNAS.

Next and Back advance to the next screen or return to the previous screen without saving or losing setting choices. Save saves all settings, closes the wizard, and adds the new VM to the Virtual Machines screen.

Operating System Settings

The Operating System settings specify the VM operating system type, the time setting the VM system clock uses, the boot method, and the display type.

Operating System Settings

Setting	Description
Guest Operating System	(Required) Sets the operating system for the VM operating system to the option selected on the dropdown list. Options are Windows, which adds the Enable Hyper-V Enlightenments option. Linux, and FreeBSD.
Enable Hyper-V Enlightenments	Only shows when Guest Operating System is set to Windows. When enabled, the VM emulates a Hyper-V-compatible hypervisor for the Windows guest operating system and makes some Hyper-V-specific features available.
Name	(Required) Text entry field that accepts manual or copy/paste entry of a name for the VM that consists of alphanumeric characters.
Description	(Optional) Text entry field that accepts manual or copy/paste entry of a brief description about the VM. For example, the type of OS for the VM or the purpose of the VM.
System Clock	(Required) Sets the VM system clock to the option selected on the dropdown list. Options are: Local, which uses the TrueNAS SCALE system clock setting, or UTC, which uses the Coordinated Universal Time clock. The default is Local.
Boot Method	(Required) Sets the boot method to the option selected on the dropdown list. Options are: UEFI for newer operating systems or Legacy BIOS for older operating systems that only support BIOS booting.
Enable Secure Boot	Sets the VM to verify boot components using digital signatures. This prevents unauthorized code from running during startup and is required for Windows 11 and some Linux distributions.
Enable Trusted Platform Module (TPM)	Sets TrueNAS to provide a virtual TPM 2.0 device for the VM. This enables hardware-based security functions, including secure key storage and cryptographic operations. Required for Windows 11.
Shutdown Timeout	Text entry field that accepts manual entry of a time in seconds that the system waits for the VM to cleanly shut down. During system shutdown, the system powers off after the shutdown timeout entered for the VM expires.
Start on Boot	Sets the VM to automatically start after restarting the system or when it is rebooted. Selected by default.
Enable Display (VNC)	Enables a VNC display (Virtual Network Computing) remote connection. VNC is the default display type when adding a VM. Requires UEFI booting. Selected by default.
Bind	Shows when Enable Display is selected. Sets an IP address to use for remote VNC sessions. Note that this setting only applies when using a VNC client other than the TrueNAS WebUI.
Password	(Required) Displays when Enable Display is selected.Enter a password to secure access to the VM. Enter this when logging into the VNC display.

CPU and Memory Settings

The CPU and Memory settings specify the CPU mode, model, and memory size. They allow specifying the number of virtual CPUs to allocate to the virtual machine, the number of cores per virtual CPU socket, and the number of threads per core.

CPU and Memory Settings

Setting	Description
Virtual CPUs	Text entry field to manually enter the number of virtual CPUs to allocate to the virtual machine. The VM operating system might have operational or licensing restrictions on the number of CPUs. Consult the documentation and requirements for the planned operating system configured for this VM.
Cores	Text entry field to manually enter the number of cores per virtual CPU socket.
Threads	Text entry field to manually enter the number of threads per core.
Optional: CPU Set (Example: 0-3,8-11)	Text entry field to manually enter the logical cores this VM can use. Better cache locality can be achieved by setting the CPU set based on the CPU topology (e.g., to assign cores 0, 1, 2, 5, 9, 10, and 11, you can enter 1-2,5,9-11).
Pinvcpus	Set to automatically pin into the CPU when the number of vcpus equals the number of CPUs in the CPU. Pinning is done by mapping each vcpu into a single CPU number following the order in CPU set. This improves CPU cache locality and can reduce possible stutter in GPU passthrough VMs.
CPU Mode	Sets the CPU mode to the option selected on the dropdown list. Options are: Custom, Host Model, and Host Passthrough.
Custom shows the CPU Model setting.
CPU Model	Sets the CPU model to the option selected on the dropdown list.
Memory Size	Text entry field to manually enter the amount of RAM allocated for the VM. The minimum value is 256 MiB.
Minimum Memory Size	Text entry field to manually enter the minimum amount of memory. When not specified, a guest system is given a fixed amount of memory specified above. When specified, a guest system is given memory within the range between the minimum and fixed as needed.
Optional: NUMA nodeset (Example: 0-1)	Text entry field to manually enter the node sets. The node set allows setting NUMA nodes for multi-NUMA processors when the CPU set is defined. Better memory locality can be achieved by setting the node set based on the assigned CPU set (e.g., if CPUs is 0, and 1 belongs to NUMA node 0, then setting nodeset to 0 improves memory locality).

Disks Settings

The Disks settings specify how virtual disks are added. Options are creating a new zvol on an existing dataset for a disk image, or using an existing zvol or file for the VM.

Disks Settings

Setting	Description
Create new disk image	Shows settings to create a new zvol on an existing dataset to use as a virtual hard drive for the VM.
Use existing disk image	Shows settings to select an existing zvol or file for the VM. Shows the Select Disk Type and Select Existing Zvol fields.
Select Disk Type	Sets the disk type to the option selected on the dropdown list. Options are AHCI or VirtIO. Select AHCI for Windows VMs. VirtIO requires a guest OS that supports VirtIO paravirtualized network drivers.
Select Existing Zvol	(Required) Shows after selecting Use existing disk image. Sets the disk to the existing zvol selected from the dropdown list.
Zvol Location	(Required) Shows when Create new disk image is selected. Shows a dropdown list of datasets to select as the location where a new zvol is created.
Size	(Required) Shows when *Create new disk image is selected. Allocates space for the new zvol. (Examples: 500 KiB, 500M, 2 TB). Units smaller than MiB are not allowed.

Network Interface Settings

The Network Interface settings specify the network adapter type, MAC address, and physical network interface card associated with the VM.

Network Interface Settings

Setting	Description
Adapter Type	Sets the adapter type to the option selected on the dropdown list. Options are: Intel e82545 (e1000) - Emulates the same Intel Ethernet card and provides compatibility with most operating systems. VirtIO - Provides better performance when the operating system installed in the VM supports VirtIO para-virtualized network drivers.
Mac Address	Shows the MAC address automatically entered by TrueNAS. Enter the desired address into the field to override the randomized MAC address.
Attach NIC	Sets the physical interface to associate with the VM selected on the dropdown list.
Trust Guest Filters	Enables and allows the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Enabling Trust Guest Filters has security risks because it allows the virtual server to change its MAC address and so receive all frames delivered to this address. Disabled by default.

Installation Media Screen

The Installation Media settings specify the location of the operating system installation media image in a TrueNAS dataset, or you can upload a copy from the local machine.

Installation Media Settings

Setting	Description
Choose Installation Media Image	Shows two fields, the mount path field and a file browser field directly below it. Sets the mount path to what is selected in the file browser field. To collapse the file branch, click on the to the left of /mnt.
Upload New Image File	Opens the Upload Image File dialog, where you browse to, and select the image file location on the local system or a network location available to your TrueNAS system. Choose File sets the file location and activates Upload.

Upload Installation Media Dialog

Upload Installation Media Settings

Setting	Description
ISO save location	Enter the path or browse to the location where you want to install the image file.
Choose File	Click to save the path populated in the ISO save location field.
Upload	Click to upload the file selected in the ISO save location field.

GPU Screen

The GPU settings specify the graphics processing unit (GPU) for the VM. It also provides the option to hide the VM from the Microsoft Reserved Partition (MSR) on Windows systems.

GPU Settings

Setting	Description
Hide from MSR	Hides the GPU from the model-specific registers (MSRs). MSRs are the low-level CPU registers that enable the hardware features necessary for GPU virtualization to work properly. They control processor features and behaviors, store configuration settings, provide hardware information, and enable/disable specific GPU capabilities. In GPU passthrough configurations, MSRs control PCIe settings for direct GPU access. VMware ESXi uses MSRs for vGPU configuration, Proxmox/QEMU MSRs enable GPU passthrough, and Hyper-V MSRs control RemoteFX/GPU-P features.
Ensure Display Device	Ensures the guest always has access to a video device. For headless installations like an Ubuntu server, this is required for the guest to operate properly. However, for cases where a consumer wants to use GPU passthrough and does not want a display device added, do not enable this option.
GPUs	Sets the GPU to the option selected on the dropdown list.

Confirm Options Screen

The Confirm Options screen shows a summary of settings for the VM, including the number of CPUs, cores, threads, memory, name of the VM, and the disk size.

Save adds the VM to the Virtual Machines screen.

Add Device Screen

The Add Device screen shows different settings based on the option selected in Device Type. Settings change based on the type except the Type and Device Order settings, which are common to all device types.

Type sets the device type to the option selected on the dropdown list. The default selection is CD-ROM.

Device Order sets the position of the device in the boot order used when the system boots up or restarts. Accepts a number (such as 1003) that represents where in the boot order this device should be. The higher the number, the later in the boot-up process the device falls.

CD-ROM Settings

CD-ROM settings show when Device Type is set to CD-ROM.

CD-ROM Path shows two fields: the /mnt path field that populates with what is selected with the file browser field directly below it. The to the left of /mnt expands or collapses the directory branch while you browse to the location of the CD-ROM file on the system. |

NIC Settings

VM network interface card settings show when Device Type is set to NIC.

Setting	Description
Adapter Type	(Required) Sets the emulator type to the option selected in the dropdown list. Emulating an Intel e82545 (e1000) Ethernet card provides compatibility with most operating systems. VirtIO provides better performance for systems with VirtIO paravirtualized network driver support.
MAC Address	Shows the default auto-generated random MAC address the VM receives. Enter a custom address to override the default.
Generate	Generates a new randomized address in MAC Address.
NIC To attach	Sets a physical interface to associate with the VM to the device selected on the dropdown list.
Trust Guest Filters	Allows the virtual server to change its MAC address. As a consequence, the virtual server can join multicast groups. The ability to join multicast groups is a prerequisite for the IPv6 Neighbor Discovery Protocol (NDP). Setting Trust Guest Filters to “yes” has security risks because it allows the virtual server to change its MAC address and receive all frames delivered to this address. The default setting is not enabled.

Disk Settings

Disk settings, including disk location, drive type, and disk sector size, show when Device Type is set to Disk.

Setting	Description
Zvol	Sets the zvol path to the options selected on the dropdown list.
Mode	Sets the drive type to the option selected on the dropdown list. Options are AHCI or VirtIO.
Disk sector size	Sets the disk sector size in bytes to the option selected on the dropdown list, or leave it set to Default. Options are: Default, which uses the ZFS volume values, 512, or 4096. Setting a sector size changes both the logical and physical sector size.

Display Settings

Display settings show when Device Type is set to Display. You can only have one display type set to either VNC (the default when creating a new VM) but can add a second display device set to SPICE.

Remote clients can connect to VM display sessions using a SPICE client, or by installing a third-party remote desktop server inside your VM. SPICE clients are available from the SPICE Protocol site.

Setting	Description
Display Type	Sets a new display device type to the option selected. If the VM is created with no display setting, the options shown in Display Type are VNC or SPICE. If the VM is created with the default VNC display, only the SPICE option shows in on the dropdown list. If you create a VM without adding the device and then later add a display device, the options show VNC and SPICE on the dropdown list. TrueNAS allows creating two display devices, one from the VM creation wizard, which uses the default VNC display, and a second through the Add Device screen with the Device Type is set to Display. Only SPICE shows when adding the second display device.
Port	Text field that accepts manual or copy/paste entry of a port number. Can be set to 0, left empty for TrueNAS to assign a port when the VM is started, or set to a fixed preferred port number.
Resolution	Sets the screen resolution for the VM display session to the option selected on the dropdown list.
Bind	Sets the IP address used for the SPICE display sessions to the option selected on the dropdown list. Options include the default 0.0.0.0, ::, ::1, IP addresses obtained from your network, and the TrueNAS primary interface.
Password	Text field that accepts manual or copy/paste entry of a password, that is eight characters in length, that TrueNAS automatically passes to the remote display session.
Web Interface	Enables connecting to the SPICE web interface.

Raw File Settings

Shows the raw file settings, including file location, size, disk sector size, and type when Device Type is set to Raw File.

Setting	Description
Raw File	Shows two fields. A file browser field and a blank field that populates with what is selected in the file browser directly below it. Use the to the left of /mnt to expand or collapse the directory branches as you browse to and select the location of the file on the system.
Disk sector size	Sets the disk sector size to the option selected on the dropdown list. Options are Default, which uses the ZFS volume values, 512 or 4096. Setting a sector size changes both the logical and physical sector size.
Mode	Sets the drive type to the option selected on the dropdown list. Options are: AHCI - Emulates an AHCI hard disk for better software compatibility. VirtIO - Uses paravirtualized drivers and can provide better performance, but the operating system installed in the VM must support VirtIO disk devices. .
Raw filesize	Text field that accepts manual entry of a number for the size of the file in GiB.

PCI Passthrough Settings

Shows PCI passthrough device settings when Device Type is set to PCI Passthrough Device.

Depending upon the type of device installed in your system, you might see a PCI device does not have a reset mechanism defined warning. You might experience inconsistent or degraded behavior when starting or stopping the VM. If this occurs, determine if you want to proceed with this action.

PCI Passthrough Device sets the PCI device to what is manually entered or select on the dropdown list of options. Enter a device as bus#/slot#/fcn#, for example 0000:00:04.3 ‘System peripheral’: Sky Lake-E CBDMA Registers by ‘Intel Corporation’.

USB Passthrough Settings

Shows the USB passthrough device setting when Device Type is set to USB Passthrough Device.

Setting	Description
Controller Type	(Required) Sets the controller to the option selected on the dropdown list. Options are: piix3-uhci, piix4-uhci, ehci, ich9-ehci1, vt82c686b-uhci, pci-ohci, nec-xhci, qemu-xhci.
Device	Sets the device to the option manually entered or selected on the dropdown list of options. Selecting Specify custom shows the Vendor ID and Product ID fields.

Use Cases

Industry

Support

Resources

Virtual Machines

Virtual Machines Screen

Virtual Machine Details Screen

Delete Virtual Machine Dialog

Clone Virtual Machine Dialog

VM Serial Shell Screen

Edit Virtual Machine Screen

General Settings

Edit CPU and Memory Settings

Edit GPU Settings

Devices Screens

Create Virtual Machine Wizard Screens

Operating System Settings

CPU and Memory Settings

Disks Settings

Network Interface Settings

Installation Media Screen

Upload Installation Media Dialog

GPU Screen

Confirm Options Screen

Add Device Screen

Related Content