Installation of Home Assistant on your FreeNAS

Tags: #<Tag:0x00007f739a045910>

FreeNAS is a free and open-source network-attached storage (NAS) software based on FreeBSD and the OpenZFS file system. It is licensed under the terms of the BSD License and runs on commodity x86-64 hardware.

This has been tested on FreeNAS 11.3 and should also work on FreeBSD 11.x as well. These instructions assume you already have a running and accessible jail. For more information on creating a jail read the official FreeNAS User Guide regarding Jails. Once you have the jail available, follow the steps below. Directories used follow standard BSD conventions but can be adjusted as you wish.


Enter the Home Assistant jail. If you don’t know which name you have given the jail, you can use the iocage list command to check.

# If the jail is called 'HomeAssistant'
iocage console HomeAssistant

Install the suggested packages:

pkg update && pkg upgrade
pkg install -y autoconf bash ca_root_nss ffmpeg gcc gmake pkgconf python37 py37-sqlite3

Create the user and group that Home Assistant will run as. The user/group ID of 8123 can be replaced if this is already in use in your environment.

pw groupadd -n homeassistant -g 8123
echo 'homeassistant:8123:8123::::::/usr/local/bin/bash:' | adduser -f -

Create the installation directory:

mkdir -p /usr/local/share/homeassistant
chown -R homeassistant:homeassistant /usr/local/share/homeassistant

Create the virtualenv and install Home Assistant itself:

su - homeassistant
cd /usr/local/share/homeassistant
python3.7 -m venv .
source ./bin/activate
pip install --upgrade pip wheel
pip install homeassistant

While still in the venv, use the ensure_config script to populate the configuration directory.

hass --script ensure_config

Next, using the check_config script, we can make Home Assistant finish installing the initial dependencies.

hass --script check_config

Then deactivate venv and logout of the Home Assistant user.

deactivate && exit

Auto-start and running Home Assistant as a service

Create the directory and the rc.d script for the system-level service that enables Home Assistant to start when the jail starts.

mkdir -p /usr/local/etc/rc.d

Then create the file /usr/local/etc/rc.d/homeassistant and insert the content below.

ee /usr/local/etc/rc.d/homeassistant
  • To save and exit, press ESC then press ENTER twice
# PROVIDE: homeassistant
# KEYWORD: shutdown
# homeassistant_enable: Set to YES to enable the homeassistant service.
#       Default: NO
# homeassistant_user: The user account used to run the homeassistant daemon.
#       This is optional, however do not specifically set this to an
#       empty string as this will cause the daemon to run as root.
#       Default:  "homeassistant"
# homeassistant_group: The group account used to run the homeassistant daemon.
#       Default:  "homeassistant"
# homeassistant_config_dir: Directory where the homeassistant `configuration.yaml` is located.
#       Default:   "$HOME/.homeassistant"
#       Change:    `sysrc homeassistant_config_dir="/usr/local/etc/homeassistant"`
#       Reset to default: `sysrc -x homeassistant_config_dir`
# homeassistant_venv: Directory where the homeassistant virtualenv is located.
#       Default:  "/usr/local/share/homeassistant"
#       Change:    `sysrc homeassistant_venv="/srv/homeassistant"`
#       Reset to default: `sysrc -x homeassistant_venv`

# -------------------------------------------------------
# Copy this file to '/usr/local/etc/rc.d/homeassistant'
# `chmod +x /usr/local/etc/rc.d/homeassistant`
# `sysrc homeassistant_enable=yes`
# `service homeassistant start`
# -------------------------------------------------------

. /etc/rc.subr


load_rc_config ${name}
: ${homeassistant_enable:="NO"}
: ${homeassistant_user:="homeassistant"}
: ${homeassistant_group:="homeassistant"}
: ${homeassistant_config_dir:="/home/homeassistant/.homeassistant"}
: ${homeassistant_venv:="/usr/local/share/homeassistant"}


homeassistant_prestart() {
  install -g ${homeassistant_group} -m 664 -o ${homeassistant_user} -- /dev/null "${logfile}" \
  && install -g ${homeassistant_group} -m 664 -o ${homeassistant_user} -- /dev/null "${pidfile}" \
  && install -g ${homeassistant_group} -m 664 -o ${homeassistant_user} -- /dev/null "${pidfile_child}" \
  || return 1

  if [ ! -d "${homeassistant_config_dir}" ]; then
    install -d -g ${homeassistant_group} -m 775 -o ${homeassistant_user} -- "${homeassistant_config_dir}" \
    || return 1
  HA_ARGS="--config ${homeassistant_config_dir}"
  if [ -n "${homeassistant_log_file}" ]; then
    install -g ${homeassistant_group} -m 664 -o ${homeassistant_user} -- /dev/null "${homeassistant_log_file}" \
    && HA_ARGS="${HA_ARGS} --log-file ${homeassistant_log_file}"
  if [ -n "${homeassistant_log_rotate_days}" ]; then
    HA_ARGS="${HA_ARGS} --log-rotate-days ${homeassistant_log_rotate_days}"
  rc_flags="-f -o ${logfile} -P ${pidfile} -p ${pidfile_child} ${HA_CMD} ${HA_ARGS}"

homeassistant_poststart() {
  sleep 1
  run_rc_command status

homeassistant_prerestart() {
  eval "${homeassistant_venv}/bin/hass" --config "${homeassistant_config_dir}" --script check_config

homeassistant_status() {
  if [ -n "$rc_pid" ]; then
    echo "${name} is running as pid $rc_pid."
    echo "http://`ifconfig | sed -En 's/;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p'`:8123"
    echo "${name} is not running."
    return 1

homeassistant_postcmd() {
    rm -f -- "${pidfile}"
    rm -f -- "${pidfile_child}"

run_rc_command "$1"

Make the rc.d script executable:

chmod +x /usr/local/etc/rc.d/homeassistant

Configure the service to start on boot and finally start Home Assistant!:

sysrc homeassistant_enable="YES"
service homeassistant start


Before upgrading, read the changelog to see what has changed and how it affects your Home Assistant instance. Enter the jail using iocage console <jailname> then stop the Home Assistant service:

service homeassistant stop

Switch to your Home Assistant user and activate the venv:

su - homeassistant
cd /usr/local/share/homeassistant
source ./bin/activate

Upgrade Home Assistant:

pip install --upgrade homeassistant

Then deactivate venv and logout of the Home Assistant user. Finally start Home Assistant:

deactivate && exit
service homeassistant start

Adding support for Z-Wave and Zigbee USB sticks

:information_source: USB Z-Wave sticks may give dmesg warnings similar to “data interface 1, has no CM over data, has no break”. This doesn’t impact the function of the Z-Wave stick in Home Assistant. Just make sure the proper /dev/cu* is used in the Home Assistant configuration.yaml file.

Inside in the jail:
Ensure the following package has been installed

iocage console HomeAssistant
pkg install -y gmake

Then you can install the Z-Wave package

su - homeassistant
cd /usr/local/share/homeassistant
source ./bin/activate.csh
pip install homeassistant-pyozw
deactivate && exit

On the FreeNAS host:

:warning: These steps to enable pass through for Z-Wave / Zigbee USB devices were originally created for FreeNAS 9.x - If you are having trouble getting your Z-Wave or Zigbee USB stick to show up in your jail on FreeNAS 11 or TrueNAS Core, you can try this alternate approach.

Stop the Home Assistant Jail

iocage stop HomeAssistant

Edit the devfs rules

vi /etc/devfs.rules

Add the following lines

add path 'cu\*' mode 0660 group 8123 unhide

Reload devfs

service devfs restart

Edit the ruleset used by the jail in the FreeNAS GUI by going to Jails -> HomeAssistant -> Edit -> Jail Properties -> devfs_ruleset. – Set it to 7

Start, then connect to the Home Assistant jail

iocage start HomeAssistant
iocage console HomeAssistant

Inside in the jail:
Verify that you see the modem devices

ls -l /dev/cu*

You should see output similar to the following

crw-rw----  1 uucp  dialer  0x197 Jul 23 11:45 /dev/cuaU0
crw-rw----  1 uucp  dialer  0x198 Jul 23 11:45 /dev/cuaU0.init
crw-rw----  1 uucp  dialer  0x199 Jul 23 11:45 /dev/cuaU0.lock

Add the Z-Wave configuration to your configuration.yaml and restart Home Assistant

:information_source: The Z-Wave integration is now configurable via the Home Assistant UI

vi /home/homeassistant/.homeassistant/configuration.yaml
  usb_path: /dev/cuaU0
  polling_interval: 10000
service homeassistant restart

I’ve captured these instructions in some scripts to make it easier to run. I’ve been using them for a while now and seem to be stable now. Scripts are available here:

A big thank you for this guide it has been very useful.

I seem to have one issue that when I run the GUI the command holds the console command open so I can’t then detach.

I run: hass --open-ui

However instead of outputting the “Starting Home Assistant” message the console holds stdout and logs to screen.

I then can’t extract myself from the venv and the GUI is only running while the command is left running.

I’ve googled and tried to search the communit but no joy.

Anyone help I feel like this is a total n00b issue but I’m very new to Home Assistant.

(Freenas 11.2 iocage jail)

I tried using the command in the linked github script:

timeout 180 hass --open-ui

This seems to timeout the command however the GUI stops too…

Hey there,
This is the normal behaviour, the purpose of hass --open-ui is only to create and populate the configuration directory in /home/homeassistant/.homeassistant/. Once that’s done, you need to stop the command and start homeassistant as a service with

 service homeassistant start

The same logic is built in the script with the timeout command, runs hass --open-ui for 3 minutes then stops.

Hope this helps.

1 Like

Thanks! That makes perfect sense… I should have just kept going! :smiley:

How are you adding access for a SMB share to access the config?

I’ve added the User and Group homeassistant under GID/UID 8123 in the main NAS and added appropriate ACL’s but still I have no access right to the folder?


My share setting have maintained it’s since l first set them up back on FreeNAS 11.1 – the setup has changed a few time since then so I’m not sure the exact steps to say right now. I gave it a quick try using the TrueNAS defaults and I couldn’t get this work either – Seems there is some trick to correctly setting ACL in this case.

Anyway’s – In my setup I have only created the group with UID 8123 and I add that group to my own user account. ( I use group permission to control rw access to the configuration ) You may need to set group rw permissions on the configuration directory for this work. IMO it is important the permission are set from inside the jail and not using the FreeNAS / TrueNAS UI - something simple, for example.

chmod -R g=u /home/homeassistant/.homeassistant

( Edited to correct command chown chmod )

Here’s a shot of my working share configuration

Note the auxiliary parameters I use override general read-only setting by adding my user to the write list. The create mask and directory mask ensure that new files/folder are created with the correct permissions for this setup.

write list = troy

create mask = 0664
directory mask = 0775
vfs objects = zfs_space zfsacl streams_xattr

I’m not sure where this last line came from – I think it was added when I upgraded FreeNAS 11.3 --> TrueNAS Core - Honestly I can’t say for sure, I haven’t looked at these setting in a few years.

So I’ve followed this but I still can’t get it to share correctly, not sure what it is as I can see all files yet I only have Read-Only access.

I’ve also re-installed the official Plugin and it still can not give me read/write access with the same permissions and no ACL’s set.

Still at a loss, any help will be very much appreciated!


Can you confirm the permissions inside the jail

iocage console $jail
ls -al /home/homeassistant/.homeassistant

I might also create a test file in the jail, with rw permissions for everyone…

touch /home/homeassistant/.homeassistant/test_file.txt
chmod 666 /home/homeassistant/.homeassistant/test_file.txt

… then test edit / save using you share. If you still cannot save any changes to the test file using the samba, I would assume to look in setting on FreeNAS for the cause. ( remember the most restrictive permission wins )

I’m creating a FN 11.3 VM now to test… I can’t say for sure, but it’s also possible you may need to create an external dataset if you want share the configuration over samba. I know this was case on FreeNAS 11.2, but I never tried on FreeNAS 11.3 – On TrueNAS Core, I have tested this and creating a share to a location inside a jail does seem to work.

EDIT – I have tested this on FreeNAS 11.3 and confirmed that creating a share from inside a jail should work.

Screenshots from FreeNAS 11.3 samba config

I used a clean install of the plugin to test but this should be the same for a manual jail. Noting The configuration directory is not hidden with a leading . in the plugin. The share I created here points to /home/homeassistant and I have rw access to the config over samba

Configuration Setting

Press SAVE



Just FYI ( Sorry, I know I’m horrible at listing all the plugin details ) – the plugin runs Home Assistant with a umask=2 – which this case basically means files should already have the correct rw permission set for the $homeassisatnt_group. It’s a small detail but otherwise there is no difference to setting up a file share if you are using the plugin or manual jail.

Please tell me what I am doing wrong, I’ve checked the samba settings in TrueNAS and all seem fine it just gaining access to this jails contents I can’t seem to break!

I have many others shares but these shares reside on my Tank drive, which is the dedicated media drive for the NAS. All the jails run from this smaller ‘swap’ drive and I have 0 ACL’s setup on it anywhere

Thank you so much for your pointers so far


Edit: Added wrong picture

You are very close looking at your screenshot – There is only rw permissions for the owner


You want yours to look something like this
[email protected]:~ # ls -al /home/homeassistant/homeassistant/
total 27014
drwxrwxr-x  16 homeassistant  homeassistant         36 Jul 27 17:32 .
drwxrwsr-x  17 homeassistant  homeassistant         25 Jul 24 10:04 ..
drwxrwxr-x   2 homeassistant  homeassistant          7 Jul 27 17:03 .cloud
-rw-rw-r--   1 homeassistant homeassistant        287 Jul  4 13:20 .directory
-rw-rw-r--   1 homeassistant  homeassistant          7 Jul 25 11:14 .HA_VERSION
drwxrwxr-x   3 homeassistant  homeassistant         27 Jul 27 17:24 .storage
drwxrwxr-x   2 1000           homeassistant          3 Mar 31 15:17 .vscode
drwxrwxr-x   3 homeassistant  homeassistant         11 Apr 29 17:55 automations
-rw-rw-r--   1 homeassistant  homeassistant        717 Feb 28 16:49 automations.yaml
-rw-rw-r--   1 homeassistant  homeassistant       1282 Jun 11 22:20 configuration.yaml
drwxrwxr-x   5 homeassistant  homeassistant          5 Jul 25 12:53 custom_components
-rw-rw-r--   1 homeassistant  homeassistant        226 Feb 22 20:24 customize.yaml
drwxrwxr-x   2 homeassistant  homeassistant          2 Jun  1 11:08 deps
-rw-rw-r--   1 homeassistant  homeassistant        675 Feb 23 02:21 emulated_hue_ids.json
drwxrwxr-x   2 homeassistant  homeassistant          3 Feb 23 13:42 groups
-rw-rw-r--   1 homeassistant  homeassistant         64 Dec 27  2019 groups.yaml
-rw-rw-r--   1 homeassistant  homeassistant       6671 Jul 27 17:11 harmony_12187291.conf
-rw-rw-r--   1 homeassistant  homeassistant  436936704 Jul 27 17:32 home-assistant_v2.db
-rw-rw-r--   1 homeassistant  homeassistant     171772 Jul 27 17:11 home-assistant.log
-rw-rw-r--   1 homeassistant  homeassistant         55 Dec 27  2019 known_devices.yaml
drwxrwxr-x   2 homeassistant  homeassistant          3 Feb 29 23:11 lights
-rw-rw-r--   1 homeassistant  homeassistant       1122 Jan 17  2020 options.xml
-rw-rw-r--   1 homeassistant  homeassistant      35414 Jun  6 11:58 OZW_Log.txt
drwxrwxr-x   9 homeassistant  homeassistant         10 Jul 13 10:39 packages
-rw-rw-r--   1 homeassistant  homeassistant      32768 Jan 17  2020 pyozw.sqlite
drwxrwxr-x   2 homeassistant  homeassistant          4 Feb 23 12:49 scenes
-rw-rw-r--   1 homeassistant  homeassistant          3 Jan 19  2020 scenes.yaml
-rw-rw-r--   1 homeassistant  homeassistant         66 Dec 27  2019 scripts.yaml
-rw-rw-r--   1 homeassistant homeassistant       2527 Jul 19 23:16 secrets.yaml
drwxrwxr-x   2 homeassistant  homeassistant          3 Feb 29 23:13 switches
drwxrwxr-x   5 homeassistant  homeassistant          5 Jul 25 11:09 themes
drwxrwxr-x   2 homeassistant  homeassistant          3 Feb 23 02:57 tts
drwxrwxr-x   3 homeassistant  homeassistant          3 Feb 22 22:12 www
-rw-rw-r--   1 homeassistant  homeassistant      77824 Jul 27 17:31 zigbee.db
-rw-rw-r--   1 homeassistant  homeassistant      10646 Jun  6 11:46 zwcfg_0xcfb0615a.xml
-rw-rw-r--   1 homeassistant  homeassistant        108 Jun  6 11:46 zwscene.xm

Please try ( this will set the group permission equal to the owner permissions )

iocage console $jail
chmod -R g=u /home/homeassistant/.homeassistant

If you are not familiar with reading / modiying unix type permissions from the command line, this might be helpful

Also on your TrueNAS host make sure you created the homeassistant group and added your user david.bayley to that group.

1 Like


Looks like it is all working? (So far so good)

Found that when I set up the share, it wouldn’t save the additional parameters set so I think it was that all this time as I can now modify all files!

Thank you so much for your help, I re-built the whole jail and HA - now to get back to working out how to automatically backup the config etc

Can I ask, I noticed on one of my builds I could add the samba addon via service homeassistant install samba does this mean that plugins work with this version of HA? I’ve always had dedicated hardware to HA and not really worked with having it running on Free/TrueNAS but after updating the hardware in my NAS I decided to get it running on this shared hardware.

Thanks again for your help - this was bugging me for some time!!


Edit: I realise that this command works only on the plugin, my question is can I install other addons with this version?

Please forgive if I misunderstand your question – I think you are confusing the terminology; I do not mean to be picky but I think it is important to have this part correct – Technically I understand “add-ons” to be specific to Home Assistant OS and Home Assistant Supervised - In such case, an “add-on” is a docker container providing an additional piece of software, that has been customized to be installed and managed from the Home Assistant UI. Add-ons are typically pre-configured to work nearly “out-of-the-box” with Home Assistant – Keep in mind, Docker is a Linux technology. Docker is simply not available on FreeBSD / FreeNAS / TrueNAS (unless you run Linux in a VM)

Instead we have jails, that provide the same concept as a docker container – On FreeNAS / TrueNAS we have “plugins”. - In this case a “plugin” is a jail providing an additional piece of software to expand the functionality of our NAS. A “plugin” can provide some basic controls from the NAS UI but these are mostly standalone jails. Regarding Home Assistant, the “plugin” is really nothing more than a scripted installation.

To answer what I think you’re asking – yes you can add the same additional software provided by “add-on”, but it will not have the convenience to “just work” with Home Assistant – Instead of an “add-on”, you could first look for a “plugin” that provides what software you need, then manually configure it’s integration with Home Assistant. If there is not a “plugin” available, you could manually create a separate jail for it.

In the case of two common “add-ons” samba and ssh – These services are already provided by the NAS host system. Although you could do so if you really wanted, I think it is unnecessary to install these a second time from inside of a jail.

– Hope that kind of helps.

And to answer your edited question regarding the plugin – This is not a command intended install samba.

service homeassistant install [SOMETHING]

That is equal to

su - $homeassistant_user
source $homeassistant_venv/bin/activate
pip install [SOMETHING]

Some typical use cases

  • Upgrading pip
  • Upgrade Home Assistant
  • Install a specific Home Assistant version
service homeassistant install --upgrade pip
service homeassistant install --upgrade homeassistant
service homeassistant install homeassistant==0.112.5

There is one exception when using the “plugin”

  • Simple shortcut to download / install the latest HACS
  • HACS is a custom integration ( not a plugin or add-on )
service homeassistant install hacs
1 Like

Yea you’ve confirmed my suspicions on how this version would work. I already have a Node-Red and few other jails running which provide access to the services I require to run HA in the way I intend.

I was more wanting to have a play with App Daemon as it seems to play more prettier with my tablets I had eyed up for a future project but alas I digress in creating a better lovelace UI instead - that is (BIG Thanks to you) now I can access the dam files!

Thank you again, I do appreciate all the help you’ve provided to get my HA running and my knowledge to grow bigger!


1 Like

The writeup here was top notch. I was able to get homeassistant up and running quickly. Thanks!

I’m curious what the best practice is for editing the main configuration file is.

I noticed that with this install method there’s no “” tab on the left (like in many of the videos i see at 'The Hook Up on youtube). Does this mean I should just jexec into the jail and edit ./usr/home/homeassistant/.homeassistant/configuration.yaml manually? Is there a config-check tool like the “Configurator” plugin thing has?


FWIW, editing the file with vi and then checking it with:
/usr/local/share/homeassistant/bin/hass --script check_config -c /usr/home/homeassistant/.homeassistant/
seems to work.

If others have a ways to install the configurator thing, that’d still be nice!

The Hass-Configurator ( :wrench: File Editor ) can be installed in a separate virtualenv. Basically follow the same steps you used to install homeassistant, except install hass-configurator instead. Just use the existing $homeassistant_user. For start-up, you can either adapt the RC script from this guide or download mine - The configuration file is technically option but I strongly recommend in order to define persistent setting.

It’s all pretty straight forward, but even easier still, the community plugin includes an option install the configurator from the jails console menu :wink: