My (outdated) Quick Start for Home Assistant Core on FreeNAS 11.2

Updated Feb 10 2020 :tada:

Changing the Home Assistant Brand

The purpose here is only to explain how this thread fits into the scheme of things
depending on where in time it relates to Changing the Home Assistant Brand

Finding a place in time

A = Home Assistant
B =
C = Home Assistant Core

Forever in time

  • The following statement is always TRUE

From the beginning of time until January 29 2020

A = A
B = B
  • During this time the following statement was TRUE

From January 30 2020 until the end of time

A = C
B = A
  • During this time the following statement is TRUE
my personal thoughts

… don’t really matter. :laughing:

I agree with what they are after but I think the new naming, as it stands now, has not gone far enough and will only lead to different confusion. I think it is unfortunate the community was not given any further consideration it the final decision because I think there were several other naming conventions suggested by community members that could have done a better job clearing things up without additional confusion. That is just my opinion.

I do not agree 100% with the new naming but I do respect the final decision has been made.

The discussion has already been closed and will not be reopened here.

I was going to remove the outdated 11.2 guide and keep updating this original post for FreeNAS 11.3 – Now after some suggestion from a few friends, I have to agree that is probably better to just move on. Simply put there are around 230 posts with an estimated read over an hour. Coming to thread this on FreeNAS 11.3 will just have too much outdated information to get through before reach anything current to FreeNAS 11.3. The other factor is name change. After second thoughts, I’m thinking it is probably not gonna help the issue if the first 200+ posts are referring to something that was one thing, but now, that one thing has become something else… Anyways onward to the future…

New Branding = Home Assistant Core | FreeNAS 11.3 = New Thread

Old Branding = Home Assistant | FreeNAS 11.2 = This Old Thread

The FreeNAS 11.2 guide now outdated will no longer be updated.

Getting Started

This “Getting Started” section covers some optional FreeNAS configuration. This is technically not required for Home Assistant, however in my opinion, may provide a better overall experience. For example, having a separate dataset to contain Home Assistant configuration, which can then be shared over a network, allowing to easily edit the files from outside the jail. While these steps can be performed at any time, I find the easiest results can be achieved by starting here before you begin creating your jail. Additional steps will be required if this is done after Home Assistant is installed.

Show Me

Installing FreeNAS is not the scope of this guide however only minimal configuration is assumed.

My FreeNAS setup for this guide

I have also started these services on FreeNAS

  • ssh for remote console connection to FreeNAS
  • samba for network access to Home-Assistant configuration

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

Setting up a separate dataset for Home Assistant configuration

  • Required for using a network share to access configuration
  • Allow FreeNAS user troy and jail user hass READ/WRITE access to files

Create the hass group on FreeNAS

Create the dataset for hass

Share the dataset via samba (network)

Installing Home Assistant Core on FreeNAS 11.2

There are several options for installing Home Assistant Core on FreeNAS

  • This is using the 11.2-RELEASE This release has reach EOL
  • If you are on FreeNAS 11.2-U7 or later, you should use the 11.3-RELEASE instead

iocage standard-jail – Scripted Install

  • Recommended - Basically this is a scripted version of the manual install
  • Includes simple console menu to execute updates
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 vnet_default_interface=auto -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 -b 11.2-RELEASE /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

  • If you are on FreeNAS 11.2-U7 or later, you should use the 11.3-RELEASE instead
Show Me

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 vnet_default_interface=auto 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 python37 py37-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 8123 -o 8123 -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.7 -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.7 /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: USER_NAME
# 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: USER_GROUP
# homeassistant_config_dir:	Directory where homeassistant config is located.
#			Default: ~/homeassistant
# copy file to /usr/local/etc/rc.d/homeassistant 
# chmod +x /usr/local/etc/rc.d/homeassistant
# sysrc homeassistant_enable=yes                        # to enable
# sysrc homeassistant_config_dir="~/homeassistant"      # to change
# service homeassistant start                           # to 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 -o ${logfile} -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 [ ! -e "${logfile}" ]; then
        install -g ${homeassistant_group} -o ${homeassistant_user} -- /dev/null "${logfile}";

    if [ ! -d "${homeassistant_config_dir}" ]; then
        install -d -g ${homeassistant_group} -o ${homeassistant_user} -m 775 -- "${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| | -   | -        |

Managing your Home-Assistant jail

  • How to Update and Start or Stop Home Assistant Core service from the console
Show Me

Upgrading Home Assistant Core to use python 3.7

Easily perform updates from a menu

  • Included only with the Scripted Install
  • Works from FreeNAS console
Show Me
sudo iocage exec homeassistant bash update

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

Create a snapshot of Home-Assistant jail

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

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

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

My other plugins for FreeNAS 11.2

These plugins are using the 11.2-RELEASE

  • These are for FreeNAS 11.2 only
  • This release has reach EOL
Amazon Dash

Create a separate FreeNAS plugin running - Amazon Dash

wget -O /tmp/amazon-dash.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/amazon-dash.json --branch 'master'

Mosquitto MQTT Broker

Create a separate FreeNAS plugin running - Eclipse Mosquitto

wget -O /tmp/mosquitto.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/mosquitto.json --branch '11.2-RELEASE'


Create a separate FreeNAS plugin running - Node-RED

wget -O /tmp/node-red.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/node-red.json --branch '11.2-RELEASE'


Create a separate FreeNAS plugin running - TasmoAdmin

wget -O /tmp/tasmoadmin.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/tasmoadmin.json --branch '11.2-RELEASE'


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

root@freenas:~ # 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.

1 Like

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.

troy@zodiac~ $ sudo iocage update mosquitto
Snapshotting mosquitto...
Updating plugin INDEX...
/mnt/iocage/.plugin_index/mosquitto.json was not found!

Amazon Dash

Dasher is EOL so I’m using Amazon Dash now.

This will create a plugin-jail running Amazon Dash.

wget -O /tmp/amazon-dash.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes -n /tmp/amazon-dash.json --branch 'master'

Attention z-wave users, manual intervention may be required!

On FreeNAS 11.2 - USB devices are no longer exposed by default inside an iocage jail.

This means devices like Aeotec Gen-5 USB Stick and the GoControl/Nortek HUSZB-1 will require several addition steps to get them working. Now this is not so much a big deal but if like me, you’ve never had to configure FreeNAS in this way, the (likely preferred) solution can take some time figure out.

Have a look at my post in the FreeNAS forum if this effect you. The solution is quite simple when you know what to do!

Wow, thank you for the great work! With this guide I was able to move my RaspberryPi installation to FreeNAS without any problems.

1 Like

Thanks for the awesome guide!

I tried to use Mosquitto with a username and password but keep getting (null):$6$(null)$ …looks like a few others have gotten the same thing.

Were you able to get this to work?

Currently I do not use a user name or password with Mosquitto. I’ll try to set this up to see if I can reproduce there error. I do not have any issues when the password is not set.

Work is busy this week so it may not be till this weekend when I have time to investigate.

Just curious, does everything work correctly if you do not use a user name or password?

Yes! I was able to use Mosquitto without issue prior to changing mosquitto.conf to authenticate with username and password. Thanks.

Also working on the Node-Red jail…is your script supposed install a working version or just the jail? When I go to the [Node-Red IP Address]:1880 it fails to load. Do I need to follow the install instructions

I recommend using the plugin scrpit for node-red. It will create a seperate jail and install a working version of node red. Are you seeing any are messages? I just installed the node-red plugin last night and it worked fine.

I’m about to leave work now. I can help you troubleshoot some of this in about an hour

Is there a command I can run in the shell to check if Node-Red is running? Tried service -e and it’s not listed, tried service node-red start and it doesn’t recognize the command.

I found that I provided the wrong commands for Node-RED in my FreeNAS resource. (Its fixed now)

The commands to install Node-RED should be

wget -O /tmp/node-red.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes -n /tmp/node-red.json --branch 'master'

To check if Node-RED is running inside the jail
Log into the jail console, then check the status of Node-RED

sudo iocage console node-red
service nodered status

You can preform the same check from the FreeNAS console

sudo iocage exec node-red service nodered status

Note: Right now there is no hyphen (-) in nodered when referring to the service. I can change that if it makes things confusing. Let me know if you think I should add the hyphen (-) to the service name