Installing HAOS (Home Assistant OS) in a VM

troy · April 2, 2024, 12:49am

Install Home Assistant OS

Begin in the TrueNAS UI by selecting Datasets from the left-hand menu. Next, choose a location within your datasets where you want to place your VM (Virtual Machine). Click Add Zvol to create a new Zvol at least 32 GiB in size.

Show Create Zvol

create_zvol

Next. check the Zvol Details to take note of the Path. Please also confirm that the Volume Size was set correctly, and is at least 32 GiB in size.

Show Zvol Details

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 path should begin with /dev/zvol/ - If you are using the shell as the root user, you should omit sudo from the command.

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

Create the Virtual Machine

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

Show Create Virtual Machine

create_vm_with_bridge

1 - Operating System - Set the guest operating system to Linux and give your VM a name. Ensure UEFI is the selected boot method. You should also set a password for the Spice display. Optionally, add a description and change the system clock to UTC.

Show Operating System

2 - CPU and Memory - Assign one virtual CPU with at least two cores. Change the CPU mode to host passthrough, and set the memory size to a minimum of 2 GiB.

Show CPU and Memory

3 - Disks - Click use existing disk image and set the disk type to VirtIO. Select the Zvol on which you installed HAOS.

Show Disks

4 - Network Interface - Set the adapter type to VirtIO. Select a network device to associate with the VM. You should choose a bridge if you want the VM to communicate with TrueNAS. If you are not using a bridge, enable Trust Guest Filters to allow Home Assistant’s discovery to work.

Show Network Interface

5 - Installation Media - Nothing is needed here.

Show Installation Media

6 - GPU - Defaults should be fine.

Show GPU

7 - Confirm Options - Click Save.

Show Confirm Options

Please see the 2nd post for troubleshooting common issues

This guide is also posted in the Home Assistant forums here
More information about creating a VM in TrueNAS can be found here
More information about installing HAOS in a VM can be found here

troy · April 2, 2024, 1:18am

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

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 Gateway

The ConBee II needs to be attached to the VM in a specific way. Currently, TrueNAS lacks a method to handle such a device using USB passthrough. If you are using the ConBee II, it is recommended to use PCI passthrough for the USB controller to which the ConBee is connected.

Alternatively, you can use a script to start your VM. The script will correctly attach the ConBee II to your VM before Home Assistant or any add-ons have a chance to start. It is annoying, but if you don’t restart your VM very often, this may be a suitable workaround.

Click to Show Script

`start_haos.sh`

Save this script to your TrueNAS and make it executable.
Edit line 4 and set the name of your VM.
Using the TrueNAS shell, run the script to start your VM.

#!/usr/bin/env bash

## Set the name of your VM
VM='HAOS'


if [ ${EUID} -ne 0 ]; then
  echo "Please run this script as root or using sudo" ; exit
elif [ -z "${CONBEE:="$(ls /dev/serial/by-id/*ConBee_II*)"}" ]; then
  echo "ConBee II not found" ; exit
fi

## HEREDOC: ConBee_II.xml
read -r -d '' XML << END_XML
<serial type="dev">
  <source path="${CONBEE}"/>
  <target type="usb-serial" port="1">
    <model name="usb-serial"/>
  </target>
  <address type="usb" bus="0" port="4"/>
</serial>
END_XML

# create a temporary file containing the ConBee II HEREDOC
conbee_xml=$(mktemp -t conbee.xml.XXXXX)
echo "${XML}" > "${conbee_xml}"

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

# get VM name and use it to attach the ConBee II
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}" "${conbee_xml}"

# remove the temporary file
rm "${conbee_xml}"

The ConBee II will then be visible inside the VM as follows:

/dev/serial/by-id/usb-QEMU_QEMU_USB_SERIAL_1-0000:00:03.7-4-if00-port0

Michel · April 20, 2024, 4:51am

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?

troy · April 20, 2024, 1:05pm

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.

Michel · April 20, 2024, 2:55pm

This is great information, thank you!

sfatula · April 21, 2024, 8:04pm

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.

troy · April 21, 2024, 8:27pm

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.

Liam79 · May 29, 2024, 12:15am

Hi Troy and wider audience,

I am having a similar issue trying to get a ConBee stick working.

When I go to add a device to the virtual machine (Debeian), I can see it in the list under USB passthrough.

When I save this setting, it will not be available as a device on Home Assisntant.

There are no options available for me to be able to use the PCI passthough option.

My stick is the ConBee III (3) Zigbee Matter USB

Any advice for a novice would be greatly appreciated.

troy · May 31, 2024, 1:36pm

Hi @Liam79 - Sorry for the long delay. I’ve been traveling for work.

Unfortunately, I can not offer any advice on PCI Passthrough since I have not used it. Hopefully, someone else can help.

You may also consider making a separate post asking for general help with PCI passthrough since the process should be the same with any VM and not specific to the Conbee USB device.

Prince · June 4, 2024, 6:46pm

Hi Troy,
I have looked through the forms on HAOS and here. I am able to install the HAOS but when I open the virtual machine. It gets stuck at the following.

As you have stated before, it looks like HAOS in not expanding properly. the size is 579.88 MB. I ran the commands as sudo and followed the rest of the instructions here.

I also googled the issue and someone suggested to just type “login”. Which just seems to restart the HAOS CLI but after about 30 sec it goes back to stating “Home Assistant CLI not starting”

Anything you can suggest?

Thanks

troy · June 4, 2024, 7:28pm

Hi @Prince - I’m guessing the downloaded file is most likely corrupt.

Please remove any existing files and try again.

rm haos_ova-12.2.*

Removing the existing file(s) before you try to download them again is important because multiple attempts to download (without removing the existing file) will append a number suffix, which unxz will complain about. Also, unxz ignores the suffix, so it will continue to unzip the first download.

You can still reuse your existing zvol and VM - Just overwrite it with the new file.

EDIT: The following link may provide more explanation if needed

Prince · June 4, 2024, 9:45pm

I will try that later tonight and see. Thanks for your help!

Prince · June 5, 2024, 6:13am

So I deleted the old file. Followed the whole procedure again, still the same result. I even deleted zvol and recreated the zvol. That didn’t help either. Is there way to check any logs to see why it is not working?

troy · June 5, 2024, 1:47pm

@Prince - can you say what version of TrueNAS you are using? You may have that information in a signature but that does not show up on mobile.

Also, please confirm you are trying to download HAOS V12.2

I will try to reproduce this issue on my end. I’m not aware of any logs that can be checked at this point since HAOS has failed to start.

Prince · June 5, 2024, 4:11pm

Hi @troy i am using Truenas Scale Dragonfish-24.04.1.1. I am trying to install HAOS V12.3. I am coping the link directly form HAOS website, which happens to be 12.3 but should I try 12.2? Also I have adguard and Tailscales installed could those somehow be stopping HAOS from downloading the necessary packets to expand? I was able to ping google.com, 8.8.8.8 and 1.1.1.1 from the emergency console. But I was not angle to ping the host because I don’t have a bridge network setup. Thanks for your help.

troy · June 5, 2024, 4:25pm

Hi @Prince - Please give 12.2 a try. You would not be the first person to have an issue with 12.3 - I keep this guide updated, but I don’t bump the HAOS version until a day or two after I see the update pushed to my running installation.

At this time, I don’t think Adguard or Tailscale are the issue. I have just tested HAOS 12.2 install; this VM does not have a network cable connected. Even without internet, you should at least get to the landing page, as shown below.

A bridge should not be required to complete the installation.

I’m still running Cobia 23.10.2. I’ll try HAOS 12.3 and see if I encounter the same issue.

EDIT 1:
HAOS 12.3 installed without issue - I’ll update my TrueNAS and try again.

EDIT 2:
Well, I updated my TrueNAS to Dragonfish-24.04.1.1 and installed HAOS 12.3 again without issue.

Can you share the 3 commands and output you are running for your install

click to show example output from my test

Welcome to TrueNAS
troy@zodiac:~$ wget https://github.com/home-assistant/operating-system/releases/download/12.3/haos_ova-12.3.qcow2.xz
--2024-06-05 12:47:09--  https://github.com/home-assistant/operating-system/releases/download/12.3/haos_ova-12.3.qcow2.xz
Resolving github.com (github.com)... 140.82.112.4
Connecting to github.com (github.com)|140.82.112.4|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://objects.githubusercontent.com/github-production-release-asset-2e65be/115992009/a97331fa-80cf-47cf-94aa-4ce6f0af27e4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=releaseassetproduction%2F20240605%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240605T164710Z&X-Amz-Expires=300&X-Amz-Signature=8a3f153f07ab1e5569a54caa2f46f3dcce663021527030f1599677388c7103d8&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=115992009&response-content-disposition=attachment%3B%20filename%3Dhaos_ova-12.3.qcow2.xz&response-content-type=application%2Foctet-stream [following]
--2024-06-05 12:47:10--  https://objects.githubusercontent.com/github-production-release-asset-2e65be/115992009/a97331fa-80cf-47cf-94aa-4ce6f0af27e4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=releaseassetproduction%2F20240605%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20240605T164710Z&X-Amz-Expires=300&X-Amz-Signature=8a3f153f07ab1e5569a54caa2f46f3dcce663021527030f1599677388c7103d8&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=115992009&response-content-disposition=attachment%3B%20filename%3Dhaos_ova-12.3.qcow2.xz&response-content-type=application%2Foctet-stream
Resolving objects.githubusercontent.com (objects.githubusercontent.com)... 185.199.109.133, 185.199.111.133, 185.199.110.133, ...
Connecting to objects.githubusercontent.com (objects.githubusercontent.com)|185.199.109.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 346186720 (330M) [application/octet-stream]
Saving to: ‘haos_ova-12.3.qcow2.xz’

haos_ova-12.3.qcow2.xz        100%[=================================================>] 330.15M  3.93MB/s    in 85s     

2024-06-05 12:48:35 (3.89 MB/s) - ‘haos_ova-12.3.qcow2.xz’ saved [346186720/346186720]

troy@zodiac:~$ unxz haos_ova-12.3.qcow2.xz
troy@zodiac:~$ sudo qemu-img convert -O raw haos_ova-12.3.qcow2 /dev/zvol/ssd/home-assistant/vm/haos
[sudo] password for troy: 
troy@zodiac:~$

Prince · June 5, 2024, 5:01pm

I will try 12.2 and post an update.

Prince · June 5, 2024, 5:32pm

It is finally up and running. I did shutdown Adguard and Tailscale. Maybe the way I have my Adguard setup was messing with DNS but I really don’t know enough to say that for sure. I will post the outputs here but it was same as before, I never got any errors.

Thanks for all your help @troy!

Nordlicht-13 · June 18, 2024, 8:18am

Thanks for the guide to set up Home Assistant in a VM on TrueNAS scale.
Now that my Home Assistant is running on my TrueNAS I tried to make it available over my Ngnix Proxy Manager, that is running as a app on my TrueNAS.
I cant get it to work. Immich and Paperless work with no problem, but I can’t access my Home Assistant running in the TrueNAS VM.
I added

http:
  use_x_forwarded_for: true
  trusted_proxies:

to my configuration.yaml but what IP do I have to add here?
IP of my TrueNAS (Ngnix PM) is not working.

troy · June 18, 2024, 11:43am

I’m sorry @Nordlicht-13 - I can not provide much help beyond installation.

I can only ask if you can ping your TrueNAS from the HAOS console. If not, I believe you need to set up a bridge for HAOS to communicate with TrueNAS or any “apps” running there.

I subscribe to Nabu Casa, which supports Home Assistant development and provides remote access that “just works”, so I’m unfamiliar with any reverse proxy configuration.

Hopefully, someone else can jump in with better help