From c27b6ad50ba47379e8efd5da8a83755b824abce8 Mon Sep 17 00:00:00 2001 From: David Beitey Date: Sat, 13 Apr 2019 21:33:35 +1000 Subject: [PATCH] Update install docs for FreeNAS 11.2 (#9206) * Update install docs for FreeNAS 11.2 This includes some best-practice improvements (such as running Home Assistant as a limited-access user vs root), using Python 3.7 to install and adding a BSD-style service to manage and test configuration. * Fix typo --- source/_docs/installation/freenas.markdown | 133 ++++++++++++++++++--- 1 file changed, 115 insertions(+), 18 deletions(-) diff --git a/source/_docs/installation/freenas.markdown b/source/_docs/installation/freenas.markdown index 654f3e084db..9d775654029 100644 --- a/source/_docs/installation/freenas.markdown +++ b/source/_docs/installation/freenas.markdown @@ -1,6 +1,6 @@ --- layout: page -title: "Installation on FreeNAS 9.10" +title: "Installation on FreeNAS 11.2" description: "Installation of Home Assistant on your FreeNAS." date: 2017-06-20 11:00 sidebar: true @@ -9,45 +9,142 @@ sharing: true footer: true --- -[Freenas](http://www.freenas.org) 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. +[FreeNAS](https://www.freenas.org) 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 the FreeNAS 9.10. These instructions assume you already have a running and accessible jail. For more information on creating a jail follow the official FreeNAS 9.10.x documentation [HERE](https://doc.freenas.org/9.10/jails.html#adding-jails). Once you have the jail follow the steps below. +This has been tested on FreeNAS 11.2 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](https://www.ixsystems.com/documentation/freenas/11.2/jails.html). Once you have the jail available, follow the steps below. Directories used follow standard BSD conventions but can be adjusted as you wish. -Install the necessary Python Packages. +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. ```bash -# pkg update +# pw groupadd -n homeassistant -g 8123 +# echo 'homeassistant:8123:8123::::::/bin/csh:' | adduser -f - +``` + +Install the necessary Python packages: + +```bash +# pkg update -y # pkg upgrade -# pkg install python35 -# pkg install py35-sqlite3 -# python3.5 -m ensurepip +# pkg install -y python37 py37-sqlite3 ca_root_nss +# python3.7 -m ensurepip ``` -Install Home Assistant itself. +Create the configuration directory: ```bash -# pip3 install homeassistant +# mkdir -p /usr/local/homeassistant +# chown -R homeassistant:homeassistant /usr/local/homeassistant ``` -Create an `/etc/rc.local` file to enable Home Assistant to start when the jail starts. The command in `/etc/rc.local` can also be run in a terminal session but Home Assistant will exit when that session is closed. - +Create the installation directory: ```bash -# cd / && mkdir -p /home/.homeassistant +mkdir -p /usr/local/share/homeassistant +chown -R homeassistant:homeassistant /usr/local/share/homeassistant ``` +Install Home Assistant itself: + ```bash -# /usr/local/bin/hass --open-ui --config /home/.homeassistant/ & +# su homeassistant +% cd /usr/local/share/homeassistant +% source ./bin/activate.csh +% virtualenv -p python3.7 . +% pip3 install homeassistant +% deactivate +% exit ``` -Make `/etc/rc.local` executable so it runs on startup +Create an `rc.d` script for the system-level service that enables Home Assistant to start when the jail starts. Create a file at `/usr/local/etc/rc.d/homeassistant` with the following contents: ```bash -# chmod 755 /etc/rc.local +#!/bin/sh +# +# Based upon work by tprelog at https://www.ixsystems.com/community/resources/fn-11-2-iocage-home-assistant-jail-plugins-for-node-red-mosquitto-amazon-dash-tasmoadmin.102/ +# +# 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: homeassistant +# 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: homeassistant +# homeassistant_config_dir: Directory where config files are located. +# Default: /usr/local/homeassistant +# homeassistant_install_dir: Directory where Home Assistant is installed. +# Default: /usr/local/share/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:="homeassistant"} +: ${homeassistant_group:="homeassistant"} +: ${homeassistant_config_dir:="/usr/local/homeassistant"} +: ${homeassistant_install_dir:="/usr/local/share/homeassistant"} + +command="/usr/sbin/daemon" +start_precmd=${name}_precmd +homeassistant_precmd() +{ + rc_flags="-f -P ${pidfile} -p ${pidfile_child} ${homeassistant_install_dir}/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 + + echo "Performing check on Home Assistant configuration:" + eval "${homeassistant_install_dir}/bin/hass" --config "${homeassistant_config_dir}" --script check_config +} + +stop_postcmd=${name}_postcmd +homeassistant_postcmd() +{ + rm -f -- "${pidfile}" + rm -f -- "${pidfile_child}" +} + +run_rc_command "$1" ``` -Finally restart the jail from the FreeNAS GUI. +Make the `rc.d` script executable: + +```bash +# chmod +x /usr/local/etc/rc.d/homeassistant +``` + +Configure the service to start on boot and start the Home Assistant service: + +```bash +# sysrc homeassistant_enable="YES" +# service homeassistant start +``` + +You can also restart the jail to ensure that Home Assistant starts on boot.

-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 Hass. Just make sure the proper `/dev/cu*` is used in the Home Assistant `configuration.yaml` file. +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.