UNRAID Integration

ruaandeysel · October 21, 2024, 11:08am

Hello fellow Unraiders!

I’m excited to share a new custom integration I’ve developed that brings comprehensive Unraid server monitoring and control capabilities to Home Assistant.

Features

System Monitoring

Real-time system metrics:
- CPU usage and temperature
- RAM utilization
- Boot drive status
- Cache drive usage
- Array disk status
- Individual disk monitoring
Temperature sensors:
- CPU temperature tracking
- Motherboard temperature monitoring
UPS integration:
- Battery status
- Power monitoring

Docker Management

Complete Docker container control:
- Start/stop containers
- Monitor container status
- Execute commands within containers
- Container health monitoring

VM Control

Virtual Machine management:
- Start/stop VMs
- VM status monitoring
- Automated VM control

Command & Script Management

Advanced control capabilities:
- Execute shell commands
- Run user scripts
- Schedule automated tasks
- Background task execution

Installation

Add through HACS (recommended):
- Add custom repository: https://github.com/domalab/ha-unraid
- Install “Unraid Integration”
Manual installation:
- Download the repository
- Copy to your custom_components folder
- Restart Home Assistant

Documentation

Example Uses

Automated Backups

# Weekly backup automation
automation:
  - alias: "Weekly Unraid Backup"
    trigger:
      - platform: time
        at: "02:00:00"
    condition:
      - condition: time
        weekday: 
          - sun
    action:
      - service: unraid.execute_user_script
        data:
          entry_id: "YOUR_UNRAID_IP"
          script_name: "backup.sh"

Smart Power Management

# UPS monitoring automation
automation:
  - alias: "UPS Low Battery Shutdown"
    trigger:
      - platform: numeric_state
        entity_id: sensor.unraid_ups_battery
        below: 20
    action:
      - service: notify.notify
        data:
          title: "UPS Battery Critical"
          message: "Initiating safe shutdown"

Contributing

Contributions are welcome! Feel free to:

Report bugs
Suggest features
Submit pull requests
Share your automation examples

Future Plans

Enhanced Diagnostic Logging
More detailed temperature tracking
Extended disk health monitoring
Additional automation templates
Support for ZFS pools
Improved error handling

Feedback

I’d love to hear your thoughts and suggestions! Feel free to:

Share your use cases
Suggest improvements
Report any issues
Ask questions

Happy automating!

mase · October 21, 2024, 7:24pm

thanks, was looking for an easy way to see my containers

however VMs are always shown as offline. is that a bug or a problem on my side?

ruaandeysel · October 22, 2024, 12:44am

@mase Thanks for the feedback. On my system it appears to be working fine although bit of a delay when toggling the switches.

I’m looking into that delay issue to see if I can improve it.

I’ll also look at improving the VM state (stopped, running, paused) validation to see if that fixes the offline issue.

Which version of unraid are you using?

mase · October 22, 2024, 9:34am

i´m using v6.12.13, HA is on a VM.

ashie_tashi · October 23, 2024, 7:48am

Hey there! thanks for this!!

Im sorry for the dumb question, but where do i find the “Config Entry ID” to run a shell command?

ruaandeysel · October 23, 2024, 10:25am

Hello,

Please have a look here. It has a few examples.

How to use Unraid Service Commands

stephack · October 23, 2024, 10:41am

Hi @ruaandeysel . First off, thanks for sharing your project. We appreciate any work being done to integrate Unraid.
I’m curious to know if this integration is similar to the “Unraid API” from a few years ago that is no longer being maintained. We’ve all been waiting for Unraid to release an official api but I’m not holding my breath. Does this one integrate via web scraping similar to the old one or have you found a more efficient method?

ruaandeysel · October 23, 2024, 10:49am

Hello, this integration uses python ssh library to connect to your Unraid server to execute commands and retrieve info for the HA sensors and VM / Container controls.

I found it works better than the UNRAID API that scrapes the web portal and less complex.

ashie_tashi · October 24, 2024, 6:53am

Thank you for that!

Im struggling to run the “powerdown” command.
I get an unknown error when trying to run it via automation or dev tools.

data:
entry_id: 10.23.19.5
command: powerdown
action: unraid.execute_command

ruaandeysel · October 24, 2024, 7:22am

Maybe try it like this

service: unraid.execute_command
data:
  entry_id: "10.23.19.5"
  command: "shutdown -h now"

or

service: unraid.execute_command
data:
  entry_id: "10.23.19.5"
  command: "/sbin/powerdown"

ashie_tashi · October 24, 2024, 7:28am

Sadly no luck!

I get this error on running (so helpful! haha)

ruaandeysel · October 24, 2024, 8:18pm

FYI

Finding Your Entry ID

Go to Configuration → Integrations
Find your Unraid integration
Click on your device entity
Click on UNRAID under Device Info
The long string in the URL is your entry_id

Example URL: /config/integrations/integration/unraid#config_entry/1234abcd5678efgh
Your entry_id would be: 1234abcd5678efgh

ruaandeysel · October 24, 2024, 9:11pm

You gave me an idea.

I’m going to to add three new services to control Unraid:

Available Services

unraid.array_stop - Safely stop the Unraid array
unraid.system_reboot - Reboot the Unraid server
unraid.system_shutdown - Shutdown the Unraid server

wildenrou · October 25, 2024, 12:12am

just to say thanks for this amazing work, was waiting for such an integratio for a very long time. will be following closely new features / updates to come in the future. thanks again!

mvanlijden · October 25, 2024, 9:21am

Removed the buggy Unraid-API and the overcrowded Glances integration and installed this. I know you are still adding features, but your setup is great and very in line with HA design principles.

I appreciate all the effort and will keep updating this.
I posted a bug on github on drive health, before seeing that this is still a missing feature here.

ruaandeysel · October 25, 2024, 9:41am

I found a bug that’s causing the execute command service to fail. I’ll get a fix implemented asap.

Gurulee · October 25, 2024, 9:52am

This sounds awesome! I will definitely try it out.

Gurulee · October 25, 2024, 11:07am

Anyway to use unraid connected SmartUPS for power / energy power consumption stats?

ruaandeysel · October 25, 2024, 11:21am

Yes, it’s possible! If you have a Smart-UPS connected to your Unraid server, I can add power consumption monitoring. I just need to enhance the existing UPS monitoring in the Unraid integration to include these power metrics.

Not all UPS supports this type of monitoring so will need to figure out a detection mechanism.

Gurulee · October 25, 2024, 11:55pm

Love it!