14. Virtual Machines — FreeNAS®11.1-U4 User Guide Table of Contents

# 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

Select `VMs → Add VM` for the Add VM dialog 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 Options
Setting | Value | Description
--- | --- | ---
VM Type | drop-down menu | type of VM, either Virtual Machine for a typical instance, or Docker VM for a special VM to run Docker
Name | string | a name to identify the VM
Description | string | a short description of the VM or its purpose
Virtual CPUs | integer | quantity of virtual CPUs allocated to the VM, up to 16; although these are virtual and not strictly related to host processor cores, the host CPU might limit the maximum number; the operating system used in the VM might also have operational or licensing restrictions on the number of CPUs allowed
Memory Size (MiB) | integer | megabytes of RAM allocated to the VM
Boot Method | drop-down menu | UEFI for newer operating systems, or UEFI-CSM (Compatibility Support Mode) for older operating systems that only understand BIOS booting
Autostart | checkbox | when checked, start the VM automatically on boot

## 14.2. Adding Devices to a VM

After creating the VM, click it to select it, then click Devices and Add Device to add virtual hardware to it:

Fig. 14.2.1 Add Devices to a VM

Select the name of the VM from the VM drop-down menu, then select the Type of device to add. These types are available:

- Network Interfaces
- Disk Devices
- Raw Files
- CD-ROMs
- VNC Interface

Figure 14.2.2 shows the fields that appear when Network Interface is the selected Type.

### 14.2.1. Network Interfaces

Fig. 14.2.2 VM Network Interface Device

The default Adapter Type emulates an Intel E1000 (82545) Ethernet card for compatibility with most operating systems. This can be changed to VirtIO to provide better performance when the operating system installed in the VM supports VirtIO paravirtualized network drivers.

If the system has multiple physical network interface cards, the Nic to attach drop-down menu can be used to specify which physical interface to associate with the VM.

By default, the VM receives an auto-generated random MAC address. To override the default with a custom value, enter the desired address into the MAC Address field.

### 14.2.2. Disk Devices

Zvols are typically used as virtual hard drives. After creating a zvol, associate it with the VM by selecting Add device, choose the VM, select a Type of Disk, select the created zvol, then set the Mode. If a specific sector size is required, enter the number of bytes into Disk sectorsize. The default of 0 leaves the sector size unset.

Fig. 14.2.3 VM Disk Device

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.3. 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, select Add device, choose the VM, select a Type of Raw File, browse to the image file, 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 sectorsize. The default of 0 leaves the sector size unset.

Fig. 14.2.4 VM Raw File Disk Device

### 14.2.4. 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.5 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.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 when VNC is the selected Type.

Fig. 14.2.6 VM VNC Device

The Resolution drop-down menu can be used to modify the default screen resolution used by the VNC session.

The VNC 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.

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

Check the Wait to boot checkbox to indicate that the VNC client should wait until the VM has booted before attempting the connection.

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, check the VNC Web checkbox.

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. 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 a list of configured VMs. Configuration and control buttons appear at the bottom of the screen when an individual VM is selected with a mouse click:

Fig. 14.3.1 VM Configuration and Control Buttons

The name, description, running state, VNC port (if present), and other configuration values are shown. Click on an individual VM for additional options.

Some standard buttons are shown for all VMs:

- Edit changes VM settings.
- Delete removes the VM.
- Devices is used to add and remove devices to this VM.

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

- Start starts the VM.
- Clone clones or copies the VM to a new VM. The new VM is given the same name as the original, with _cloneN appended.

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

- Stop shuts down the VM.
- Power off immediately halts the VM, equivalent to disconnecting the power on a physical computer.
- Restart restarts the VM.
- Vnc via Web starts a web VNC connection to the VM. The VM must have a VNC device, and VNC Web enabled in that device.

## 14.4. Deleting VMs

When a VM is no longer needed, it can be deleted by clicking on the VM, then clicking Delete at the bottom of the screen. A dialog will show any related devices that will also be deleted and ask 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 VM

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. Rancher VM Requirements

20 GiB of storage space is required for the Rancher VM. For setup, the SSH service must be enabled.

The Rancher VM requires 2 GiB of RAM while running.

### 14.5.2. Create the Rancher VM

Click VMs, then the Add VM button. Set the VM Type to Docker VM. Enter RancherUI for the name, Rancher UI VM for the Description, leave the number of Virtual CPUs at 1, and enter 2048 for the Memory Size. To have the Rancher VM start when the FreeNAS® system boots, check the Autostart checkbox. Click OK to create the virtual machine.

Fig. 14.5.1 Rancher VM Configuration

A location to store the disk image must now be chosen. In this example, a dataset called vm-storage has already been created as a location to store VM data. Click VMs, then click on the RancherUI line to select it. Click on the Devices button to show the devices attached to that VM. Click on the RAW device to select it, then click the Edit button. In the Raw File field, browse to the dataset and select it. Then add a filename by typing /rancherui.img at the end of the path in the text box.

Set the Disk boot checkbox, enter a password for the `rancher` user in the Password field, then enter 20G in the Disk size field. Click OK to save the device.

Fig. 14.5.2 Rancher Image Storage

### 14.5.3. Start the Rancher VM

Click VMs, then click on the RancherUI line to select it. Click the Start button and then Yes to start the VM.

The first time the Rancher 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 is started.

### 14.5.4. Installing the Rancher Server

Click VMs and locate the line for the RancherUI VM. The Info column shows the `Com Port` for the Rancher VM. In this example, `/dev/nmdm3B` 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 the setting of the service, 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 RancherUI Info column:

    cu -l /dev/nmdm3B

If the terminal does not show a `rancher login:` prompt, press `Enter`.

Enter rancher as the username, press `Enter`, then type the password that was entered when the raw file was created above and press `Enter` again. After logging in, a `[rancher@rancher ~]$` prompt is displayed.

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.