unraid

What this skill does

# Unraid

Unraid is a storage-first operating system. Every decision flows from how data is stored, protected, and accessed.
Understand the storage layer before touching Docker, VMs, or shares.

## References

Extended configuration details, command examples, and decision tables live in the references directory.

- **Array and storage** — [`${CLAUDE_SKILL_DIR}/references/array-and-storage.md`] Storage architecture comparison, write
  modes with speed benchmarks, cache strategies, allocation methods, split level, ZFS configuration, SSD limitations,
  RAIDZ expansion (7.2), foreign ZFS import (7.1), external FS support (7.2), encryption
- **Docker containers** — [`${CLAUDE_SKILL_DIR}/references/docker-containers.md`] Network modes, macvlan vs ipvlan
  stability, custom networks, Docker Compose Manager plugin workflow, native Compose roadmap, Traefik integration, VPN
  container routing, fork bomb prevention, overlay2 on ZFS, volume mappings, startup management
- **VM management** — [`${CLAUDE_SKILL_DIR}/references/vm-management.md`] BIOS/machine types, vDisk types, GPU
  passthrough setup, IOMMU group risks, ACS override caveats, CPU pinning, IOThreads, NUMA, SR-IOV, snapshots,
  templates, VM backup
- **Shares and permissions** — [`${CLAUDE_SKILL_DIR}/references/shares-and-permissions.md`] Security levels, share
  creation workflow, export visibility options, Windows SMB considerations, NFS configuration, user access control,
  flash device security
- **Plugins and scripts** — [`${CLAUDE_SKILL_DIR}/references/plugins-and-scripts.md`] Plugin catalog, script scheduling
  options, automation patterns, Docker template XML, notification agents, heartbeat monitoring, script repositories
- **Security and networking** — [`${CLAUDE_SKILL_DIR}/references/security-and-networking.md`] SSL hardening, port
  security, remote access methods (Tailscale/WireGuard), Wi-Fi (7.1), OIDC/SSO (7.2), 3-2-1 backup rule, offsite tools
  (Borgmatic/Kopia/Restic), UPS/NUT integration, official GraphQL API (7.2), MCP agent, WebGUI features

## Storage Architecture

Unraid supports three storage approaches. Choose based on workload:

- **Traditional array (XFS/BTRFS + parity)** — Growing media collections, power efficiency matters, easy expansion
- **ZFS pools** — Data integrity critical, multi-user throughput, snapshots needed
- **Hybrid (array + ZFS pools)** — Mixed workloads — fast pool for active data, array for cold storage

Unraid 7+ supports **array-free operation** for all-SSD/NVMe builds using only pools.

### Parity

- Parity drives must be >= largest data drive
- Single parity: one drive failure. Dual parity: two drive failures
- Schedule monthly parity checks via Settings > Scheduler
- **Parity is not a backup** — protects against drive failure only

### Write Modes

- **Read/Modify/Write** (default) — 20-40 MB/s, low power (2 drives). Most workloads, energy savings
- **Turbo Write** (Reconstruct) — 40-120 MB/s, high power (all drives). Large transfers, array rebuilds
- **Cache Write** (SSD/NVMe) — 50-900 MB/s, varies. Apps, VMs, frequent writes

Enable Turbo Write: Settings > Disk Settings > Tunable (md_write_method).

### Cache and Pools

- Store `docker.img` and `appdata` on cache pool for performance
- Use Mover to transfer files between cache and array on schedule
- **Mover Tuning plugin**: prevents moves when cache below threshold, supports age-based filtering (e.g., only move
  files older than 40 days)
- ZFS pools enable snapshots, lz4 compression, self-healing, and RAIDZ expansion (7.2)
- Files on cache are unprotected by parity until moved — back up appdata separately
- **SSDs in array are unsupported** — no TRIM/Discard, causes degradation. Use SSDs only in cache pools or as unassigned
  devices
- **External FS support** (7.2): NTFS, exFAT, EXT2/3/4 drives can be added to array with data intact (before parity is
  assigned)

### Allocation

- **High-Water** (default): progressively fills disks. **Most-Free**: spreads across disks. **Fill-Up**: sequential
- Set Minimum Free Space to 2x largest file size
- Split Level controls directory distribution — takes priority over free space
- See the array and storage reference for detailed allocation methods and split level options

## Docker Containers

### Network Modes

- **Bridge** (default) — Most applications; safest, only mapped ports exposed
- **Host** — Application requires direct network stack access
- **Custom** (macvlan/ipvlan) — Service needs its own LAN IP (Pi-hole, Home Assistant)
- **None** — Isolated workloads with no network needs

Only modify the **host port** in bridge mode, not the container port.

### macvlan vs ipvlan

macvlan on `br0` causes kernel call traces and crashes — switch to ipvlan (default since 6.11.5) or disable bridging.
See the Docker containers reference for detailed migration steps.

Enable **Host access to custom networks** in Settings > Docker if containers with custom IPs need to reach the Unraid
host.

### Docker Compose

Unraid's native Docker management uses XML templates. Docker Compose is community-supported via the **Docker Compose
Manager plugin** (install from CA). Compose containers cannot be edited via WebGUI — all changes must be made in YAML.
See the Docker containers reference for full setup workflow and limitations.

### Volume Mappings

- Store app config in `/mnt/user/appdata/<app>` mapped to `/config`
- Use **read-only** access mode unless write is required
- Reference container paths in application settings, not host paths
- Paths are case-sensitive: `/mnt/user/Media` != `/mnt/user/media`
- Never hardcode secrets in images — use environment variables (`PUID`, `PGID`, `TZ`)

### Startup Order

Order containers by dependency (database before app, VPN before dependent services). Set wait times between starts in
Advanced View on the Docker tab.

### Custom Docker Networks

Create custom bridge networks for inter-container DNS resolution and isolation. Preserve across restarts with a User
Script at array start. See the Docker containers reference for setup details.

## Reverse Proxy

- **Traefik**: Docker labels for dynamic routing and automatic SSL. Mount Docker socket read-only. Best for IaC/Compose
  workflows
- **Nginx Proxy Manager**: GUI-based, simpler setup, manual per-service config. Best for users who prefer visual
  configuration

## Virtual Machines

### Prerequisites

- Enable IOMMU (Intel VT-d / AMD-Vi) in BIOS
- Upload OS ISOs and VirtIO drivers to `isos` share
- Use OVMF (UEFI) for modern OSes and GPU passthrough
- Use Q35 machine type for Linux VMs and GPU passthrough

### GPU Passthrough

1. Bind GPU + audio device to vfio-pci: Tools > System Devices
2. Reboot after binding
3. Select bound GPU in VM settings, assign USB keyboard/mouse
4. If black screen: switch to OVMF + Q35, then try manual ROM injection as last resort

**IOMMU group risks**: on consumer motherboards, the GPU may share an IOMMU group with the SATA controller — binding it
to a VM strips the host of disk access. ACS Override splits groups but bypasses hardware isolation. See the VM
management reference for detailed risks and safer alternatives.

### Performance Tuning

- **CPU pinning**: assign dedicated cores to VMs, avoid core 0
- **IOThreads**: enable VirtIO IOThreads for up to 20% latency reduction
- **NUMA pinning**: place vCPU, IOThreads, and memory on same NUMA node as storage controller for 5%+ IOPS improvement
- **VirtIO drivers**: install paravirtualized drivers for Windows VMs (auto-attach ISO via Settings > VM Manager)
- **QEMU Guest Agent**: install in Windows VMs for graceful shutdown/hibernation

### Snapshots (Unraid 7+)

- Require QCOW2 vDisk format
- Create before significant changes (updates, software installs)
- Revert to restore state, Block Commit to make changes permanent
- Not a backup replacement — complement with VM XML + NVRAM backups

### GPU Sharing (Unraid 7+)

- **VirGL**: share Intel/AMD GPU among Linux VMs (no physical output, no Windows)
- **SR