15. Virtual Machines — FreeNAS®11.2-RC1 User Guide Table of Contents

# 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 Virtual Machines 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 Virtual Machines 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  (Options) ‣ Devices on the VM card. Then click ➕ (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

Virtual Machines ‣  (Options) ‣ Devices is also used to edit or delete an existing device for a specific VM. Click  (Options) for a device to display Edit, Delete, Change Device Order, and Details.

### 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 Virtual Machines ‣  (Options) ‣ 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 Virtual Machines ‣  (Options) ‣ 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 Virtual Machines ‣  (Options) ‣ 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 Hosts 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 going to Virtual Machines ‣  (Options) ‣ Devices, and clicking  (Options) ‣ Edit for 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

Go to Virtual Machines to see a card for each installed VM. There are different view options at the top of the screen for this page:

- Cards: Default view. Shows a large “card” for each VM with all options for that VM contained on that card.
- Slim: Similar to the default, but reduces the size of the card to fit more cards on the screen.
- Table: Removes cards entirely to show all VMs in a space efficient table.

The default Cards view is described and shown in this section, but VM options are the same between each view. Each VM card has a CONNECT button at the bottom and will flip to show more options after clicking  (Options) and Edit.

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, Stop, 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. FreeNAS® will display a substantive error message if cloning a VM fails.

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

- ⏻ (Power) (Green) shuts down the VM.
- Stop also 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.
- Restart shuts down the VM and turns it back on.

Popups ask to confirm the choice when shutting down, powering off, or deleting a VM.

## 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 Hosts

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 within the Docker Host.

### 15.5.1. Docker Host Requirements

The system BIOS must have virtualization support enabled for a Docker Host 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 Host.

For setup, the SSH service must be enabled.

The Docker Host requires 2 GiB of RAM while running.

### 15.5.2. Creating Docker Host

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

Fig. 15.5.1 Add Docker Host

Docker Host configuration options are described in Table 15.5.1.

Table 15.5.1 Docker Host 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 | string | Enter a descriptive name for the Docker Host.
2 | Start on Boot | checkbox | Set to start this Docker Host when the FreeNAS® system boots.
3 | Virtual CPUs | integer | Enter the number of virtual CPUs to allocate to the Docker Host. 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 Host. A minimum 2048 MiB of RAM is required.
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. Default leaves 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 Host. Click SUBMIT to create the Host or BACK to change any settings. Click CANCEL at any time to return to the Virtual Machines page.

Fig. 15.5.2 Docker Host Configuration

Click ⏻ (Power), CONNECT, and Serial to log in to the Docker Host. Enter `rancher` for the user name and `docker` for the password.

The default password is changed in the Devices by stopping the Docker Host, clicking  (Options), and Devices. Click  (Options) and Edit for the RAW device and enter a new value in the password field. Passwords cannot contain a space.

Fig. 15.5.3 Edit Rancher Password in Raw File Device

### 15.5.3. Start the Docker Host

Go to Virtual Machines, then click on the red ⏻ (Power) button of the Docker Host to start it.

Starting a Docker Host can take some time. Connecting to the Serial Shell is possible during the startup process to view the activity of the Docker Host. When a message about `RancherOS` starting appears and the shell stops posting new messages, press `Enter` to see the `ClientHost login:` text and continue to log in.

### 15.5.4. SSH into the Docker Host

It is possible to SSH into a running Docker Host. Go to the Virtual Machines page and find the card for the Docker Host. The card shows the Com Port for the Docker Host. In this example, `/dev/nmdm12B` is used.

Use an SSH client to connect to the FreeNAS® server. Remember this also requires the SSH service to be running. Depending on the FreeNAS® system configuration, it might also require changes to the SSH service settings, like setting Login as Root with Password.

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

    cu -l /dev/nmdm12B -s 9600

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

### 15.5.5. Installing and Configuring the Rancher Server

Go to Virtual Machines and locate the card for the Docker Host. Start the Host and click Connect and Serial to open the Host Serial shell.

Continuing to set up the Rancher Host is done from the command line. Enter rancher as the username, press `Enter`, then enter either the default password docker or the custom password created by editing the raw file. Press `Enter` again. After logging in, a `[rancher@ClientHost ~]$` 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, ensure the radial This site’s address button is set, and click Save. Follow the instructions that now display and run the sudo docker run --rm --privileged -v command in the Docker Host Serial shell. After the command runs a message displays `Launched Rancher Agent:`. Refresh or go to the Hosts page of the Rancher web interface to confirm the Docker Host displays in the web interface. Rancher is now configured and ready for use.

For more information on using RancherOS, see the RancherOS Documentation.