Installing HAOS (Home Assistant OS) in a VM

Apps and Virtualization
, ,
1

Install Home Assistant OS

Begin in the TrueNAS UI by adding a new ZVOL at least 32 GiB in size. Take note of the ZVOL path.

Z-Volume Details

Then, using the TrueNAS shell, run these commands to download, extract, and write the HAOS image for KVM to the ZVOL you created. In the 3rd command, replace tank/vm/haos with the path to your ZVOL. Notice the full ZVOL path should begin with /dev/zvol/

wget https://github.com/home-assistant/operating-system/releases/download/12.2/haos_ova-12.2.qcow2.xz
unxz haos_ova-12.2.qcow2.xz
qemu-img convert -O raw haos_ova-12.2.qcow2 /dev/zvol/tank/vm/haos

Create the Virtual Machine

In the TrueNAS UI, select Virtualization from the left-hand menu, then click the add button to begin the Virtual Machine Creation Wizard.

Step 1 - Set the guest operating system to Linux, give your VM a name, and ensure UEFI is the selected boot method.

Show Operating System

Step 1
Step 1460×935 24.1 KB

Step 2 - Assign 1 virtual CPU with at least 2 cores and a minimum of 2 GiB memory. Set the CPU mode to host passthrough.

Show CPU and Memory

Step2
Step2460×1055 32.5 KB

Step 3 - Click use existing disk image and set the disk type to VirtIO. Select your existing HAOS ZVOL.

Show Disks

Step 3
Step 3460×560 16.6 KB

Step 4 - Choose a NIC for your VM. Set the adapter type to VirtIO. If you are not using a bridge, enable Trust Guest Filters to allow multicast.

Show Network Interface

Step 4
Step 4460×660 18.1 KB

Step 5 - Nothing is needed here.

Show Installation Media

Step 5
Step 5460×620 17 KB

Step 6 - Defaults should be fine.

Show GPU

Step 6
Step 6460×670 16.5 KB

Step 7 - Confirm options and save.

Show Confirm Options

Step 7
Step 7460×820 28.5 KB

QEMU Guest Agent

A channel for the guest agent will be added to the VM automatically.

For more information about creating a VM, see the TrueNAS Scale documentation found HERE

For more information about installing Home Assistant OS in a VM, see the Home Assistant documentation found HERE

This guide is also posted in the Home Assistant forums and can be found HERE

6 Likes
2

Troubleshooting and Additional Information

:warning: Permission denied

The following errors (or similar) when trying to download, extract, or install HAOS using the TrueNAS shell are typically caused by insufficient user permissions.

haos_ova-9.5.qcow2.xz: Permission denied
Cannot write to ‘haos_ova-9.5.qcow2.xz’ (Permission denied).
unxz: haos_ova-9.5.qcow2: Permission denied
qemu-img: /dev/zvol/tank/vm/haos: error while converting raw: Protocol driver 'host_device' does not support image creation, and opening the image failed: Could not open '/dev/zvol/tank/vm/haos': Permission denied

You may need to run the commands as root or use sudo

sudo wget https://github.com/home-assistant/operating-system/releases/download/9.5/haos_ova-9.5.qcow2.xz
sudo unxz haos_ova-9.5.qcow2.xz
sudo qemu-img convert -O raw haos_ova-9.5.qcow2 /dev/zvol/tank/vm/haos

:warning: Cannot grow device files

This can happen when the ZVOL is not sized correctly.

qemu-img: /dev/zvol/tank/vm/haos: error while converting raw: Cannot grow device files

Confirm the size of your ZVOL is at least 32 GiB

image

:warning: VM is booting to the UEFI Interactive shell

image
image1158×683 3.03 KB

This happens if we use the incorrect path when writing the HAOS image to our zvol. Notice in the following command that the path starts with /dev/zvol

qemu-img convert -O raw haos_ova-11.5.qcow2 /dev/zvol/tank/vm/haos

If you’re still having trouble, please reply with the exact command you used for this step.

:information_source: Using the ConBee II Zigbee Controller

Unfortunately, the Conbee II is known to not work with USB Passthrough.

You still have a few options, though:

  1. Use PCIe passthrough to connect the USB controller to the VM.
  2. Use this script to start your VM. (this gets old fast)
  3. The final option is to get another Zigbee controller
3 Likes
3

Thanks, Troy. I’m a longtime FreeNAS user (since 9.10) and still on the fence on making the jump to SCALE myself.

I’ve used a very similar process to install and run HAOS in a bhyve VM on TrueNAS CORE. It’s been running great and updates are a breeze.

Any big benefits to running HASS on SCALE versus CORE? I’m running Wifi devices (mostly Shelly and custom ESPHome based devices) only, so I haven’t had to fiddle with USB passthrough et al.

From your post above, do I understand that SCALE is fussy with what Zigbee/Z-Wave controllers it supports?

4

Hi Michel,

None that I’m aware of.

The Conbee II is the only Zigbee controller I know that has issues with USB passthrough.

Also, series 5 Z-Wave controllers may be reset when starting Z-Wave JS, causing them to eject from the VM. Since SCALE does not support hot-plugging USB devices, they are basically useless. However, the Z-Wave JS developer has told me that series 7 and 8 controllers do not eject when reset, so they should work fine with USB passthrough.

Using PCIe passthrough for the USB controller rather than USB passthrough per device can avoid these issues altogether.

2 Likes
5

This is great information, thank you!

1 Like
6

I am using a ZWave Zooz ZST10 S2 and it certainly never ejects using USB passthrough into HAOS VM on Scale. I have quite a large variety of devices integrated via HA and no issues.

1 Like
7

Only series 5 controllers eject. The Zooz ZST10 S2 appears to be (according to Google) a series 7 controller, so it wouldn’t suffer from the ejection issue.

Technically, you can disable soft reset in the Z-Wave JS add-on to avoid the ejection issue with series 5 controllers, but that is considered a last resort and not recommended by Z-Wave JS developers.

1 Like