Varaverk/README-User_Script_Plug-in.md

User Scripts Setup

How to configure the unRAID User Scripts plugin to match the repository structure exactly. Matching names and categories between the plugin and the repo means your eyes find what they're looking for instantly — no mental translation between "what did I call it in the plugin" and "what's it called in git".

---

Required Plugins

Install both from Community Applications:

User Scripts — Andrew Zawadzki The base plugin. Runs scripts via the unRAID UI without command line access. Required.

User Scripts Enhanced — Kurotaku Adds category support, UI customization, and additional features. Required for category organization.

Both must be installed before setting up the script entries below.

---

Category Structure

Categories match the repository folder names exactly:

Failover
Monitors
Orchestrators
Rsync
Docker_Essentials
Media
Transcodes
Tools
unRAID_Essentials
Git

Create these categories in User Scripts Enhanced before adding scripts. When the plugin category and the repo folder name are identical, navigating between VS Code and the plugin requires zero mental overhead.

---

Script Entries

For each entry below:

1. Create a new User Script
2. Set the Name exactly as shown
3. Set the Category as shown
4. Paste the Script line into the script body
5. Set the Schedule as shown

---

Failover

Name	Schedule	Background
failover	At Startup of Array	✅ Yes — runs continuously
failover_test	None — run manually	❌ No

# failover
/mnt/user/appdata/unraid_scripts/Failover/failover.sh

# failover_test — always --dry-run first
/mnt/user/appdata/unraid_scripts/Failover/failover_test.sh --dry-run

⚠️ failover.sh must run as a background task. Set "Run in background" in the script settings. If run in foreground the plugin UI will hang waiting for it to complete — it never does, it loops forever.

---

Monitors

Name	Schedule
backup_verify	0 10 * * 0 (Sunday 10am)
bandwidth_monitor_report	0 11 * * 0 (Sunday 11am)
cert_monitor	0 9 * * 0 (Sunday 9am)
emby_session_report	0 11 * * 0 (Sunday 11am)
smart_health	0 7 * * 0 (Sunday 7am)
weekly_health_digest	0 8 * * * (8am daily)
zfs_memory_snapshot	0 6 * * 0 (Sunday 6am)

# backup_verify
/mnt/user/appdata/unraid_scripts/Monitors/backup_verify.sh

# bandwidth_monitor_report
/mnt/user/appdata/unraid_scripts/Monitors/bandwidth_monitor.sh --report

# cert_monitor
/mnt/user/appdata/unraid_scripts/Monitors/cert_monitor.sh

# emby_session_report
/mnt/user/appdata/unraid_scripts/Monitors/emby_session_report.sh

# smart_health
/mnt/user/appdata/unraid_scripts/Monitors/smart_health.sh

# weekly_health_digest
/mnt/user/appdata/unraid_scripts/Monitors/weekly_health_digest.sh

# zfs_memory_snapshot
/mnt/user/appdata/unraid_scripts/Monitors/zfs_memory_snapshot.sh

---

Orchestrators

Name	Schedule
daily_sync	0 1 * * * (1am daily)
media_management	0 2 * * * (2am daily)
transcode_management	*/3 * * * * (every 3 min)

# daily_sync
/mnt/user/appdata/unraid_scripts/Orchestrators/daily_sync.sh

# media_management
/mnt/user/appdata/unraid_scripts/Orchestrators/media_management.sh

# transcode_management
/mnt/user/appdata/unraid_scripts/Orchestrators/transcode_management.sh

---

Rsync

Name	Schedule
rsync_arrs_stack	As needed
rsync_critical_data	As needed
rsync_important_data	As needed
rsync_emby	As needed
rsync_gmer4lfe	As needed

# rsync_arrs_stack
/mnt/user/appdata/unraid_scripts/Rsync/rsync.sh /mnt/user/appdata-Failover/Arrs_Stack

# rsync_critical_data
/mnt/user/appdata/unraid_scripts/Rsync/rsync.sh /mnt/user/appdata-Failover/Critical-Data

# rsync_important_data
/mnt/user/appdata/unraid_scripts/Rsync/rsync.sh /mnt/user/appdata-Failover/Important-Data

# rsync_emby
/mnt/user/appdata/unraid_scripts/Rsync/rsync.sh /mnt/user/appdata-Failover/Emby

# rsync_gmer4lfe
/mnt/user/appdata/unraid_scripts/Rsync/rsync.sh /mnt/user/appdata-Failover/Gmer4Lfe

---

Docker_Essentials

Name	Schedule
docker_watchdog	*/15 * * * * (every 15 min)
docker_daily_restart	0 3 * * * (3am daily)
docker_weekly_restart	0 3 * * 0 (Sunday 3am)
docker_network_connect	At Startup of Array

# docker_watchdog
/mnt/user/appdata/unraid_scripts/Docker_Essentials/docker_watchdog.sh

# docker_daily_restart
/mnt/user/appdata/unraid_scripts/Docker_Essentials/docker_daily_restart.sh

# docker_weekly_restart
/mnt/user/appdata/unraid_scripts/Docker_Essentials/docker_weekly_restart.sh

# docker_network_connect
/mnt/user/appdata/unraid_scripts/Docker_Essentials/docker_network_connect.sh

---

Media

Name	Schedule
media_shares_permissions	None — called by media_management
media_cleaner_anime	None — called by media_management
media_cleaner_media	None — called by media_management
lidarr_cleanup	None — called by media_management
sonarr_cleanup	None — called by media_management
radarr_cleanup	None — called by media_management

# media_shares_permissions
/mnt/user/appdata/unraid_scripts/Media/media_shares_permissions.sh

# media_cleaner_anime
/mnt/user/appdata/unraid_scripts/Media/media_cleaner.sh anime

# media_cleaner_media
/mnt/user/appdata/unraid_scripts/Media/media_cleaner.sh media

# lidarr_cleanup — always --dry-run first
/mnt/user/appdata/unraid_scripts/Media/lidarr_cleanup.sh --dry-run

# sonarr_cleanup — always --dry-run first
/mnt/user/appdata/unraid_scripts/Media/sonarr_cleanup.sh --dry-run

# radarr_cleanup — always --dry-run first
/mnt/user/appdata/unraid_scripts/Media/radarr_cleanup.sh --dry-run

These scripts are called automatically by media_management.sh. Individual entries exist so you can run them manually for testing or one-off maintenance without triggering the full orchestrator.

---

Transcodes

Name	Schedule
ramdisk_setup	At Startup of Array
transcode_manager	None — called by transcode_management
transcode_cleanup	None — called by transcode_management

# ramdisk_setup
/mnt/user/appdata/unraid_scripts/Transcodes/ramdisk_setup.sh

# transcode_manager — run individually if needed
/mnt/user/appdata/unraid_scripts/Transcodes/transcode_manager.sh

# transcode_cleanup — run individually if needed
/mnt/user/appdata/unraid_scripts/Transcodes/transcode_cleanup.sh

⚠️ ramdisk_setup.sh must run before Emby starts at array start. Ensure it is ordered before any Emby-related startup scripts in the User Scripts plugin. If Emby starts before the ramdisk is created it will write transcoding-temp to the SSD fallback path and all sessions will land on SSD until Emby restarts.

---

Tools

Name	Schedule
failover_state_reset	None — run manually
watchdog_skip_list_manager	None — run manually
bulk_permissions_repair	None — run manually
container_data_export	None — run manually
emby_database_repair	None — run manually
recreate_shares	None — run manually
zfs_pool_scrub	None — run manually

# failover_state_reset — check status first
/mnt/user/appdata/unraid_scripts/Tools/failover_state_reset.sh --status

# watchdog_skip_list_manager — check status first
/mnt/user/appdata/unraid_scripts/Tools/watchdog_skip_list_manager.sh --status

# bulk_permissions_repair — specify share path
/mnt/user/appdata/unraid_scripts/Tools/bulk_permissions_repair.sh /mnt/user/ShareName

# container_data_export — specify container and paths
/mnt/user/appdata/unraid_scripts/Tools/container_data_export.sh ContainerName /path/to/appdata /path/to/output

# emby_database_repair
/mnt/user/appdata/unraid_scripts/Tools/emby_database_repair.sh

# recreate_shares
/mnt/user/appdata/unraid_scripts/Tools/recreate_shares.sh

# zfs_pool_scrub
/mnt/user/appdata/unraid_scripts/Tools/zfs_pool_scrub.sh

---

unRAID_Essentials

Name	Schedule
system_watchdog	*/15 * * * * (every 15 min)
webgui_restart	*/10 * * * * (every 10 min)
docker_syslog_filter	At Startup of Array
php_fpm_max_children	At Startup of Array
clear_logs	0 5 * * 0 (Sunday 5am)
mover_stop	None — run manually
rsync_stop	None — run manually
server_reboot	None — run manually
user_scripts_stop	None — run manually

# system_watchdog
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/system_watchdog.sh

# webgui_restart
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/webgui_restart.sh

# docker_syslog_filter
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/docker_syslog_filter.sh

# php_fpm_max_children
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/php_fpm_max_children.sh

# clear_logs
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/clear_logs.sh

# mover_stop
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/mover_stop.sh

# rsync_stop
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/rsync_stop.sh

# server_reboot
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/server_reboot.sh

# user_scripts_stop
/mnt/user/appdata/unraid_scripts/unRAID_Essentials/user_scripts_stop.sh

---

Git

Name	Schedule
git_pull_execute	None — run manually after pushing changes

# git_pull_execute
/mnt/user/appdata/unraid_scripts/git_pull_execute.sh

This is the deployment mechanism for the entire ecosystem. After pushing changes to Gitea from VS Code — run this on both servers. Both pull the latest scripts and set executable permissions automatically.

---

At Startup of Array — Order Matters

Scripts that run at array start must be ordered correctly. In User Scripts Enhanced you can drag to reorder. The required order:

1. ramdisk_setup          — ramdisk must exist before Emby starts
2. docker_syslog_filter   — suppress veth noise before containers start
3. php_fpm_max_children   — WebGUI tuning before anyone accesses it
4. docker_network_connect — connect containers after Docker is ready
5. failover               — background task, starts monitoring loop

---

After Rebuilding

Once all entries are created and scheduled, verify by running each script once manually from the plugin UI before relying on the scheduled runs. Use --dry-run for anything destructive before running live.

The scheduled scripts that matter most to verify first:

transcode_management  — runs cleanup then manager, check output is clean
docker_watchdog       — check all required containers show running
system_watchdog       — check no threshold alerts on first run
daily_sync            — run manually, verify remote connectivity