Installing HAOS in a VM on TrueNAS SCALE

troy · January 2, 2023, 3:00am

Install Home Assistant OS

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

zvol-path

Then, using the TrueNAS shell, run these commands to (1) download, (2) extract, and (3) 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/13.2/haos_ova-13.2.qcow2.xz
unxz haos_ova-13.2.qcow2.xz
qemu-img convert -O raw haos_ova-13.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 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

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

Show Disks

Step 3

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 5 - Nothing is needed here.

Show Installation Media

Step 5

Step 6 - Defaults should be fine.

Show GPU

Step 6

Step 7 - Confirm options and save.

Show Confirm Options

Step 7

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 NEW TrueNAS Discourse forum and can be found HERE

troy · January 2, 2023, 3:09am

Troubleshooting and Additional Information

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

Cannot grow device files

This can happen when the ZVOL does not get 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

VM is booting to the UEFI Interactive shell

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.

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:

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

Tromperie · January 8, 2023, 2:06am

Happy new year to you.
Will this method use an IP address from the LAN DHCP server, that is, if the IP range is 192.168.0.0/24, will it use an address in it?

Is there USB pass through?

troy · January 8, 2023, 2:28am

Yea, unless you configure something differently the VM will have its own IP in the same network range as your TrueNAS. In Home Assistant, you can configure if it’s a static IP or uses DHCP (default)

Yep - I’m using it with a Gen 5 Z-Stick with the Z-Wave JS UI addon

Here’s how I added it to my VM

And in the addon, I used the /dev/serial/by-id/usb... path that’s typically recommended.

oblivioncth · January 9, 2023, 5:49am

Just wanted to chime in that I migrated my HAOS install from ESXi to TrueNAS SCALE successfully by following this guide, including USB passthrough of a Z-Wave/Zigbee coordinator.

Thanks.

I opted for patching the middleware to handle the QEMU Guest Agent, which seems to have worked well as the machine does respond to the shutdown command.

LaUr3nTiU · January 15, 2023, 2:53am

Any particular reason for adding the QEMU Guest Agent?

I’m currently experimenting as I’d like to switch to TrueNAS from RPi4 in a few weeks and not sure why the QEMU Guest Agent is required.

I was able to boot up HA. Do we need it for shutdown, or why?

Edit: I issued Stop and it managed to shutdown.

troy · January 15, 2023, 1:23pm

It’s what the official Home Assistant documentation tells you to do. I’ve tried asking a few times on Discord but never got a reply to precisely what the guest agent does for HAOS.

That was my assumption. If your VM runs and shuts down to your satisfaction, you may skip adding the guest agent. Some other users have not been so lucky.

My VM also shuts down without the guest agent, but I added it anyways because I want everything to work as best as possible.

Kazador · January 15, 2023, 6:46pm

Hello and thank you for the tutorial. I confirm that I also did not need to add the QEMU Guest Agent, the machine starts well when starting truenas scale, and responds to the commands to start and stop the vm.

To understand I directly asked the question to GPT chat “why the QEMU guest agent is necessary for home assistant os?”

And here is his answer: The QEMU guest agent is needed for Home Assistant OS because it allows using virtual devices in a guest OS (like Home Assistant) that does not support them natively. QEMU acts as an emulator that translates virtual device instructions to make them compatible with the guest operating system, so attached devices can be used as if they were connected directly to the host.

Il est possible que vous n’ayez pas besoin de l’agent invité QEMU si vous n’utilisez pas de périphériques qui nécessitent une émulation, ou si vous utilisez un système d’exploitation qui prend en charge ces périphériques nativement. Cependant, pour certaines personnes, l’utilisation de QEMU peut être nécessaire pour connecter des périphériques spécifiques à leur système Home Assistant, comme des cartes réseau, des périphériques USB, des disques durs virtuels, etc. Il est donc nécessaire pour certains utilisateurs pour utiliser certains périphériques qui nécessite une émulation pour fonctionner avec Home Assistant OS.

So that was what I originally understood. Normally we do not need Qemu in this specific case of construction

Chris2fourlaw · January 17, 2023, 5:45am

I’m having trouble getting USB passthrough working with ConBee II.

I came across this message: VM for Home Assistant OS needs multicast | TrueNAS Community

But it doesn’t seem to work for me. I can confirm that it looks like Scale is grabbing it, because /dev/ttyACM0 exists there

Cretezy · January 18, 2023, 8:18pm

I’m also having issues with the ConBee II USB.

Also, the linked message has a typo. The correct command is:

system advanced update kernel_extra_options="module_blacklist=cp210x"

Chris2fourlaw · January 18, 2023, 11:57pm

Yeah, I noticed their follow up and fixed the typo. I have an AMD Ryzen if that’s meaningful

kzelnick · January 26, 2023, 1:56am

up and running had to use sudo with the commands above not sure why but it worked
one problem
my addons are not running
node red
and a few others any advice

metatroneoz · February 1, 2023, 6:16am

Hi, i’m very new to all of this, so excuse my rookie question.
I’m stuck on the first step to dl HAOS… I’m getting this error when I use the code in the shell:

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.xz: No such file or directory
qemu-img: Could not open ‘haos_ova-9.5.qcow2’: Could not open ‘haos_ova-9.5.qcow2’: No such file or directory

Any idea of what I’m doing wrong?

troy · February 1, 2023, 12:18pm

Hi @metatroneoz

Are you logged into the shell as root or another user?

If the first command to dl does not work, none of the remaining commands will work either

Seems like a permissions issue. Try adding sudo to the beginning of each command like this

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

troy · February 1, 2023, 12:30pm

Hi @kzelnick

Sorry I missed your post.

My fault, I need to update the guide to mention that commands may need to be run as root or use sudo. Not every case is the same. It depends on your setup and how you’re accessing the TrueNAS shell.

Were you able to get your add-ons working?

If your still having issues, mind listing all the trouble add-ons. I don’t know how much I can help but I can at least install them to see if I can reproduce the issue.

kzelnick · February 1, 2023, 10:45pm

I did not sure why but a second reboot and they all came up
Works great thanks

Did not do the qemu agent script looked above my paygrade and working without it

Thanks again

Ken

Chris2fourlaw · February 2, 2023, 12:24am

I got my SkyConnect and that works for me

metatroneoz · February 2, 2023, 5:42am

Hi @troy

Perfect it worked with Sudo. Got HA to run.
I’m having another issue which I can’t seem to figure out. After a few minutes Home assistant loses connection and crashes. I can’t restart it and I have to restart the VM to run it again. There’s no error message that I can see. Would you have any idea why this is happening? (I didn’t set up the qemu agent).

Thank you for your help.

troy · February 2, 2023, 10:29pm

I’m not sure @metatroneoz. But I dought this is related to not having the qemu guest agent.

When you’re in TrueNAS, does the DISPLAY button work? Maybe you can find some clues there. For example, is Home Assistant crashing but the supervisor still running, or is it the entire VM that crashes?

From this same page, have you tried downloading the logs?

I’m just making some guesses here. When you log into your TrueNAS UI, are you logging in as root or another user? If it’s another user, try adding them to the root group. I don’t know if it will help, but I’ve seen there is a known issue that has some effect on Apps and VMs when you’re not logged in as root.

I’m sorry I can’t be more helpful - Maybe someone else can jump in with tips for better troubleshooting.

metatroneoz · February 3, 2023, 2:02am

Hi @troy thank you for your help, you are being very kind to try figure out my issues.
So here’s the interesting finding: HA works on the app on my phone (local) all the time, no crashing.
I can’t get to the HA ui in my browser. So there’s nothing wrong from the VM side of things and HA is running stable and fine by the look of it while I’m using the app. I’ve also tested on my laptop and it appears to be working fine there too.
I wonder if it’s an issue with my computer being connected by wifi and some strange local access issue. I don’t know why I can’t access from my iMac. I’ll try some stuff with the cache and other things, hopefully i could fix it.