9.6 KiB
Tools
Utility scripts for specific operational situations — recovery, repair, migration, and one-time tasks that don't fit the scheduled maintenance model of the other folders.
unRAID_Essentials/ — regular system maintenance, scheduled
Docker_Essentials/ — regular container management, scheduled
Monitors/ — regular health reporting, scheduled
Tools/ — situational utilities, run when needed
What Belongs Here
A script belongs in Tools when it:
- Solves a specific operational problem rather than ongoing maintenance
- Is run manually in response to a situation rather than on a schedule
- Is used rarely — recovery scenarios, repairs, migrations, initial setup
- Would be dangerous or meaningless to run routinely
- Doesn't fit cleanly into any of the other folders
Tools scripts are not scheduled. They sit here ready for when you need them.
Scripts
failover_state_reset.sh
Resets the failover state file to NORMAL manually.
/mnt/user/appdata/unraid_scripts/Tools/failover_state_reset.sh --status
/mnt/user/appdata/unraid_scripts/Tools/failover_state_reset.sh --dry-run
/mnt/user/appdata/unraid_scripts/Tools/failover_state_reset.sh
When you need this:
After failover testing, a failed handback, or manual intervention that left the state file inconsistent. The failover.sh state machine reads this file on every cycle — if it shows FAILOVER when the system is actually in NORMAL operation, the script will make incorrect decisions.
What it does: Rewrites the state file with state=NORMAL and clears all tier flags. Does NOT start or stop any containers — state file only.
⚠️ Verify first: Only run after manually confirming both servers are in their correct states — right containers running on the right server, DDNS pointing correctly. The reset doesn't check any of this — it just trusts you.
Confirmation required: Type YES to proceed — prevents accidental runs.
watchdog_skip_list_manager.sh
View and manage the persistent container skip list used by docker_watchdog.sh.
# View current skip list and restart history
/mnt/user/appdata/unraid_scripts/Tools/watchdog_skip_list_manager.sh --status
# Clear a specific container
/mnt/user/appdata/unraid_scripts/Tools/watchdog_skip_list_manager.sh --clear Authelia
# Clear everything
/mnt/user/appdata/unraid_scripts/Tools/watchdog_skip_list_manager.sh --clear-all
When you need this:
When a container hits the restart loop limit and gets added to the skip list — it stops being monitored until manually cleared. The --status view shows which containers are on the list and whether they're currently running, so you can see at a glance what needs attention.
After clearing a container:
- Fix whatever caused the failure
- Start it manually:
docker start ContainerName - The watchdog monitors it normally on the next cycle
Files managed:
/boot/config/system_watchdog_failed.db — skip list
/boot/config/container_restart_history.db — restart loop tracking
Both are cleared per-container or together. The restart history is also cleared when clearing a specific container — gives it a fresh slate for the loop protection window.
bulk_permissions_repair.sh
Applies correct permissions to a single share or specific path. Faster than running the full media_shares_permissions.sh which processes every share.
# Single share
/mnt/user/appdata/unraid_scripts/Tools/bulk_permissions_repair.sh /mnt/user/Movies
# Multiple shares
/mnt/user/appdata/unraid_scripts/Tools/bulk_permissions_repair.sh \
/mnt/user/Movies /mnt/user/Tv_Shows
# Dry run first
/mnt/user/appdata/unraid_scripts/Tools/bulk_permissions_repair.sh \
/mnt/user/Movies --dry-run
When you need this:
- A failed transfer left files owned by wrong user
- A container wrote files as root instead of
nobody:users - Manual file operations bypassed normal permission handling
- A new share needs permissions applied before the next nightly run
Uses PERMISSIONS_MODE and PERMISSIONS_OWNER from Master.conf — same values as the full permissions script. Applies chown before chmod to ensure correct ownership before mode change.
container_data_export.sh
Exports a container's appdata directory to a compressed tar archive. Stops the container before archiving for a clean consistent backup, restarts after.
/mnt/user/appdata/unraid_scripts/Tools/container_data_export.sh \
Emby \
/mnt/media-servers/Media_Server/Emby \
/mnt/user/Backups/
# Dry run — verify space and paths without stopping anything
/mnt/user/appdata/unraid_scripts/Tools/container_data_export.sh \
Emby \
/mnt/media-servers/Media_Server/Emby \
/mnt/user/Backups/ \
--dry-run
Output filename: ContainerName_YYYY-MM-DD_HH-MM.tar.gz
When you need this:
- Before a major container update you're not sure about
- Before migrating appdata to a different pool
- Before removing a container from the stack — archive its data first
- As a manual point-in-time backup before making significant config changes
Space check: Script estimates required space from appdata size × 1.1 and aborts if the output directory doesn't have enough free space. The container is not stopped until the space check passes.
Recovery: If archiving fails, the container is restarted before the script exits — it tries to leave things clean regardless of outcome.
emby_database_repair.sh
Stops Emby, runs SQLite integrity checks on all Emby databases, and restarts.
# Check and report (restarts Emby after)
/mnt/user/appdata/unraid_scripts/Tools/emby_database_repair.sh
# Dry run — detect config path and show what would be checked
/mnt/user/appdata/unraid_scripts/Tools/emby_database_repair.sh --dry-run
When you need this:
- Emby reports database errors in logs
- Unexpected Emby crashes with no clear cause
- Playback history or user data behaving strangely
- After a hard shutdown or power loss with Emby running
Databases checked:
| Database | Contains | If corrupted |
|---|---|---|
library.db |
Media library metadata | Delete — Emby rebuilds from media files |
users.db |
User accounts and settings | Delete resets all user accounts |
authentication.db |
API keys and sessions | Delete — keys regenerated on restart |
activity.db |
Activity log | Delete safely — log only |
Important: This script checks and reports. It does NOT automatically delete or repair corrupted databases — that requires judgment about which database is corrupted and whether you have a backup. The summary provides specific guidance per database type.
Config path detection: Automatically detects the Emby config path from Docker volume mounts — no configuration needed beyond TRANSCODE_EMBY_CONTAINER in Master.conf.
zfs_pool_scrub.sh
Triggers ZFS scrub on all pools (or a specific pool), waits for completion, and reports results.
# Scrub all pools (skips ZFS_REPORT_IGNORE_POOLS)
/mnt/user/appdata/unraid_scripts/Tools/zfs_pool_scrub.sh
# Scrub a specific pool
/mnt/user/appdata/unraid_scripts/Tools/zfs_pool_scrub.sh gaming
# Check current scrub status without starting a new one
/mnt/user/appdata/unraid_scripts/Tools/zfs_pool_scrub.sh --status
# Dry run — show which pools would be scrubbed
/mnt/user/appdata/unraid_scripts/Tools/zfs_pool_scrub.sh --dry-run
When you need this:
ZFS scrub reads every block on every pool and verifies checksums — it catches silent data corruption that would otherwise only surface when you try to read the corrupted data. Running monthly is recommended.
Safe to run while in use. Scrub does not interrupt normal I/O — it runs in the background at low priority. The script polls every 60 seconds until all scrubs complete, then reports errors found.
Pool filtering: Pools in ZFS_REPORT_IGNORE_POOLS are skipped during all-pool scrubs. To scrub an ignored pool explicitly, specify it by name.
Notifications:
- Clean completion — normal notification with pool count and duration
- Errors found — warning notification listing affected pools
Scheduled Summary
None. Tools are not scheduled — they run when needed.
Adding a New Tool
When you encounter a situation that required manual bash commands to resolve — write a tool. You'll face it again.
The pattern for a Tools script:
#!/bin/bash
# Short description of what situation this solves.
# When to run it.
# Any warnings about destructive operations.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../Master.conf"
source "$SCRIPT_DIR/../common.sh"
parse_args "$@"
# Always:
# 1. Check for root
# 2. Support --dry-run
# 3. Confirm before destructive operations (read -p "Type YES:")
# 4. Notify on completion
Good candidates for future tools:
array_migration.sh — move appdata from one pool to another
with container stop/start and path updates
emby_metadata_refresh.sh — trigger full library refresh via API
useful after storage changes
tailscale_rekey.sh — rotate Tailscale keys on both servers
with SSH key update on both ends
Philosophy
Tools exist because not every problem has a scheduled solution. Some things only need to happen once. Some things only happen after something goes wrong. Having a dedicated folder keeps the other folders clean and makes it obvious what runs routinely vs what runs situationally.
Write the tool when you solve the problem. Store it here. Find it at 2am when you need it again.