My (almost) complete quick start to installing Home Assistant on FreeNAS 11.2 (Including AppDaemon/HA-Dashboard, Hass-Configurator, Mosquitto and TasmoAdmin)


Quick Start for Home Assistant on FreeNAS 11.2

This quick start guide assumes

My setup for this guide is on a clean install of FreeNAS 11.2

  • FreeNAS storage pool is tank
  • FreeNAS user is troy
  • Change these accordingly through out this guide

I have also enabled and started samba and ssh

  • ssh for remote console connection to FreeNAS
  • samba for access & editing of Home-Assistant configuration
Show Me

Getting Started

Creating a common dataset and setting it up so your-FreeNAS-user and hass, the jail/plugin user running Home Assistant, can both access and edit the Home Assistant configuration

This “Getting Started” section is technically optional however I recommend you, especially new users, to start here. Skipping this can severely limit your ability to easily edit your Home Assistant configuration files. Using the Hass-Configurator is a great way around this limitation

Typically, the jail or plugin user & group name is similar to the service application name running inside the plugin or jail. Also, the UID and GID are usually the same as the port number used by the service. During this guide I will be creating a plugin or jail user & group hass with a UID/GUID of 8123 matching the default Home Assistant port.

Add the hass group to FreeNAS

I recommend at minimum to create and join the hass group on FreeNAS.

  • The hass group can allow select-FreeNAS-users Read/Write access to the Home Assistant configuration files
Show Me

Create a dataset for hass

Creating a separate dataset for hass has numerous advantages

  • Required for creating a network share to access configuration
  • Easily access configuration from outside the jail
  • Ability to backup and restore using zfs snapshot
Show Me

Share the dataset via samba (network)

Optional but really nice to have.

  • Enable network access to your Home Assistant configuration
  • Easily add, remove or edit files and folders from network attatched computers
Show Me

Installing Home Assistant

There are several options for installing Home Assistant on FreeNAS

iocage plugin-jail
  • Scripted install. Only 2 commands!
  • Maybe the future “Official” Home Assistant plugin for FreeNAS ???
Show Me
wget -O /tmp/homeassistant.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes -n /tmp/homeassistant.json --branch 'master'

iocage standard-jail (Scripted Install)

  • Recommended installation method
  • Scripted install. Only 5 commands!
  • Includes simple menu to execute updates!
  • Option to install App-Daemon/HA-Dashboard
  • Option to install Hass-Configurator
  • Option to use pre-configured example files
    • Recommended for new install if you also installed AppDaemon or Hass-Configurator
    • Sample config for Hass-Configurator and added to Home-Assistant
    • Sample HA-Dashboard provided and added to Home-Assistant
    • Sample App-Daemon configuration required for appdaemon & ha-dashboard to start
Show Me

Download pkg-list and create a jail using it to install requirements

wget -O /tmp/pkglist.json
sudo iocage create -r 11.2-RELEASE boot=on dhcp=on bpf=yes vnet=on -p /tmp/pkglist.json -n homeassistant

Optional: mount a dataset inside the jail

sudo iocage fstab -a homeassistant "/mnt/tank/user/hass /home/hass nullfs rw 0 0"

Git script and begin install

sudo iocage exec homeassistant git clone /root/.iocage-homeassistant
sudo iocage exec homeassistant bash /root/.iocage-homeassistant/ standard

Answer questions will choose what gets installed

Install Home-Assistant?  [Y/n]:
Install Hass-Configurator?  [Y/n]:
App-Daemon & HA-Dashboard?  [Y/n]:
Use the pre-configured examples?  [Y/n]:



iocage standard-jail (Manual Install)

  • Manual installation guide updated for FreeNAS 11.2
Show Me

Install Home-Assistant on FreeNAS 11.2

  • This guide should still work with FreeNAS 11.1

Creating a jail

Starting with FreeNAS 11.2 new jails can be created and datasets mounted using the gui. This can be an advantage if you’d like to customize many options.
To quickly create a jail with default settings it is still much quicker to use the FreeNAS console.

I will -n name this jail homeassistant and since I assign the ip-address from my router I set the jail to use dhcp

sudo iocage create -r 11.2-RELEASE dhcp=on bpf=yes vnet=on boot=on -n homeassistant
Mounting a dataset inside you jail
  • This will require a pre-existing dataset.
  • This step is optional for Home-Assistant however it is required if you plan access your Home-Assistant configuration directory using any type of network file sharing (ie samba).
  • While this can be done later, it is much easier to have this already mounted before installing Home-Assistant

I’m going to mount the /mnt/tank/user/hass dataset I created earlier. It will be mounted inside the jail at /home/hass and will contain the Home-Assistant configuration directory.

iocage fstab -a homeassistant "/mnt/tank/user/hass /home/hass nullfs rw 0 0"
Install jail requirements

Log into the homeassistant JAIL console

sudo iocage console homeassistant

Install requirements for Home-Assistant and Z-Wave

pkg update && pkg upgrade
pkg install python36 py36-sqlite3 bash gmake ca_root_nss

At this point I believe you can finish installing Home-Assistant following any desired pip (python) install method.

Installing Home-Assistant

  • It has been pointed out that a virtualenv inside a jail is not needed since the jail itself is already a jail! I still prefer this method.

Best practice suggests to create a user/group hass then install Home-Assistant inside a python virtualenv.

If not already, log into the homeassistant JAIL console

sudo iocage console homeassistant
Create a user to run Home-Assistant
  • Typically, the user and group names are similar to the application name. Also, the UID and GID are usually the same as the port number used by the service.
  • I’m creating a user hass with a UID/GUID of 8123 matching the default Home-Assistant port.

The next commands, create a home directory if it does not already exist, as well as adding the group and user.
I will add hass to the dialer group as required for using the (USB) Aeotec Z-Wave stick.

install -d -g hass -o hass -m 775 -- /home/hass
pw addgroup -g 8123 -n hass
pw adduser -u 8123 -n hass -d /home/hass -w no -s /usr/local/bin/bash -G dialer -c "Daemon User for Home-Assistant"
Install pip requirements and create directory to install Home Assistant virtualenv
python3.6 -m ensurepip
pip3 install --upgrade pip
pip3 install --upgrade virtualenv
install -d -g hass -o hass -m 775 -- /srv/homeassistant
Switch to user hass, activate the virtualenv and finally install Home-Assistant!
su - hass
virtualenv -p /usr/local/bin/python3.6 /srv/homeassistant
source /srv/homeassistant/bin/activate
pip3 install --upgrade homeassistant
deactivate && exit

Automatically starting on boot-up

Create directory if it doesn’t exist and add the startup script

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

Show File: /usr/local/etc/rc.d/homeassistant
# 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: hass
# homeassistant_group:    The group 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 with group wheel.
#            Default: hass
# homeassistant_dir:    Directory where config files are located.
#            Default: ~/.homeassistant
# sysrc homeassistant_enable=yes
# service homeassistant start

. /etc/rc.subr


load_rc_config ${name}
: ${homeassistant_enable:="NO"}
: ${homeassistant_user:="hass"}
: ${homeassistant_group:="hass"}
: ${homeassistant_config_dir:="/home/hass/homeassistant"}


        rc_flags="-f -P ${pidfile} -p ${pidfile_child} /srv/homeassistant/bin/hass --config ${homeassistant_config_dir} ${rc_flags}"
    if [ ! -e "${pidfile_child}" ]; then
            install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile_child}";

    if [ ! -e "${pidfile}" ]; then
            install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${pidfile}";

    if [ ! -d "${homeassistant_config_dir}" ]; then
        install -d -g ${homeassistant_group} -o ${homeassistant_user} -- "${homeassistant_config_dir}";

    rm -f -- "${pidfile}"
    rm -f -- "${pidfile_child}"

run_rc_command "$1"

copy and paste. Press escape then enter twice to save and exit

Make this file executable and enable

chmod +x /usr/local/etc/rc.d/homeassistant
sysrc homeassistant_enable=yes
Finally we can start Home-Assistant
service homeassistant start

From the FreeNAS console You can list jails you have installed and see if they are running. (showing ip addresses requires root)

sudo iocage list -l

| JID |     NAME      | BOOT | STATE | TYPE |     RELEASE     |         IP4         | IP6 | TEMPLATE |
| 1   | homeassistant | on   | up    | jail | 11.2-RELEASE-p3 | epair0b| | -   | -        |

Install Mosquitto

  • plugin-jail for FreeNAS
  • Scripted install. Only 2 commands!
show Me
wget -O /tmp/mosquitto.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes -n /tmp/mosquitto.json --branch 'master'

Install TasmoAdmin

  • plugin-jail for FreeNAS
  • Scripted install. Only 2 commands!
Show Me
wget -O /tmp/tasmoadmin.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes -n /tmp/tasmoadmin.json --branch 'master'

Edit the configuration.yaml using the Hass-Configurator

  • example adding TasmoAdmin to Home Assistant side panel
Show Me

I recommend a standard-jail for Home Assistant because it allows more control. I do not find this need for TasmoAdmin or Mosquitto. For this reason I have provided instructions only for a plugin-jail.

If at a later time any plugin should need to become a standard-jail, I have discovered that iocage export followed by iocage destroy and finally iocage import will do such a trick.

Show Installed

If you really want these as standard-jails see here and here

Update homeassistant jail (Scripted Install)

  • Recommended for the standard-jail - Scripted Install
  • Recommended for plugin-jail - Menu option 1 & 4 only
  • Works from FreeNAS console
Show Me
sudo iocage exec homeassistant bash update

Manual updates and more

  • Recommended for Manual Install
  • Safe for standard-jail - Scripted Install
  • Safe for plugin-jail
  • Works from JAIL console
Show Me

Login to JAIL console

sudo iocage console homeassistant

These commands are run from the JAIL console:

  • No sudo command in the jail since we’re already root
Control the installed service(s)


service homeassistant [start|stop|status|restart]


service appdaemon [start|stop|status|restart]


service configurator [start|stop|status|restart]

Upgrade PiP

To also upgrade pip just include pip3 install --upgrade pip Otherwise you can skip this line in the commands below

Upgrade homeassistant
service homeassistant stop

su - hass
    source /srv/homeassistant/bin/activate
    pip3 install --upgrade pip
    pip3 install --upgrade homeassistant
    deactivate && exit

service homeassistant start
Upgrade appdaemon:
service appdaemon stop

su - hass
    source /srv/appdaemon/bin/activate
    pip3 install --upgrade pip
    pip3 install --upgrade appdaemon
    deactivate && exit
service appdaemon start

Upgrade configurator:
service configurator stop

wget -O /srv/configurator/
chmod +x /srv/configurator/

service configurator start

Update FreeBSD packages

standard-jail or plugin-jail

pkg update && pkg upgrade

Backup Home-Assistant config directory using zip

zip is not installed by default. To use this command you will need to first install zip

pkg update && pkg install zip

create backup as user hass

su - hass
    zip -9 -q -r homeassistant-backup /home/hass/homeassistant -x"components/*" -x"deps/*" -x"home-assistant.log"

These commands are run from the FreeNAS Console

If you need to restart the jail iocage docs recommend using the -s switch.
This “soft-restart” will help prevent issues that could arise from a “hard-restart” when vnet=on

sudo iocage restart -s homeassistant

You can also start or stop the jail.

sudo iocage [start|stop] homeassistant

Backup Home-Assistant jail using snapshots

Create a snapshot

The following would on Oct 3 2018 create a snapshot named [email protected]
-n = “Name_of_Snapshot”

sudo iocage snapshot homeassistant -n $(date +%Y.%m.%d)
List snapshots in homeassistant
sudo iocage snaplist homeassistant
Rollback to previous snapshot
sudo iocage stop homeassistant
sudo iocage rollback homeassistant -n 018.10.03
sudo iocage start homeassistant
Remove snapshot from homeassistant
sudo iocage snapremove homeassistant -n 018.10.03

Update / Upgrade Jail RELEASE:

update the Jail for example from 11.1-RELEASE-p10 to 11.1-RELEASE-p14

sudo iocage update homeassistant

upgrade the Jail for example from 11.1-RELEASE-p10 to 11.2-RELEASE-p3

sudo iocage upgrade -r 11.2-RELEASE homeassistant

Thanks for reading my quick start

This guide and plugin/jail script are only a quick start to get things up and running
Further configuration will likely be required to meet your specific needs


[OUTDATED] FreeNAS Plugin: Demo includes Home Assistant + AppDaemon + Configurator
Installing HASS in virtualenv on FreeNAS 11.1-U3 w/ iocage jail

Not sure what I have missed. When I get to login to the homeassistant jail I get:

[email protected]:~ # iocage console homeassistant
jail: mount.fstab: /mnt/Disk1/iocage/jails/homeassistant/root/home: No such file or directory


The path to your jail /mnt/Disk1/iocage/jails/homeassistant does not look correct. It should be /mnt/iocage/jails/homeassistant. So the question is how did you end up with that?

Do you have a z-pool named Disk1 ?

Which version of FreeNAS are you using when you tried to install Home Assistant and how did you try to install? ( plugin, standard jail or manually )


I’m using FreeNAS-11.2-RC2.

Yes I have a z-pool named Disk1

I followed the iocage standard-jail (Manual Install)

Have I setup the jails wrong?


I got it running :smile:

Deleted the jail and started over at the beginning. Thank you for the great write up.


Hey Troy,

Do you know how to install ffmpeg on the freenas? I have a few cameras that use it with home assistant that will not work without it.


From the homeassistant jail console sudo iocage console homeassistant

You can try installing ffmpeg from the BSD package repo using pkg install ffmpeg

Depending on exactly what is needed from ffmpeg you may need to compile from ports if, for example, you need MP3 support. It’s not that difficult to do just a few more steps but I can’t help with that until I get home from work later.


Yes that would be nice if you could help. I already tried to compile from ports. ffmpeg is installed but I still get errors in home assistant.



@Dayve67 I’m not 100% but have you tried installing libav inside the jail

pkg install libav

Don’t forget you can take a snapshot of your jail first. (from the FreeNAS console)That way if this is not the solution you can easily rollback. -n Some_name_for_your_snapshot

sudo iocage snapshot homeassistant -n before_libav_install

If that doesn’t help you can rollback
sudo iocage stop homeassistant
sudo iocage rollback homeassistant -n before_libav_install
sudo iocage start homeassistant


Firstly, thanks for the superb guide. I created an iocage jail in 11.1-U6 using a previous version (Home Assistant, Configurator and HA Dashboard) which has been working perfectly for a good few months.

I’ve just updated to 11.2-RELEASE so thought I’d come and review the guide for upgrading the jail to FreeBSD 11.2, as the standard command I tried didn’t seem to work on the .json created jails.

Has anyone successfully upgraded a iocage jail using iocage upgrade hass-etc -r 11.2-RELEASE for a jail created with a .json script?

I’m tempted to recreated it using the latest guide, but would like to know if upgrading will be possible if I install using a script.



After a little more reading, bit the bullet and recreated using the iocage standard-jail (Scripted Install) option above which creates a standard jail which I can update more easily. Just need to transfer all my .yaml settings across…


@adrianwi Sorry I didn’t get back quicker.

I think having a standard-jail for this is best. However, just to be clear any of three choices I proved will in the end provide the exact same Home Assistant installation using a python virtualenv. The difference between a standard-jail and a plugin-jail is strictly a FreeNAS thing. The standard-jail (Scripted Install) is exactly the same as following the manual install guide with a few extra files like the bash menu to run updates. Any of these extra files can be safely deleted or demo-config files replaced with your own.

I’m glad you went this route. To transfer your settings maybe you want to have a fresh start and move things over to new config files slowly. But if everything was fine and you just want it done, you can literally just copy each entire configuration directory from your old plugin to the fresh install. Everything is setup same with each config directory inside /home/hass/

Yes I have but I did it on 11.2-BETA. FreeNAS seems to have added some their middle-ware workings now to iocage. In this case FreeNAS now expects to find the whatever-plugin.json file in the /mnt/iocage/.plugin_index directory. So if for example you also installed my plugin-jail for mosquitto and then tried to iocage update mosquitto you would get an error.

[email protected]~ $ sudo iocage update mosquitto
Snapshotting mosquitto...
Updating plugin INDEX...
/mnt/iocage/.plugin_index/mosquitto.json was not found!