FreeNAS statistics and messages in Home Assistant

Following on from the previous guide on how to enable remote starting and shutting down of a FreeNAS I’ll be showing you how to view your FreeNAS statistics and messages in Home Assistant. For this guide I’m once again going to be using the FreeNAS API. The FreeNAS dashboard has evolved into a nice little visual hub for viewing important data but as I have Home Assistant open on my desktop a lot more often than the FreeNAS web interface I wanted to import and display that data in my UI. The sensor I’ll be setting up in this guide will give me a report of the following:

  • The name of my volume
  • The current status of my volume
  • The used percentage of my volume
  • Whether the volume is decrypted

Once you’ve understood the basics you’ll be able to add any of the values available through the FreeNAS API. Based on these values you can also set up notifications such as a push notification if you’re volume were to become unhealthy.

Setting up the FreeNAS sensor in Home Assistant

As I’m not executing any commands, such as shutting the system down, this setup will be using sensors and not rest_command. Any of the following variables can be enabled in using the RESTful integration (just add or remove them under the json_attributes):

  • status: The current status of the Volume
  • vol_guid: The volume’s Globally Unique Identifier
  • name: The volume’s name
  • used_pct: The percentage of used storage
  • used_si: The amount of storage currently used
  • is_decrypted: Whether the volume is decrypted or not
  • avail_si: Available storage
  • total_si: The volume’s total storage

To get this API call to work, I’ve once again referenced the username and password in my secret.yaml file. For more on that topic you can check out my previous guide here.

 sensor:
  - platform: rest
    name: freenas_report_full
    json_attributes:
      - name
      - status
      - used_pct
      - is_decrypted
    resource: http://IP -OF-YOUR-FREENAS/api/v1.0/storage/volume/VOLUME-NAME/?format=json
    value_template: '{{ value_json.status }}'
    username: !secret freenas_user
    password: !secret freenas_password
    authentication: basic
    headers:
      Content-Type: application/json

This code will create a new entity with the desired attributes. But, as you might find out, this isn’t very practical. With this entity you won’t be able to embed individual information in your Lovelace UI and you can’t easily use the values in automations. What I did was create a template sensor for each individual value.

Template sensors

Percent used

 sensor:
  - platform: template
    sensors:
      freenas_percent_used:
        friendly_name: Percent used
        value_template: '{{ states.sensor.freenas_report_full.attributes["used_pct"].title() }}'
        entity_id: sensor.freenas_report_full

Volume status

 sensor:
  - platform: template
    sensors:
      freenas_status:
        friendly_name: Status
        value_template: '{{ states.freenas_report_full.attributes["status"].title() }}'
        entity_id: sensor.freenas_report_full

FreeNAS version (full)

 sensor:
  - platform: rest
    name: fn_version_full
    scan_interval: 3600
    json_attributes: 
      - fullversion
      - name
      - version
    resource: http://192.168.1.10/api/v1.0/system/version/?format=json
    value_template: '{{ value_json.fullversion }}'
    username: !secret fn_user
    password: !secret fn_password
    authentication: basic
    headers:
      Content-Type: application/json

FreeNAS version (just version number)

 sensor:
  - platform: template
    sensors:
      fn_version:
        friendly_name: Version
        value_template: '{{ states.sensor.fn_version_full.state.split(" ")[0] }}'
        entity_id: sensor.fn_version_full

Final steps

And there we have. Our FreeNAS statistics and information on the system can now be displayed inside Home Assistant and used for automations, scripts, and notification.

Controlling a FreeNAS using Home Assistant

Update 13 December 2019: Changed mac_address to mac

Besides my application server running Proxmox VE I have a NAS (Network Attached Storage) containing plenty of media, backups of my photography, and many delicious recipes. My NAS is currently running the FreeNAS operating system and despite it’s many faults, I’ll be sticking to that OS for the foreseeable future. My NAS is far from perfect. In fact, it’s borderline embarrassing. I bought the cheapest case I could find and fitted the absolute minimum of hardware. It isn’t particularly quiet and nothing is dampened so during writes this thing gets loud. Seeing as it sits right next to where I sleep there’s no way of leaving it turned on 24/7. This is where Home Assistant enters the fray. I needed a way of remotely turning my FreeNAS on and off as it sits in a shelf that isn’t easy to reach. And this is what the endresult looks like in my Lovelace UI:

The FreeNAS switch in my Home Assistant

For this to work I’m using the FreeNAS API to trigger a system shutdown from Home Assistant. Turning on the FreeNAS is way easier thanks to Wake on LAN (WOL) integration in Home Assistant. Let me start by showing you how to use the WOL switch to turn on your FreeNAS instantly.

Turning on a FreeNAS using Home Assistant

If you’re considering implementing this I’m going to assume you are technically well versed and understand the basics of Home Assistant and FreeNAS. For the WOL switch to work you need to know the IP (though this is technically only optional) and MAC of your FreeNAS. To find out your MAC simply enter the command ifconfig in your FreeNAS’ shell and look for hwaddr. The IP is solely used for Home Assistant to figure out if your FreeNAS is turned on or not. So if you’re going to use the switch in the UI I’d recommend adding the IP.

 switch:
  - platform: wake_on_lan
    name: FreeNAS
    host: YOUR-FREENAS-IP
    mac: "XX:XX:XX:XX:XX:XX"

Turning off a FreeNAS using Home Assistant

Turning off a FreeNAS using Home Assistant is slightly more complex. There’s no reverse WOL or anything similar and no universal way of handling shutdowns so instead I’ve opted to use the FreeNAS API. To make the API call simply create a REST command containing the following details:

 rest_command:
  freenas_shutdown:
    url: http://IP-OF-YOUR-FREENAS/api/v1.0/system/shutdown/
    method: post
    username: !secret freenas_user
    password: !secret freenas_password
    headers:
      content-Type: application/json

As you might have noticed, I’ve used the secret file to store my credentials. I had to use root to get this API call to work. There might be a nicer and safer way of doing this. To do this simply open the secrets.yaml on your Home Assistant server and enter the following on a new line:

freenas_user: YOUR-ROOT-USER
freenas_password: YOUR-PASSWORD

Tying it all together in one switch

Now that the FreeNAS RESTful Command is complete it can be added to the switch created in the first step. To do so, simply add the turn_off variable at the end of the switch as seen below:

switch:
 platform: wake_on_lan
 name: FreeNAS
 host: YOUR-FREENAS-IP
 mac_address: "XX:XX:XX:XX:XX:XX"
 turn_off:
   service: rest_command.freenas_shutdown 

And there you have it, FreeNAS can now be controlled by Home Assistant. This switch can be used in automations using switch.turn_on, switch.toggle, and switch.turn_off and can be placed in the UI.