TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Adding and Managing VMs

A virtual machine (VM) is an environment on a host computer that you can use as if it is a separate, physical computer. Users can use VMs to run multiple operating systems simultaneously on a single computer. Operating systems running inside a VM see emulated virtual hardware rather than the host computer physical hardware. VMs provide more isolation than Jails but also consume more system resources.

What system resources do VMs require?

TrueNAS assigns a portion of system RAM and a new zvol to each VM. While a VM is running, these resources are not available to the host computer or other VMs.

TrueNAS VMs use the KVM virtual machine software. This type of virtualization requires an x86 machine running a recent Linux kernel on an Intel processor with VT (virtualization technology) extensions or an AMD processor with SVM extensions (also called AMD-V). Users cannot create VMs unless the host system supports these features.

To verify that you have Intel VT or AMD-V, check your processor model name on the vendor’s website. If needed, enable virtualization in the BIOS Advanced > CPU Configuration settings.

Creating a Virtual Machine

Before creating a VM, you need an installer .iso or image file for the OS you intend to install, and a zvol on a storage pool that is available for both the virtual disk and OS install file.

To create a new VM, go to Virtualization and click Add to open the Create Virtual Machine configuration screen. If you have not yet added a virtual machine to your system you can click Add Virtual Machines to open the same screen.

  1. Select the operating system you want to use from the Guest Operating System dropdown list.
Operating System Settings
Figure 1: Operating System Settings

Compare the recommended specifications for the guest operating system with your available host system resources when allocating virtual CPUs, cores, threads, and memory size.

  1. Change other Operating System settings per your use case.

    Select UTC as the VM system time from the System Clock dropdown if you do not want to use the default Local setting.

    Select Enable Display to enable a SPICE Virtual Network Computing (VNC) remote connection for the VM. The Bind and Password fields display. If Enable Display is selected:

    • Enter a display Password

    • Use the dropdown menu to change the default IP address in Bind if you want use a specific address to access the display using an external VNC client, 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.

      To edit bind address after VM creation (click to expand) Go to Virtualization > Virtual Machines and locate the VM you want to modify. Click anywhere on the VM entry on the Virtual Machines widget to expand it. Click Devices to open the devices screen associated with the VM. From this screen, click the more_vert icon at the right of the display device and select Edit to open the Edit Display Device screen. Use the Bind dropdown to select a new IP address.

    Click Next.

  2. Enter the CPU and memory settings for your VM.

CPU and Memory
Figure 2: CPU and Memory

If you selected Windows as the Guest Operating System, the Virtual CPUs field displays a default value of 2. The VM operating system might have operational or licensing restrictions on the number of CPUs.

Do not allocate too much memory to a VM. Activating a VM with all available memory allocated to it can slow the host system or prevent other VMs from starting.

Leave CPU Mode set to Custom if you want to select a CPU model.

Use Memory Size and Minimum Memory Size to specify how much RAM to dedicate to this VM. 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. Reviewing available memory from within the VM typically shows the Minimum Memory Size.

Click Next.

  1. Configure disk settings.
Disks
Figure 3: Disks

Select Create new disk image to create a new zvol on an existing dataset.
Select Use existing disk image to use an existing zvol for the VM.

Select either AHCI or VirtIO from the Select Disk Type dropdown list. We recommend using AHCI for Windows VMs.

Select the location for the new zvol from the Zvol Location dropdown list.

Enter a value in Size (Examples: 500KiB, 500M, and 2TB) to indicate the amount of space to allocate for the new zvol.

Click Next.

  1. Configure the network interface.
Network Interface
Figure 4: Network Interface

Select the network interface type from the Adapter Type dropdown list. Select Intel e82585 (e1000) as it offers a higher level of compatibility with most operating systems, or select VirtIO if the guest operating system supports para-virtualized network drivers.

Select the network interface card to use from the Attach NIC dropdown list.

Click Next.

  1. Upload installation media for the operating system you selected.
Installation Media
Figure 5: 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.

To upload an iso select Upload New Image File and either enter the path or browse to the location of the file.

Upload Installation Media
Figure 6: Upload Installation Media

Click Upload to begin the upload process. After the upload finishes, click Next.

  1. Specify a GPU.
GPU Screen
Figure 7: GPU Screen

The VirtIO network interface requires a guest OS that supports VirtIO para-virtualized network drivers.

iXsystems does not have a list of approved GPUs at this time but does have drivers and basic support for the list of nvidia Supported Products.
  1. Confirm your VM settings, then click Save.

Adding and Removing Devices

After creating the VM, you can add or remove virtual devices.

Expand the VM entry on the Virtual Machines screen and click Devices.

Devices
Figure 8: Devices

Device notes:

  • A virtual machine attempts to boot from devices according to the Device Order, starting with 1000, then ascending.
  • A CD-ROM device allow booting a VM from a CD-ROM image like an installation CD. The CD image must be available in the system storage.

See Adding and Managing VM Devices for more information.

Managing a Virtual Machine

After creating the VM and configuring devices for it, manage the VM by expanding the entry on the Virtual Machines screen.

VM Options
Figure 9: VM Options

An active VM displays options for Display and Serial Shell connections.

When a Display device is configured, remote clients can connect to VM display sessions using a SPICE client, or by installing a 3rd party remote desktop server inside your VM. SPICE clients are available from the SPICE Protocol site.

If the display connection screen appears distorted, try adjusting the display device resolution.

Use the State toggle or click Stop to follow a standard procedure to do a clean shutdown of the running VM. Click Power Off to halt and deactivate the VM, which is similar to unplugging a computer.

If the VM you created has no Guest OS installed, The VM State toggle and Stop button might not function as expected. The State toggle and Stop button send an ACPI power down command to the VM operating system, but since an OS is not installed, these commands time out. Use the Power Off button instead.

Installing an OS

When the VM is configured in TrueNAS and has an OS .iso, file attached, you can start the VM and begin installing the operating system.

Some operating systems can require specific settings to function properly in a virtual machine. For example, vanilla Debian can require advanced partitioning when installing the OS. Refer to the documentation for your chosen operating system for tips and configuration instructions.

Debian OS Example

Upload the Debian .iso to the TrueNAS system and attached to the VM as a CD-ROM device. This example uses Debian 12 and basic configuration recommendations. Modify settings as needed to suit your use case.

  1. Click Virtualization, then ADD to use the VM wizard. See table below for settings used in this example.
Wizard ScreenSettingDescription
Operating System:Guest Operating SystemLinux
NamedebianVM
DescriptionDebian VM
CPU and Memory:Memory Size1024 MiB
Disks:Create new disk imageSelected
Zvol LocationSelect pool.
Size30 GiB
Network Interface:Attach NICSelect the physical interface to associate with the VM.
Installation Media:Installation ISO is uploaded to local storage.
If the ISO is not uploaded, select Upload an installer image file.
Select a dataset to store the ISO, click Choose file, then click Upload. Wait for the upload to complete.
GPU:Leave the default values.
Confirm OptionsVerify the information is correct and then click Save.
  1. After creating the VM, start it. Expand the VM entry and click Start.

  2. Click Display to open a SPICE interface and see the Debian Graphical Installation screens.

  3. Press Enter to start the Debian Graphical Install.

    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 at this time.

    c. Enter a name in Hostname.

    d. Enter a Domain name

    e. Enter the root password and re-enter the root password.

    f. Enter a name in New User.

    g. Select the username for your account or accept the generated name.

    h. Enter and re-enter the password for the user account.

    j. Choose the time zone, Eastern in this case.

  4. Detect and partition disks.

    a. Select Guided - use entire disk to partition.

    b. Select the available disk.

    c. Select All files in one partition (recommended for new users).

    d. Select Finish partitioning and write changes to disk.

    e. Select Yes to Write the changes to disks?.

  5. Install the base system

    a. Select No to the question Scan extra installation media.

    b. Select Yes when asked Continue without a network mirror.

  6. Install software packages

    a. Select No when asked Participate in the package usage survey.

    b. Select Standard system utilities.

    c. Click Continue when the installation finishes.

    After the Debian installation finishes, close the display window.

  7. Remove the device or edit device order. In the expanded section for the VM, click Power Off to stop the new VM.

    a. Click Devices.

    b. Remove the CD-ROM device containing the install media or edit device order to boot from the Disk device.

    • 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. Change the CD-ROM Device Order to a value greater than that of the existing Disk device, such as 1005. Click Save.

  8. Return to the Virtual Machines screen and expand the new VM again.

  9. Click Start.

  10. Click Display.

What if the grub file does not run after starting the VM?

The grub file does not run when you start the VM, you can do this manually after each start. At the shell prompt:

  1. Type FS0: and press Enter.
  2. Type cd EFI and press Enter.
  3. Type cd Debian and press Enter.
  4. Type grubx64.efi and press Enter.

To ensure it starts automatically, you create the startup.nsh file at the root directory on the vm. To create the file:

  1. Go to the Shell.

  2. At the shell prompt type edit startup.nsh.

  3. In the editor type:

    a. Type FS0: and press Enter.

    b. Type cd EFI and press Enter.

    c. Type cd Debian and press Enter.

    d. Type grubx64.efi and press Enter.

    e. Use the Control+s keys (Command+s for Mac OS) then press Enter.

    f. Use the Control+q keys to quit.

  4. Close the display window

  5. To test if it now boots up on startup:

    a. Power off the VM.

    b. Click Start.

    c. Click Display.

    d. Log into your Debian VM.

Configuring Virtual Machine Network Access

Configure VM network settings during or after installation of the guest OS. To communicate with a VM from other parts of your local network, use the IP address configured or assigned by DHCP within the VM.

To confirm network connectivity, send a ping to and from the VM and other nodes on your local network.

Debian OS Example

Open a terminal in the Debian VM.

Enter ip addr and record the address.

Enter ping followed by the known IP or hostname of another client on the network, that is not your TrueNAS host. Confirm the ping is successful. To confirm internet access, you can also ping a known web server, such as ping google.com.

Log in to another client on the network and ping the IP address of your new VM. Confirm the ping is successful.

Accessing TrueNAS Storage From a VM

By default, VMs are unable to communicate directly with the host NAS. If you want to access your TrueNAS SCALE directories from a VM, for example to connect to a TrueNAS data share, you have multiple options.

If your system has more than one physical interface, you can assign your VMs to a NIC other than the primary one your TrueNAS server uses. This method makes communication more flexible, but does not offer the potential speed of a bridge.

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 for more information.