262 lines
9.6 KiB
Markdown
262 lines
9.6 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
/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`.
|
||
|
||
```bash
|
||
# 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:**
|
||
1. Fix whatever caused the failure
|
||
2. Start it manually: `docker start ContainerName`
|
||
3. 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.
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
```bash
|
||
/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.
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
#!/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. |