Register for the iXsystems Community to get an ad-free experience and exclusive discounts in our eBay Store.
Resource icon

FN 11.2 iocage -- Home Assistant jail & plugins for Node-RED, Mosquitto, Amazon-Dash, TasmoAdmin

I've been doing a better job updating this post in the Home Assistant forms. Originally this started simply as a manual installation guide and over several versions has grown to include more information on configuring the FreeNAS host system as well. For example, configuring a dataset to contain Home Assistant configuration that could then be shared over a network to easily edit the files from outside the jail. A more recent example is configuring a custom devfs_ruleset on FreeNAS to unhide a USB z-wave controller inside the jail.

Some of these tasks related to Home Assistant do provide, in my opinion, a better user experience. However they are technically optional and may be out of scope for that forum. I also find myself referring to this guide while creating and managing other jails, leading to me think this could hopefully be a worthy FreeNAS Resource. Even though this is mainly about Home Assistant on FreeNAS, I'm hoping some of these individual steps can provide useful examples in general.

Setting up a clean install of FreeNAS is not the intention of this resource however only minimal configuration is required. I started with a clean install of FreeNAS on a VM as I went through this guide. I'm only using a VM for testing. This is not recommend for daily use

This quick start guide assumes
- you have setup a storage pool
- you have created a user account

My setup for this guide
- 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 used later for network access to edit Home Assistant configuration files


Typically, the jail or plugin user & group name is similar to the service application name running inside the jail. Also, the UID and GID are usually the same as the port number used by the service.

Steps in this guide, or using my install script for Home Assistant will be creating a jail user & group hass with a UID/GUID of 8123 matching the default Home Assistant port.


Getting Started
This "Getting Started" section covers some additional FreeNAS configuration and is technically optional. 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. Some tasks may require additional steps not mentioned if performed after Home Assistant is running.

Create a dataset that can be added as storage inside the jail at /home/hass. This dataset can be shared over network to allow FreeNAS user troy to easily access and edit the Home Assistant configuration files from outside the jail
Add the hass group to FreeNAS
The hass group can be used to allow FreeNAS user troy Read/Write access to the Home Assistant configuration files.

gs1_add-group-01.png


gs1_add-group-02.png



Create the dataset for hass

gs2_add-dataset-01.png

gs2_add-dataset-02.png



Share the dataset via samba (network)

gs3_share-dataset-01.png

gs3_share-dataset-02.png

Using a USB Z-Wave or Zigbee controller
On FreeNAS 11.2-RELEASE iocage jails, by default, have only a limited number of host devices exposed in /dev. USB z-wave and zigbee devices are not in this list. This means devices like Aeotec Gen-5 USB Stick, Nortek HUSZB-1 and similar devices will require a custom devfs_ruleset which will unhide cua* devices.
List of devices inside jail with default settingsdevfs_ruleset=4
Code:
sudo iocage exec homeassistant ls /dev

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


For zwave and zigbee USB devices to work we only only need to (expose) unhide /dev/cua* devices. To achieve this we can use a custom devfs_ruleset. I am using the GoControl HUSBZB-1 which is both a zwave and zigbee radio. The zwave radio /dev/cuaU0 and the zigbee radio is /dev/cuaU1.

List of devices inside jail after using a custom devfs_ruleset

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


A few quick notes before we create our custom devfs_ruleset.
- Actually we are creating a script that will create the custom devfs_ruleset for us
- The name of this script can be changed if desired. Here I will use zwave-ruleset.sh
- This will create devfs_ruleset 99 on FreeNAS.
- I'm using 99 because it seems unlikely this would other wise be used by the host.
- Only rulesets 1-4 are defined in /etc/defaults/devfs.rules but I have no idea what voodoo the middle-ware is performing

First create a simple script zwave-ruleset.sh on your FreeNAS. This as mentioned is what will actually create the custom ruleset. I just used the FreeNAS console and created this file in my home directory with the following contents - Note changing 99 in ruleNum=99 allows changing the ruleset number if needed.

ee zwave-ruleset.sh
Code:
#!/bin/sh
# This script creates a custom devfs_ruleset with this NUMBER

# Set NUMBER
ruleNum=99

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


Be sure to make the script executable
Code:
chmod +x zwave-ruleset.sh


Simply running this script from the console can be used to immediately create the ruleset FreeNAS but these changes will be lost after reboot. That's OK for now. We'll fix that shortly by adding this as a start-up script in the FreeNAS GUI.
Code:
sudo sh zwave-ruleset.sh


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

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


By adding zwave-ruleset.sh as a startup script in the FreeNAS GUI, the custom ruleset can be automatically recreated during every (re)boot.

gs4_zwave-ruleset-01.png


You can set a jail to use the custom ruleset at creation by adding the devfs_ruleset=99

If you're jail is already created you just need to set the jail to use new ruleset. You can do this from the FreeNAS GUI or from the console. You'll need to restart the jail before it will use the new ruleset.
Here I find the console quicker. The jail name is homeassistant.

Code:
sudo iocage set devfs_ruleset=99 homeassistant
sudo iocage restart homeassistant


Installing Home Assistant
There are several options for installing Home Assistant on FreeNAS.

Scripted Install - iocage standard-jail Recommended installation method
The script is based on the manual installation method with a few extras including simple console menu to manage updates.
The install script also includes options to install App-Daemon (includes HA-Dashboard) and(or) Hass-Configurator and includes an option to use pre-configured example files. These files are intended as simply a minimum configuration to provide an "out of the box" working experience for AppDaemon and Hass-Configurator. Configuration files are required for appdaemon (ha-dashboard) and the hass-configurator to start. Any of these files are intended to be edited or replaced by you the end user. There is a legacy api password set in the secrets file! Again this is just to provide an "out of the box" working configuration for appdaemon and hass-configurator. At minimum you must change this password to something that is your own! Both appdaemon and hass-configurator also support long live access tokens which may be preferred over legacy api password.


Download pkg-list and create a jail using it to install requirements
Code:
wget -O /tmp/pkglist.json https://raw.githubusercontent.com/tprelog/iocage-homeassistant/11.2-RELEASE/pkg-list.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
Code:
sudo iocage fstab -a homeassistant "/mnt/tank/user/hass /home/hass nullfs rw 0 0"


Next git the script and begin the install
Code:
sudo iocage exec homeassistant git clone -b 11.2-RELEASE https://github.com/tprelog/iocage-homeassistant.git /root/.iocage-homeassistant
sudo iocage exec homeassistant bash /root/.iocage-homeassistant/post_install.sh standard


Simply answer questions to choose what gets installed
Code:
    Install Home-Assistant?  [Y/n]:
    Install Hass-Configurator?  [Y/n]:
    App-Daemon & HA-Dashboard?  [Y/n]:
    Use the pre-configured examples?  [Y/n]:


Profit!

1547832752045.png

1547833073474.png
- Only available from the scripted install
- Works from FreeNAS console
sudo iocage exec homeassistant bash update
1547833103365.png

Manual install - iocage standard-jail
Manual install updated for FreeNAS 11.2

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
Code:
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.
Code:
iocage fstab -a homeassistant "/mnt/tank/user/hass /home/hass nullfs rw 0 0"


Install jail requirements
Log into the homeassistant JAIL console
Code:
sudo iocage console homeassistant


Install requirements for Home-Assistant and Z-Wave
Code:
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
Code:
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.
Code:
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 "Home-Assistant Daemon"


Install pip requirements and create directory to install Home Assistant virtualenv
Code:
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!
Code:
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
Code:
mkdir -p /usr/local/etc/rc.d
ee /usr/local/etc/rc.d/homeassistant

Code:
#!/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"

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 -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
Code:
chmod +x /usr/local/etc/rc.d/homeassistant
sysrc homeassistant_enable=yes


Finally we can start Home-Assistant
Code:
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`)

Code:
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 | -   | -        |
    +-----+---------------+------+-------+------+-----------------+---------------------+-----+----------+


Managing your Home Assistant jail
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
Code:
sudo iocage restart -s homeassistant

You can also start or stop the jail.
Code:
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 homeassistant@2018.10.03
Code:
sudo iocage snapshot homeassistant -n $(date +%Y.%m.%d)


List snapshots in homeassistant
Code:
sudo iocage snaplist homeassistant


Rollback to previous snapshot
Code:
sudo iocage stop homeassistant
sudo iocage rollback homeassistant -n 018.10.03
sudo iocage start homeassistant


Remove snapshot from homeassistant
Code:
sudo iocage snapremove homeassistant -n 018.10.03


Update or Upgrade Jail RELEASE
update the Jail for example from 11.1-RELEASE-p10 to 11.1-RELEASE-p14
Code:
sudo iocage update homeassistant

upgrade the Jail for example from 11.1-RELEASE-p10 to 11.2-RELEASE-p3
Code:
sudo iocage upgrade -r 11.2-RELEASE homeassistant



These commands are run from the JAIL console
Login to JAIL console

Code:
sudo iocage console homeassistant

No longer use sudo since you're now logged in as root inside the jail

Control the installed service(s)
Home-Assistant
Code:
service homeassistant [start|stop|status|restart]


AppDaemon\HA-Dashboard
Code:
service appdaemon [start|stop|status|restart]


Hass-configurator
Code:
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
Code:
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:
Code:
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:
Code:
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
Code:
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
Code:
pkg update && pkg install zip

create backup as user hass
Code:
su - hass
  zip -9 -q -r homeassistant-backup /home/hass/homeassistant -x"components/*" -x"deps/*" -x"home-assistant.log"
  exit


Separate iocage-plugins for other things I use along with Home Assistant.
- Updated plugins for FreeNAS 11.3 can be found here

Create a separate iocage plugin for FreeNAS running - Eclipse Mosquitto
Code:
wget -O /tmp/mosquitto.json https://raw.githubusercontent.com/tprelog/iocage-mosquitto/11.2-RELEASE/mosquitto.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/mosquitto.json
Create a separate iocage plugin for FreeNAS running - Amazon Dash
Code:
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 vnet_default_interface=auto bpf=yes boot=on -n /tmp/amazon-dash.json --branch 'master'
Create a separate iocage plugin for FreeNAS running - Node-RED
Code:
wget -O /tmp/node-red.json https://raw.githubusercontent.com/tprelog/iocage-node-red/11.2-RELEASE/node-red.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/node-red.json
Create a separate iocage plugin for FreeNAS running - Tasmo Admin
Code:
wget -O /tmp/tasmoadmin.json https://raw.githubusercontent.com/tprelog/iocage-tasmoadmin/11.2-RELEASE/tasmoadmin.json
sudo iocage fetch -P dhcp=on vnet=on vnet_default_interface=auto bpf=yes boot=on -n /tmp/tasmoadmin.json

Thanks for reading!

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

- FreeNAS --- iocage
- Home Assistant
- Hass-Configurator
- AppDaemon
- HA-Dashboard
- Amazon Dash
- Node-RED
- Tasmo Admin
Author
tprelog
Views
2,021
First release
Last update
Rating
5.00 star(s) 3 ratings

Latest reviews

I'd used this guide on the Home Assistant forum, and it's pretty much perfect now! If only I had the time to learn enough about and configure Home Assistant to do more than I currently use it for!!
Thanks for making this easy!

For those of us running: FreeNAS-11.2-U2 (Build Date: Feb 14, 2019 20:8)

you need to add the following option vnet_default_interface="auto" to the iocage create command.

(See below)
iocage create -r 11.2-RELEASE boot=on dhcp=on bpf=yes vnet=on vnet_default_interface="auto" -p /tmp/pkglist.json -n homeassistant
tprelog
tprelog
Thanks for the tip about vnet_default_interface="auto". I'll update the resource to include this
flawless - I used this with 11.2 and everything just worked. I added zwave, ios and a tplink switch with no problems. That's the first time that has happened for me with HA and I've used it with several platforms. Love your work :-)
Top