14. 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.

14.1. Creating VMs¶

Navigate to VMs, and click ＋ (Add/Create) to open the Wizard shown in Figure 14.1.1:

Fig. 14.1.1 Add VM

VM configuration options are described in Table 14.1.1.

Table 14.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.
2	VM Name	string	Enter an alphanumeric name to identify the VM.
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.

For example, a user is creating a FreeBSD VM. They click ＋ (Add/Create) on the VMs page and progress through the steps of the Wizard:

Wizard type is set to Virtual Machine.
Guest Operating System is set to FreeBSD. freebsd-test is entered as the Name. The other options are left at their defaults.
Virtual CPUs and Memory Size are left at their default values.
Create new disk image is selected. The zvol size is set to 50. The user clicks Browse and stores the new disk image in the tank pool.
All networking settings are left at their default values.
The user sets Upload an installer image file and clicks Browse to set the save location for the iso file. Now the user uploads an iso by clicking Browse under ISO upload location, choosing a local FreeBSD iso file, and clicking Upload. FreeNAS^® starts the upload and populates the Choose installation media image field when finished.
After verifying the VM Summary is correct, the user clicks Submit.

Figure 14.1.2 shows the confirmation step and basic settings for the FreeBSD VM freebsd-test:

Fig. 14.1.2 Creating freebsd-test

14.2. Adding Devices to a VM¶

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

Fig. 14.2.1 VM Devices Page

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

CD-ROMs
NIC (Network Interfaces)
Disk Devices
Raw Files
VNC Interface

Note

Docker VMs are not compatible with VNC connections and cannot create a VNC Interface.

This menu is also used to Edit an existing device. Click ⫶ (Options) for an existing device shown in the table to see options to Edit or Delete that device. Editing an existing VM device offers the same options as creating the device.

14.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. 14.2.2 VM 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.

14.2.2. NIC (Network Interfaces)¶

Figure 14.2.3 shows the fields that appear after navigating VMs ‣ Devices, clicking ＋ (Add/Create), and selecting NIC as the Type.

Fig. 14.2.3 VM 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 another 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.

14.2.3. Disk Devices¶

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

Fig. 14.2.4 VM Disk Device

Browse to the created ZVol, then set the 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 into Disk sector size. The default of 0 leaves the sector size unset.

14.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, navigate VMs ‣ Devices, click ＋ (Add/Create), and select Raw File as the Type.

Fig. 14.2.5 VM Raw File Disk Device

Browse to the image file, then set the Disk sector size. If a specific sector size is required, enter the number of bytes into Disk sector size. The default of 0 leaves the sector size unset.

Now set the 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.

14.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.

Figure 14.2.6 shows the fields that appear after navigating VMs ‣ Devices, clicking ＋ (Add/Create), and selecting VNC as the Type.

Fig. 14.2.6 VM 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.

14.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 -s 9600 -l /dev/nmdm1B

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

14.3. Running VMs¶

Select VMs to see cards of installed VMs. There are options to Connect, view Devices, and Edit the VM across the bottom of the card.

Fig. 14.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, and Delete options.

Tip

The VMs page view can switch between the Cards and a Table view. VM options are the same in each view.

Some standard 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. This includes the option to Clone a VM. This copies the VM to a new VM. The new VM is given the same name as the original, with _cloneN appended, 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, equivalent to disconnecting the power on a physical computer.
Connect displays options to connect to the VM with either VNC or the Serial shell. For VNC, the VM must have a VNC device with Web Interface enabled.

14.4. Deleting VMs¶

A VM is deleted by clicking ⫶ (Options) on the desired VM card, then Delete. A dialog will prompt 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.

14.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 GUI tool for managing Docker containers.

FreeNAS^® runs the Rancher GUI as a separate VM.

14.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.

14.5.2. Creating Docker VMs¶

Figure 14.5.1 shows the Wizard that appears after navigating VMs ‣ Devices, clicking ＋ (Add/Create), and selecting Docker Host as the Virtual Machine (VM) Wizard type.

Fig. 14.5.1 Add DockerVM

Docker VM configuration options are described in Table 14.5.1.

Table 14.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 mebibytes 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 gibibytes (GiB) for the new RAW file.
5	RAW file location	browse button	Browse to an existing directory to store the new RAW file.
5	Disk sector size	integer	Define the disk sectorsize in bytes. Enter 0 to leave the sector size unset.

Choose the base options for the VM at each step of the wizard. Make sure Virtual CPUs is set to 1 and Memory Size is a minimum of 2048.

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, size, and store a raw file. Add a filename by typing an .img name in the RAW filename field. Enter a number of bytes for the RAW file size and set the Disk sector size, also in bytes. Set the raw file save location using Browse with the RAW File location 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:

_images/vms-add-wizard-docker-summary.png

Fig. 14.5.2 Docker VM Configuration

Every Docker VM is created with an initial user rancher with the password docker. This is used to log into 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. 14.5.3 Edit Rancher Raw File

14.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.

14.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/nmdm3B with the value from the Docker VM Com Port:

cu -l /dev/nmdm12B

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 GUI 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 GUI, 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.