Installing HAOS in a VM on TrueNAS SCALE (Bluefin edition)

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.

zvol-path

Then using the TrueNAS shell, run these commands to download, extract, and write the HAOS image for KVM to the ZVOL you just created. Replace tank/vm/haos with your ZVOL path.

wget https://github.com/home-assistant/operating-system/releases/download/9.5/haos_ova-9.5.qcow2.xz
unxz haos_ova-9.5.qcow2.xz
qemu-img convert -O raw haos_ova-9.5.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. For now, uncheck the start on boot option and set the display type to SPICE.

Show Operating System

Step 2 - Assign your vCPUs 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 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 5 - Nothing is needed here.

Show Installation Media

Step 6 - Defaults should be fine.

Show GPU

Step 7 - Confirm options and save.

Show Confirm Options


Add the QEMU guest agent

TrueNAS does not currently have any method to add a channel for the guest agent, but we can still do it by using a script to start the VM. For this to function correctly, the VM should have its autostart disabled; this is key. To start the VM when TrueNAS boots, we can configure the script to run as Post Init. While not the most convenient approach, it is likely safer than patching the middleware code.

With help from this post by @boti, a script on Reddit, and later this Red Hat documentation, here is a startup script I wrote. It works fine to start the VM from the TrueNAS shell, but it took a few tries to get working during Post Init. Increasing the script timeout (in the Post Init settings) was the solution - I’m using 60 seconds.

Show Post Init settings

  1. Save the startup script to your NAS and make it executable
  2. Edit line 4 of the script, set the name of your HAOS VM
  3. Using the TrueNAS shell, run the script to start your VM

start-haos.sh

#!/bin/bash

## Set the name of your VM
vm='HomeAssistant'


if [ ${EUID} -ne 0 ]; then
  echo "Please run this script as root or using sudo."
  exit 1
fi

set -euo pipefail

# create a temporary XML file for the QEMU guest agent
guest_agent=$(mktemp -t agent.xml.XXXXX)
cat << END_XML > "${guest_agent}"
<channel type='unix'>
   <target type='virtio' name='org.qemu.guest_agent.0'/>
</channel>
END_XML

# get id and use it to start the VM
id=$(/usr/bin/midclt call vm.query | /usr/bin/jq -r '.[] | ( .id|tostring ) + ":" + .name' | /usr/bin/grep "${vm}" | /usr/bin/cut -f1 -d':')
/usr/bin/midclt call vm.start "${id}" &> /dev/null
sleep 1

# get the VM name and use it to attach the QEMU guest agent
name=$(/usr/bin/virsh -c "qemu+unix:///system?socket=/run/truenas_libvirt/libvirt-sock" list --name | /usr/bin/grep "${vm}")
/usr/bin/virsh -c "qemu+unix:///system?socket=/run/truenas_libvirt/libvirt-sock" attach-device "${name}" "${guest_agent}"

# remove the temporary XML file
rm "${guest_agent}"

:warning: If you encounter a similar error, try using a SPICE display instead of VNC.

error: Failed to attach device from /some/path/to/file
error: internal error: no virtio-serial controllers are available
Show more about this error

Digging around in the middleware code, I came across this and this

 if device.is_spice_type():
	 spice_server_available = True
    if spice_server_available:
        # We always add spicevmc channel device when a spice display device is available to allow users
        # to install guest agents for improved vm experience

It looks like they are only creating the virtio-serial controller when the VM uses a SPICE display :man_shrugging:


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

6 Likes

Happy New Year :confetti_ball:

reserved

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?

1 Like

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.

image

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.

1 Like

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.

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.

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

1 Like

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

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"
1 Like

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

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

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?

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

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.

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

1 Like

I filed a ticket with ix-systems about the quest agent - They’ve issued a patch that will be included in the next TrueNAS update, 22.12.1, expected to land mid-February. After that, the qemu guest agent should just work, with no intervention or scripts required. It will be completely automagic, with nothing to configure.

I got my SkyConnect and that works for me

1 Like

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.

:thinking: 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.