How to Use Unraid Service Commands

Unraid Service Commands

This document provides examples and usage information for the Unraid integration's service commands.

Finding Your Config Entry ID

There are two ways to specify the entry_id:

1. Single Unraid Instance: Use your Unraid server's IP address or hostname

   entry_id: "192.168.1.10"  # Your Unraid IP or hostname

2. Multiple Unraid Instances: Find the specific entry_id through Home Assistant

   • Go to Settings -> Devices & Services -> Unraid -> Configure
   • The URL will show: /config/integrations/integration/unraid_[entry_id]
   • Use the ID after unraid_ in your service calls

Execute Shell Command

The unraid.execute_command service executes shell commands directly on your Unraid server.

Service Data

Field	Type	Required	Description
entry_id	string	Yes	Your Unraid IP/hostname
command	string	Yes	The shell command to execute

Examples

# List contents of user share directory
service: unraid.execute_command
data:
  entry_id: "192.168.1.10"
  command: "ls -l /mnt/user/"

# Check system disk space
service: unraid.execute_command
data:
  entry_id: "192.168.1.10"
  command: "df -h"

# View last 50 lines of system log
service: unraid.execute_command
data:
  entry_id: "192.168.1.10"
  command: "tail -n 50 /var/log/syslog"

# Check array status
service: unraid.execute_command
data:
  entry_id: "192.168.1.10"
  command: "cat /proc/mdstat"

Execute Command in Container

The unraid.execute_in_container service executes commands inside Docker containers.

Service Data

Field	Type	Required	Description
entry_id	string	Yes	Your Unraid IP/hostname
container	string	Yes	Docker container name
command	string	Yes	Command to execute
detached	boolean	No	Run in detached mode (default: false)

Examples

# Check Plex Media Server logs
service: unraid.execute_in_container
data:
  entry_id: "192.168.1.10"
  container: "plex"
  command: "tail -n 50 /config/Plex Media Server/Logs/Plex Media Server.log"

# Restart Nginx process in container
service: unraid.execute_in_container
data:
  entry_id: "192.168.1.10"
  container: "nginx"
  command: "nginx -s reload"

# Run database backup in background
service: unraid.execute_in_container
data:
  entry_id: "192.168.1.10"
  container: "mariadb"
  command: "mysqldump -u root -p[password] --all-databases > /backup/full-backup.sql"
  detached: true

Execute User Script

The unraid.execute_user_script service runs scripts from your Unraid user scripts directory.

Service Data

Field	Type	Required	Description
entry_id	string	Yes	Your Unraid IP/hostname
script_name	string	Yes	Script filename
background	boolean	No	Run in background (default: false)

Examples

# Run backup script
service: unraid.execute_user_script
data:
  entry_id: "192.168.1.10"
  script_name: "backup_appdata.sh"

# Start media organization in background
service: unraid.execute_user_script
data:
  entry_id: "192.168.1.10"
  script_name: "organize_media.sh"
  background: true

# Run maintenance script
service: unraid.execute_user_script
data:
  entry_id: "192.168.1.10"
  script_name: "monthly_maintenance.sh"

Stop User Script

The unraid.stop_user_script service stops running user scripts.

Service Data

Field	Type	Required	Description
entry_id	string	Yes	Your Unraid IP/hostname
script_name	string	Yes	Script filename to stop

Examples

# Stop backup script
service: unraid.stop_user_script
data:
  entry_id: "192.168.1.10"
  script_name: "backup_appdata.sh"

# Stop media organization script
service: unraid.stop_user_script
data:
  entry_id: "192.168.1.10"
  script_name: "organize_media.sh"

Security Considerations

1. Command Injection:

   • Validate all user input before using in commands
   • Avoid using user-provided input directly in commands
   • Use proper escaping when necessary

2. Permissions:

   • Ensure user scripts have appropriate permissions
   • Don't run commands with unnecessary elevated privileges
   • Consider using restricted user accounts for scripts

3. Automation Safety:

   • Test commands manually before adding to automations
   • Add error handling in your scripts
   • Use the background option for long-running tasks

4. Monitoring:

   • Check Unraid logs for command execution results
   • Monitor script execution through Home Assistant's logs
   • Set up notifications for script completion/failure

Troubleshooting

1. Command Fails to Execute:

   • Check if the command works directly on Unraid
   • Verify SSH connection is working
   • Check user permissions

2. Container Commands Fail:

   • Ensure container is running
   • Verify container name is correct
   • Check if command is available in container

3. User Scripts:

   • Verify script exists in /boot/config/plugins/user.scripts/scripts
   • Check script permissions (should be executable)
   • Test script manually on Unraid first

4. Common Issues:

   • Path issues: Use absolute paths in commands
   • Permission denied: Check user/script permissions
   • Timeout: Use background: true for long operations