15. Virtual Machines

A Virtual Machine (VM) is an environment on a host computer that can be used as if it were a separate physical computer. VMs can be used to run multiple operating systems simultaneously on a single computer. Operating systems running inside a VM see emulated virtual hardware rather than the actual hardware of the host computer. This provides more isolation than Jails, although there is additional overhead. A portion of system RAM is assigned to each VM, and each VM uses a zvol for storage. While a VM is running, these resources are not available to the host computer or other VMs.

FreeNAS^® VMs use the bhyve(8) virtual machine software. This type of virtualization requires an Intel processor with Extended Page Tables (EPT) or an AMD processor with Rapid Virtualization Indexing (RVI) or Nested Page Tables (NPT).

To verify that an Intel processor has the required features, use Shell to run grep VT-x /var/run/dmesg.boot. If the EPT and UG features are shown, this processor can be used with bhyve.

To verify that an AMD processor has the required features, use Shell to run grep POPCNT /var/run/dmesg.boot. If the output shows the POPCNT feature, this processor can be used with bhyve.

Note

By default, new VMs have the bhyve(8) -H option is set. This causes the virtual CPU thread to yield when a HLT instruction is detected, and prevents idle VMs from consuming all of the host’s CPU.

Note

AMD K10 “Kuma” processors include POPCNT but do not support NRIPS, which is required for use with bhyve. Production of these processors ceased in 2012 or 2013.

15.1. Creating VMs

Click on VMs and + (Add/Create) to open the wizard shown in Figure 15.1.1:

Fig. 15.1.1 Add VM

Virtual machine configuration options are described in Table 15.1.1.

Table 15.1.1 VM Wizard Options

Screen #	Setting	Value	Description
1	Virtual Machine (VM) Wizard type	drop-down menu	Choose to create either a standard VM or a Docker Host.
2	Guest Operating System	drop-down menu	Choose the VM operating system type. Choices are: Windows, Linux, or FreeBSD. See this guide for detailed instructions about using a different guest OS.
2	VM Name	string	Enter an alphanumeric name to identify the VM. An error occurs if another VM is already using the same name.
2	Boot Method	drop-down menu	Select UEFI for newer operating systems, or UEFI-CSM for (Compatibility Support Mode) older operating systems that only understand BIOS booting.
2	Start on Boot	checkbox	Set to start the VM when the system boots.
2	Enable VNC	checkbox	Set to to activate a Virtual Network Computing (VNC) remote connection. Requires UEFI booting.
3	Virtual CPUs	integer	Select the number of virtual CPUs to allocate to the VM. The maximum is 16 unless the host CPU limits the maximum. The VM operating system might also have operational or licensing restrictions on the number of CPUs.
3	Memory Size (MiB)	integer	Allocate the amount of RAM in mebibytes for the VM.
4	Disk image	check option with custom fields	Select Create new disk image to create a new zvol on an existing dataset. This is used as a virtual hard drive for the VM. Select Use existing disk image to Browse to an existing zvol or file for the VM.
4	Zvol size (GiB)	integer	Allocate the amount of storage in gibibytes for the new zvol. Only appears if Create new disk image is selected.
4	Select datastore	drop-down menu	Choose a datastore for the new zvol.
5	Adapter Type	drop-down menu	Intel e82545 (e1000) emulates the same Intel Ethernet card. This provides compatibility with most operating systems. VirtIO provides better performance when the operating system installed in the VM supports VirtIO paravirtualized network drivers.
5	MAC Address	string	Enter the desired MAC address to override the auto-generated randomized MAC address.
5	Attach NIC	drop-down menu	Select the physical interface to associate with the VM.
6	Choose an installation media	browse button	Browse to the operating system installation media.
6	Upload an ISO?	checkbox and buttons	Set to display image upload options.

The final screen of the Wizard displays the chosen options for the new VM. Click SUBMIT to create the VM or BACK to change any settings.

This example creates a FreeBSD VM. + (Add/Create) is clicked on the VMs page to start the VM wizard.

1. Wizard type is set to Virtual Machine (VM).
2. Guest Operating System is set to FreeBSD. Name is set to samplevm. Other options are left at default values.
3. Virtual CPUs is set to 2 and Memory Size is set to 2048 MiB.
4. Create new disk image is selected. The zvol size is set to 20 GiB and stored on the pool1 pool.
5. Network settings are left at default values.
6. A FreeBSD ISO installation image has been selected and uploaded to the FreeNAS^® system. The Choose installation media image field is populated when the upload completes.
7. After verifying the VM Summary is correct, SUBMIT is clicked.

Figure 15.1.2 shows the confirmation step and basic settings for the new virtual machine:

Fig. 15.1.2 Creating a Sample Virtual Machine

15.2. Adding Devices to a VM

To add a device to a VM, click Devices on the new VM card, and + (Add/Create).

Fig. 15.2.1 VM Devices

Select the new device from the Type field. These devices are available:

• CD-ROM
• NIC (Network Interface Card)
• Disk Device
• Raw File
• VNC Interface

This menu is also used to edit or delete an existing device. Click ⋮ (Options) for a device to display Edit and Delete options.

15.2.1. CD-ROM Devices

Adding a CD-ROM device makes it possible to boot the VM from a CD-ROM image, typically an installation CD. The image must be present on an accessible portion of the FreeNAS^® storage. In this example, a FreeBSD installation image is shown:

Fig. 15.2.2 CD-ROM Device

Note

VMs from other virtual machine systems can be recreated for use in FreeNAS^®. Back up the original VM, then create a new FreeNAS^® VM with virtual hardware as close as possible to the original VM. Binary-copy the disk image data into the zvol created for the FreeNAS^® VM with a tool that operates at the level of disk blocks, like dd(1). For some VM systems, it is best to back up data, install the operating system from scratch in a new FreeNAS^® VM, and restore the data into the new VM.

15.2.2. NIC (Network Interfaces)

Figure 15.2.3 shows the fields that appear after going to VMs ‣ Devices, clicking + (Add/Create), and selecting NIC as the Type.

Fig. 15.2.3 Network Interface Device

The Adapter Type can emulate an Intel e82545 (e1000) Ethernet card for compatibility with most operating systems. VirtIO can provide better performance when the operating system installed in the VM supports VirtIO paravirtualized network drivers.

By default, the VM receives an auto-generated random MAC address. To override the default with a custom value, enter the desired address in MAC Address. Click GENERATE MAC ADDRESS to automatically populate MAC Address with a new randomized MAC address.

If the system has multiple physical network interface cards, use the NIC to attach drop-down menu to specify which physical interface to associate with the VM.

Set a Device Order number to determine the boot order of this device. A lower number means a higher boot priority.

15.2.3. Disk Devices

Zvols are typically used as virtual hard drives. After creating a zvol, associate it with the VM by clicking VMs ‣ Devices, clicking + (Add/Create), and selecting Disk as the Type.

Fig. 15.2.4 Disk Device

Open the drop-down menu to select a created Zvol, then set the disk Mode:

• AHCI emulates an AHCI hard disk for best software compatibility.
• VirtIO uses paravirtualized drivers and can provide better performance, but requires the operating system installed in the VM to support VirtIO disk devices.

If a specific sector size is required, enter the number of bytes in Disk sector size. The default of 0 uses an autotune script to determine the best sector size for the zvol.

Set a Device Order number to determine the boot order of this device. A lower number means a higher boot priority.

15.2.4. Raw Files

Raw Files are similar to Zvol disk devices, but the disk image comes from a file. These are typically used with existing read-only binary images of drives, like an installer disk image file meant to be copied onto a USB stick.

After obtaining and copying the image file to the FreeNAS^® system, click VMs ‣ Devices, click + (Add/Create), then set the Type to Raw File.

Fig. 15.2.5 Raw File Disk Device

Browse to select the image file. If a specific sector size is required, enter the number of bytes in Disk sector size. The default value of 0 uses an autotuner to find and set the best sector size for the file.

Setting the disk Mode to AHCI emulates an AHCI hard disk for best software compatibility. VirtIO uses paravirtualized drivers and can provide better performance, but requires the operating system installed in the VM to support VirtIO disk devices.

Set a Device Order number to determine the boot order of this device. A lower number means a higher boot priority.

15.2.5. VNC Interface

VMs set to UEFI booting are also given a VNC (Virtual Network Computing) remote connection. A standard VNC client can connect to the VM to provide screen output and keyboard and mouse input.

Note

Each VM can only have a single VNC device. An existing VNC interface can be changed by clicking ⋮ (Options) and Edit.

Note

Docker VMs are not compatible with VNC connections and cannot have a VNC interface.

Note

Using a non-US keyboard via VNC is not yet supported. As a workaround, select the US keymap on the system running the VNC client, then configure the operating system running in the VM to use a keymap that matches the physical keyboard. This will enable passthrough of all keys regardless of the keyboard layout.

Figure 15.2.6 shows the fields that appear after navigating to VMs ‣ Devices, clicking + (Add/Create), and setting Type to VNC.

Fig. 15.2.6 VNC Device

The Port can be set to 0, left empty for FreeNAS^® to assign a port when the VM is started, or set to a fixed, preferred port number.

Set Wait to boot to force the VNC client to wait until the VM has booted before attempting the connection.

Use the Resolution drop-down menu to choose the default screen resolution used by the VNC session.

Select the IP address for VNC to listen on with the Bind drop-down menu.

To automatically pass the VNC password, enter it into the Password field. Note that the password is limited to 8 characters.

To use the VNC web interface, set Web Interface.

Tip

If a RealVNC 5.X Client shows the error RFB protocol error: invalid message type, disable the Adapt to network speed option and move the slider to Best quality. On later versions of RealVNC, select File ‣ Preferences, click Expert, ProtocolVersion, then select 4.1 from the drop-down menu.

Set a Device Order number to determine the boot order of this device. A lower number means a higher boot priority.

15.2.6. Virtual Serial Ports

VMs automatically include a virtual serial port.

• /dev/nmdm1B is assigned to the first VM
• /dev/nmdm2B is assigned to the second VM

And so on. These virtual serial ports allow connecting to the VM console from the Shell.

Tip

The nmdm device is dynamically created. The actual nmdm name can differ on each system.

To connect to the first VM:

cu -l /dev/nmdm1B -s 9600

See cu(1) for more information on using cu.

15.3. Running VMs

Click VMs to see a card for each installed VM. There are options to switch the default view on this screen to Slim or Table. Each card has a CONNECT button at the bottom.

Fig. 15.3.1 VM Cards

The name, description, running state, com port (if present), and other configuration values are shown on the card. Click ⋮ (Options) for the Start, Power Off, Delete, Devices, and Edit options.

Tip

The web interface shows an error message if a VM fails to start.

Some buttons are available for all VMs:

• Delete removes the VM.
• Devices is used to add, remove, and edit the VM devices.

When a VM is not running, these buttons are available:

• ⏻ (Power) (Red) starts the VM.
• Edit changes VM settings, and includes an option to Clone an existing VM. Cloning makes a copy of the VM. The new clone has _cloneN added to the name, where N is the number of the clone.

When a VM is already running, these buttons are available:

• ⏻ (Power) (Green) shuts down the VM.
• Power off immediately halts the VM. This is equivalent to disconnecting the power to a physical computer.
• CONNECT displays options to connect to the VM. This can include VNC, a Serial shell, or other options. For VNC, the VM must have a VNC device with Web Interface enabled.

15.4. Deleting VMs

A VM is deleted by clicking ⋮ (Options) on the desired VM card, then Delete. A dialog prompts for confirmation.

Tip

Zvols used in disk devices and image files used in raw file devices are not removed when a VM is deleted. These resources can be removed manually after it is determined that the data in them has been backed up or is no longer needed.

15.5. Docker/Rancher VMs

Docker is open source software for automating application deployment inside containers. A container provides a complete filesystem, runtime, system tools, and system libraries, so applications always see the same environment.

Rancher is a web interface tool for managing Docker containers.

FreeNAS^® runs the Rancher web interface as a separate VM.

15.5.1. Docker VM Requirements

The system BIOS must have virtualization support enabled for a Docker VM to run properly after installation. On Intel systems this is typically an option called VT-x. AMD systems generally have an SVM option.

20 GiB of storage space is required for the Docker VM.

For setup, the SSH service must be enabled.

The Docker VM requires 2 GiB of RAM while running.

15.5.2. Creating Docker VMs

Figure 15.5.1 shows the Wizard that appears after going to VMs, clicking + (Add/Create), and selecting Docker Host as the Virtual Machine (VM) Wizard type.

Fig. 15.5.1 Add DockerVM

Docker VM configuration options are described in Table 15.5.1.

Table 15.5.1 Docker VM Options

Screen #	Setting	Value	Description
1	Virtual Machine (VM) Wizard type	drop-down menu	Choose to create either a standard VM or a Docker Host.
2	Name of the VM	string	Enter a descriptive name for the Docker VM.
2	Start on Boot	checkbox	Set to start this VM when the FreeNAS® system boots.
3	Virtual CPUs	integer	Enter the number of virtual CPUs to allocate to the Docker VM. The maximum is 16 unless the host CPU also limits the maximum. The VM operating system can also have operational or licensing restrictions on the number of CPUs.
3	Memory Size (MiB)	integer	Allocate the amount of RAM in MiB for the Docker VM.
4	Adapter Type	drop-down menu	Intel e82545 (e1000) emulates the same Intel Ethernet card. This provides compatibility with most operating systems. VirtIO provides better performance when the operating system installed in the VM supports VirtIO paravirtualized network drivers.
4	MAC Address	string	Enter the desired MAC address to override the auto-generated randomized MAC address.
4	Attach NIC	drop-down menu	Select the physical interface to associate with the VM.
5	Raw filename	string	Enter a name for the new raw file.
5	Raw file size	integer	Allocate storage size in GiB for the new raw file.
5	Raw file location	browse button	Select a directory to store the new raw file.
5	Disk sector size	integer	Define the disk sector size in bytes. Enter 0 to leave the sector size unset.

Choose the base options for the VM at each step of the wizard. Virtual CPUs is set to 1. Memory Size must be set to at least 2048 MiB.

The Network Interface step is automatically populated with system defaults. Customize these fields as necessary and press NEXT to continue.

The Storage Files section of the wizard contains options to create and store a raw file. Add a filename by typing an .img name in the Raw filename field. Enter a number of gigabytes for the Raw file size. Set the raw file location with the folder button or by typing a directory in the field.

The final screen of the Wizard displays the chosen options for the new Docker VM. Click SUBMIT to create the VM or BACK to change any settings:

Fig. 15.5.2 Docker VM Configuration

Every Docker VM is created with an initial user rancher with the password docker. This is used to log in to RancherOS when connecting with the Serial shell. The password docker is changed by editing the raw device of the Docker VM. Passwords cannot contain a space.

Fig. 15.5.3 Edit Rancher Password in Raw File Device

15.5.3. Start the Docker VM

Click VMs, then click on the red ⏻ (Power) button to start the VM.

The first time the Docker VM is started, it downloads the Rancher disk image file. How long this takes to complete depends on the speed of the network connection. A status dialog reports the progress of the download.

After the image is downloaded, the VM starts.

15.5.4. Installing the Rancher Server

Click VMs and locate the card for the Docker VM. The Description shows the Com Port for the Docker VM. In this example, /dev/nmdm12B is used.

Further setup of the Rancher VM is done from the command line. Use an SSH client to connect to the FreeNAS^® server. Remember that this requires the SSH service to be running. Depending on local configuration, it might also require changes to service settings, like allowing root user login with a password.

At the FreeNAS^® console prompt, connect to the Rancher VM with cu, replacing /dev/nmdm12B with the value from the Docker VM Com Port:

cu -l /dev/nmdm12B -s 9600

If the terminal does not show a rancher login: prompt, press Enter. The Docker VM can take some time to start and display the login prompt.

Enter rancher as the username, press Enter, then enter either the default password docker or a custom password created by editing the raw file. Press Enter again. After logging in, a [rancher@rancher ~]$ prompt is displayed.

Ensure Rancher has functional networking and can ping an outside website. Adjust the VM Network Interface and reboot the VM if necessary.

Download and install the Rancher system with this command:

sudo docker run -d --restart=unless-stopped -p 8080:8080 rancher/server

Note

If the error Cannot connect to the Docker daemon is shown, run sudo dockerd. Then give the sudo docker run command above again.

Installation time varies with processor and network connection speed, but typically takes a few minutes. After the process finishes and a command prompt is shown, type this command:

ifconfig eth0 | grep 'inet addr'

The first value is the IP address of the Rancher server. Enter the IP address and port 8080 as the URL in a web browser. For example, if the IP address was 10.231.3.208, enter 10.231.3.208:8080 as the URL in the web browser.

The Rancher server takes a few minutes to start. The web browser might show a connection error while the Rancher web interface is still starting. If the browser shows a connection has timed out or a similar error, wait one minute and try again.

In the Rancher web interface, click Add a host and enter the same IP address and port number. Click Save to save the information.

For more information on using Rancher, see the Rancher Quick Start Guide.