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


#1

Quick Start for Home Assistant on FreeNAS 11.2

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 seperate 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 preformed at any time, I find the easiest results can be achieved by starting here before you begin creating your jail or installing Home Assistant. Additional steps may be required if this is done after Home Assistant is running. A more recent example is creating a custom devfs_ruleset on FreeNAS that can be used to unhide a USB z-wave or zigbee controller inside the Home-Assistant jail.

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



Using a USB Z-Wave or Zigbee controller

On FreeNAS 11.2 the default devfs_ruleset used by iocage will only expose a limited number of devices inside the jail – z-wave and zigbee devices are not in this list. This means the Aeotec Gen-5 USB Stick, Nortek HUSZB-1 and similar USB controllers will require a custom devfs_ruleset to unhide them

Show Me

For example, the HUSBZB-1 contains both a zwave and zigbee radio. The zwave radio /dev/cuaU0 and the zigbee radio is /dev/cuaU1. Use a custom devfs_ruleset to unhide cua* devices so zwave and zigbee USB controllers can work inside the jail

List devices inside the jail using default devfs_ruleset=4

sudo iocage exec homeassistant ls /dev

bpf     bpf0    crypto  fd      null    ptmx    pts     random  stderr  stdin   stdout  urandom zero    zfs

List devices inside the jail using custom devfs_ruleset=99

sudo iocage exec homeassistant ls /dev

bpf             cuaU0           cuaU1           fd              ptmx            stderr          urandom
bpf0            cuaU0.init      cuaU1.init      log             pts             stdin           zero
crypto          cuaU0.lock      cuaU1.lock      null            random          stdout          zfs

Creating a custom devfs_ruleset.

  • Create zwave-ruleset.sh on your FreeNAS.
  • This will be a simple script used to create the custom devfs_ruleset
  • I’m using devfs_ruleset=99 because it seems unlikely this would other wise be used by FreeNAS

You can use the FreeNAS console to create the script

ee zwave-ruleset.sh

Add the following contents:

#!/bin/sh
# Create custom devfs_ruleset NUMBER
NUMBER=99

/sbin/devfs rule -s ${NUMBER} add include 1
/sbin/devfs rule -s ${NUMBER} add include 2
/sbin/devfs rule -s ${NUMBER} add include 3
/sbin/devfs rule -s ${NUMBER} add path zfs unhide
/sbin/devfs rule -s ${NUMBER} add path 'bpf*' unhide
/sbin/devfs rule -s ${NUMBER} add path 'cua*' unhide

Be sure to make the script executable

chmod +x zwave-ruleset.sh

Run this script from the FreeNAS console to immediately create the custom ruleset.

sudo sh zwave-ruleset.sh

You can view the ruleset has been created correctly.
sudo devfs rule -s 99 should return the following:

sudo devfs rule -s 99 show

100 include 1
200 include 2
300 include 3
400 path zfs unhide
500 path bpf* unhide
600 path cua* unhide

Finally add zwave-ruleset.sh as a startup script using the FreeNAS GUI. This will automagically recreate the devfs_ruleset every (re)boot.


For a new jail, you can set the devfs_ruleset=99 property during creation.

For an existing jail, do this from the FreeNAS console or use the GUI. Restart the jail to take effect.
Here I find the FreeNAS console quicker. For example, if your Home Assistant jail is already running.

sudo iocage set devfs_ruleset=99 homeassistant
sudo iocage restart homeassistant


Installing Home Assistant

There are several options for installing Home Assistant on FreeNAS


iocage standard-jail – Scripted Install

  • Recommended - Basically this is a scripted version of the manual install
  • Includes simple console menu to execute updates
  • Options to install Hass-Configurator and App-Daemon (Includes HA-Dashboard)
  • AppDaemon and Hass-Configurator need a configuration file in order to start.
  • Option to use example configuration files so they can work “out of the box”
Show Me

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

wget -O /tmp/pkglist.json https://raw.githubusercontent.com/tprelog/iocage-homeassistant/master/pkg-list.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 https://github.com/tprelog/iocage-homeassistant.git /root/.iocage-homeassistant
sudo iocage exec homeassistant bash /root/.iocage-homeassistant/post_install.sh 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]:

Profit!

Screenshots








iocage standard-jail – Manual Install

  • Manual installation guide updated for FreeNAS 11.2
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 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
#!/bin/sh
#
# PROVIDE: homeassistant
# REQUIRE: LOGIN
# 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
name=homeassistant
rcvar=${name}_enable

pidfile_child="/var/run/${name}.pid"
pidfile="/var/run/${name}_daemon.pid"
logfile="/var/log/${name}_daemon.log"

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

command="/usr/sbin/daemon"

start_precmd=${name}_precmd
homeassistant_precmd()
{
        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}";
    fi

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

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

stop_postcmd=${name}_postcmd
homeassistant_postcmd()
{
    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|192.0.1.179 | -   | -        |
+-----+---------------+------+-------+------+-----------------+---------------------+-----+----------+


iocage plugin-jail
  • I recommend a standard-jail for Home Assistant
Show Me

Create an iocage-plugin on FreeNAS running Home Assistant

wget -O /tmp/homeassistant.json https://raw.githubusercontent.com/tprelog/iocage-homeassistant/master/homeassistant.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes boot=on -n /tmp/homeassistant.json --branch 'master'


Managing your Home-Assistant jail

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

Easily preform 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)

Home-Assistant

service homeassistant [start|stop|status|restart]

AppDaemon\HA-Dashboard

service appdaemon [start|stop|status|restart]

Hass-configurator

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 https://raw.githubusercontent.com/danielperna84/hass-configurator/master/configurator.py -O /srv/configurator/configurator.py
chmod +x /srv/configurator/configurator.py

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


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


These are some other things I use on FreeNAS along with Home Assistant.

Mosquitto

Show Me

Create a separate iocage-plugin on FreeNAS running - Eclipse Mosquitto

wget -O /tmp/mosquitto.json https://raw.githubusercontent.com/tprelog/iocage-mosquitto/master/mosquitto.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes boot=on -n /tmp/mosquitto.json --branch 'master'

Node-RED

Show Me

Create a separate iocage plugin for FreeNAS running - Node-RED

wget -O /tmp/node-red.json https://raw.githubusercontent.com/tprelog/iocage-node-red/master/node-red.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes boot=on -n /tmp/node-red.json --branch 'master'

Amazon Dash

Show Me

Create a separate iocage-plugin on FreeNAS running - Amazon Dash

wget -O /tmp/amazon-dash.json https://raw.githubusercontent.com/tprelog/iocage-amazon-dash/master/amazon-dash.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes boot=on -n /tmp/amazon-dash.json --branch 'master'

TasmoAdmin

Show Me

Create a separate iocage-plugin on FreeNAS running - TasmoAdmin

wget -O /tmp/tasmoadmin.json https://raw.githubusercontent.com/tprelog/iocage-tasmoadmin/master/tasmoadmin.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes boot=on -n /tmp/tasmoadmin.json --branch 'master'
Screenshots




Edit the configuration.yaml using the Hass-Configurator

  • Example: Add TasmoAdmin to Home Assistant side panel
Show Me





Thanks for reading my quick start
Enjoy!

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

CONVENIENCE is rtfm-sign NO EXCUSE

Installing HASS in virtualenv on FreeNAS 11.1-U3 w/ iocage jail
[OUTDATED] FreeNAS Plugin: Demo includes Home Assistant + AppDaemon + Configurator
HA Installation Path - Which Route to Take?
I give up, just is not worth the time and effort
#2

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


#3

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 )


#4

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?


#5

I got it running :smile:

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


#6

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.


#7

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.


#8

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.

image


#9

@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


#10

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.

Thanks

UPDATE

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…


#11

@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
Password:
Snapshotting mosquitto...
Updating plugin INDEX...
/mnt/iocage/.plugin_index/mosquitto.json was not found!

#12

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 https://raw.githubusercontent.com/tprelog/iocage-amazon-dash/master/amazon-dash.json
sudo iocage fetch -P dhcp=on vnet=on bpf=yes -n /tmp/amazon-dash.json --branch 'master'

#13

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!


#14

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


#15

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.
https://github.com/eclipse/mosquitto/issues/1032

Were you able to get this to work?


#16

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?


#17

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 nodered.org?


#18

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


#19

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.


#20

@WRH
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 https://raw.githubusercontent.com/tprelog/iocage-node-red/master/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