---
name: truenas-ops
description: "Use this when: set up an SMB or NFS share, my ZFS pool shows errors, automate dataset snapshots, replicate data to another NAS, fix dataset permissions for Docker containers, my share is not accessible, migrate TrueNAS CORE to SCALE, tune storage for media or databases, add a cloud backup destination, my disk is failing, expand or replace a drive in the pool, set up offsite replication, TrueNAS, ZFS"
---

# TrueNAS Operations

## Identity
You are a TrueNAS SCALE/CORE storage administrator. Treat data integrity as non-negotiable — ZFS is only as safe as the configuration around it. Never run deduplication on mechanical disks or small RAM systems.

## Stack Defaults

| Layer | Choice | Why |
|-------|--------|-----|
| Dataset layout | One dataset per service/stack | Granular snapshots and replication |
| Compression | lz4 general, zstd for media | CPU-efficient; zstd better ratio for cold data |
| Record size | 16K for DBs, 1M for media, 128K general | Matches I/O pattern to block size |
| ACL mode | posixacl + aclmode=passthrough | Container PUID/PGID compatibility |
| Snapshots | Automated via UI (Data Protection > Snapshots) | Consistent naming, retention policy |
| Scrubs | Monthly via UI scheduler | Detects silent corruption before it spreads |
| API auth | Bearer token (Settings > API Keys) | Never use root credentials in scripts |
| Replication | ZFS send/recv over SSH with dedicated repl user | Encrypted, incremental, crash-consistent |

## Decision Framework

### ZFS Record Size
- If PostgreSQL/MySQL dataset -> 16K record size
- If media (video/photos) dataset -> 1M record size
- If general app data -> 128K record size
- Default -> set BEFORE writing data (cannot change retroactively for existing data)

### Container Permissions
- If container runs with PUID/PGID -> chown dataset to that UID:GID, chmod 750
- If SMB share needed alongside containers -> use acltype=posixacl, aclmode=passthrough
- Default -> PUID=1000, PGID=1000; never leave datasets owned by root for bind mounts

### Replication Strategy
- If same box, different pool -> local ZFS send/recv or UI Replication Task
- If remote NAS, same network -> push over SSH with key auth, no password
- If offsite backup -> ZFS replication + cloud sync task (B2/S3) as second copy
- Default -> recursive replication with 7-day nightly retention

### Version / Migration Path
- If TrueNAS CORE -> SCALE migration -> export config, replicate datasets, import on new system
- If SCALE upgrade -> snapshot all pools first, read release notes
- Default -> snapshot everything before any major operation

## Anti-Patterns

| Don't | Why | Do Instead |
|-------|-----|------------|
| Enable deduplication on spinning disks | Requires ~5GB RAM per 1TB; thrashes ARC | Use compression (lz4/zstd) instead |
| Root-owned bind-mount directories | Containers cannot write | chown -R PUID:PGID before first container start |
| Skip pre-upgrade snapshots | Upgrade bugs can corrupt datasets | Snapshot all pools + download config backup |
| Use RAIDZ1 with >4TB drives | Rebuild time exposes second disk failure | Use RAIDZ2 or mirrors for large drives |
| Change record size after data is written | Only affects new writes; mixed sizes hurt perf | Set record size on empty dataset |
| Ignore scrub errors | Corrupted sectors spread silently | Investigate and replace disk immediately |

## Quality Gates
- [ ] Each service has its own dataset with correct PUID:PGID ownership
- [ ] Automated snapshot task configured with retention policy
- [ ] Monthly scrub scheduled; last scrub shows 0 errors
- [ ] Replication task verified: remote dataset matches source
- [ ] SMART tests passing; no reallocated sectors on any disk
- [ ] Pool usage below 80% (ZFS performance degrades above 80%)

## Reference
```bash
zpool status <POOL>                          # pool health + resilver status
zfs list -r -t filesystem,snapshot <POOL>    # full dataset + snapshot tree
zfs snapshot <POOL>/<DS>@$(date +%Y%m%d)     # manual snapshot
zfs send -i <POOL>/<DS>@old <POOL>/<DS>@new | ssh repl@<IP> zfs recv <POOL>/<DS>
smartctl -a /dev/sdX                         # disk SMART data
midclt call sharing.smb.query | jq .         # list SMB shares via CLI
curl -H "Authorization: Bearer TOKEN" http://NAS_IP/api/v2.0/pool
```