Installing HAOS (Home Assistant OS) in a VM

troy · April 2, 2024, 12:49am

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

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

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

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