TrueNAS SCALE

Tutorial completo, em português, para montar um servidor de armazenamento com TrueNAS SCALE — desde a escolha do hardware até replicação, apps Docker e operação em VM no Proxmox. Foco em uso doméstico ou em laboratório “sério”: NAS de mídia, destino de backups (incluindo Time Machine), datasets para apps em Docker, e replicação para um segundo nó.

Versões cobertas: TrueNAS SCALE 24.10 (Electric Eel) e TrueNAS SCALE 25.04 (Fangtooth) — ambas baseadas em Debian Linux + OpenZFS + Docker (a partir da 24.10, k3s foi removido).

1. Visão geral

1.1 TrueNAS CORE vs TrueNAS SCALE

A TrueNAS Fangtooth (25.04) unificou a comunidade: e o upgrade recomendado tanto para quem vinha do SCALE 24.10 quanto para quem ainda estava no CORE 13.x. Para deployments novos, use SCALE 25.04 (ou superior). Este tutorial assume SCALE.

1.2 Casos de uso

• NAS de mídia — biblioteca Plex/Jellyfin com share SMB/NFS para acesso na LAN.
• Destino de backup — repositorio para restic, borg, rclone, snapshots zfs send, Time Machine (macOS), Veeam, Proxmox Backup Server (PBS pode usar NFS exportado).
• Datasets para apps Docker — Plex, Jellyfin, Nextcloud, Vaultwarden, Home Assistant, *arr stack, instalados via App Catalog ou via custom YAML (Docker Compose).
• Hypervisor leve — VMs KVM para servicos pontuais (DNS, Pi-hole, AdGuard, etc).
• Replicacao off-site — replicar snapshots ZFS via SSH/Netcat para outro TrueNAS (3-2-1).

1.3 O que NAO usar TrueNAS para

• Single-disk “NAS” sem redundancia — ZFS brilha com VDEVs redundantes; sem isso, perde-se metade do valor.
• Workloads de banco de dados de baixa latencia direto no pool sem SLOG NVMe.
• Substituto de hypervisor principal — KVM funciona, mas Proxmox e mais flexivel; deixe TrueNAS focado em storage.

2. Arquitetura

2.1 Stack completo

flowchart TB
  subgraph HW[Hardware]
    CPU[CPU x86_64<br/>4+ cores]
    RAM[ECC RAM<br/>16-64 GB]
    HBA[HBA LSI 9211-8i<br/>IT mode]
    BOOT[Boot SSD<br/>SATA/NVMe separado]
    DATA[(Discos NAS<br/>WD Red Plus / IronWolf)]
    UPS[UPS NUT]
  end

  subgraph OS[TrueNAS SCALE 25.04]
    KERNEL[Debian + OpenZFS]
    MIDDLEWARE[middlewared API + WebUI 443]
    DOCKER[Docker engine]
    LIBVIRT[libvirt/KVM]
  end

  subgraph POOL[ZFS Pools]
    BOOTPOOL[boot-pool<br/>SSD]
    TANK[pool: tank<br/>VDEV raidz2]
  end

  subgraph DS[Datasets / Zvols]
    MEDIA[/mnt/tank/media]
    BACKUP[/mnt/tank/backup]
    TM[/mnt/tank/timemachine]
    APPS[/mnt/tank/apps]
    ISCSI[zvol/iscsi-vm1]
  end

  subgraph SHARES[Compartilhamentos & Apps]
    SMB[SMB / Time Machine]
    NFS[NFS v4]
    ISCSITGT[iSCSI target]
    APPSRUN[Apps Docker<br/>Plex, Nextcloud...]
  end

  REPL[(TrueNAS secundario<br/>replicacao ZFS)]

  CPU --> KERNEL
  RAM --> KERNEL
  HBA --> DATA
  BOOT --> BOOTPOOL
  DATA --> TANK
  UPS -.NUT.-> MIDDLEWARE

  KERNEL --> BOOTPOOL
  KERNEL --> TANK
  TANK --> MEDIA
  TANK --> BACKUP
  TANK --> TM
  TANK --> APPS
  TANK --> ISCSI

  MEDIA --> SMB
  TM --> SMB
  BACKUP --> NFS
  ISCSI --> ISCSITGT
  APPS --> APPSRUN

  TANK -.zfs send/recv via SSH.-> REPL

2.2 Modelos de implantacao

3. Hardware

3.1 CPU

• Arquitetura: x86_64 (Intel/AMD). ARM nao e oficialmente suportado.
• Cores: 4 cores e o piso pratico. 6-8 confortavel para SMB + apps. Se for rodar muitos apps (Plex transcoding, Nextcloud, *arr), 8+ cores.
• Recursos uteis: AES-NI (cripto SMB/dataset encryption), Intel QuickSync ou AMD VCN (transcoding Plex/Jellyfin).

3.2 RAM

• Minimo oficial: 8 GB.
• Recomendado real: 16 GB ou mais. ZFS usa RAM agressivamente para ARC (cache de leitura).
• Regra pratica: comece com 16 GB; se for habilitar dedup (raramente), planeje ~1-5 GB por TB.
• ECC: ideal mas nao obrigatorio. ECC protege ARC e write paths contra bit-flip. Em laboratorio domestico, non-ECC e aceitavel; em servidor de backup primario, ECC e fortemente recomendado.

3.3 HBA — controladora de disco

Regra de ouro: TrueNAS quer ver os discos diretamente. Nao use RAID por hardware.

• HBA recomendado: LSI/Broadcom 9211-8i, 9300-8i, 9305-16i, flashed em IT mode (Initiator Target = expoe discos crus).
• Evite cards RAID (PERC H730 em modo RAID, etc) mesmo em “HBA mode” — drivers irregulares mascaram SMART e abortam erros silenciosamente.
• Para boot SSD, controlador onboard (SATA/NVMe) ja basta.

3.4 Discos

Evite SMR (Shingled Magnetic Recording) para pool ZFS — WD Red non-Plus sao SMR; WD Red Plus e CMR (correto).

SLOG e L2ARC so se justificam por workload:

• SLOG (ZIL externo): so acelera sync writes (NFS sync, iSCSI, VMs). Para SMB casual nao ajuda. Precisa ter PLP (power-loss protection).
• L2ARC: cache de leitura em SSD. So vale com dataset maior que RAM e padrao de acesso quente. Cada GB de L2ARC consome RAM para indice (~80 bytes por record).

3.5 Boot drive

• Use um SSD pequeno separado (16-128 GB) so para o boot-pool.
• Nao instale o sistema dentro do pool de dados.
• Pen-drive USB nao e mais suportado (writes do journald matam o stick).
• Mirror de boot (2 SSDs) e suportado e recomendado se uptime importa.

3.6 Rede

• 1 GbE ja satura HDDs sequenciais (~120 MB/s).
• Para multiplos clientes simultaneos / iSCSI / replicacao rapida: 2.5/10 GbE (Intel X710, Mellanox ConnectX-4, etc).
• LACP/LAGG so ajuda se houver muitas conexoes simultaneas — nao acelera um cliente unico.

3.7 UPS

Obrigatorio em qualquer ZFS serio. Quedas durante escrita podem nao corromper o pool (ZFS e COW), mas perdem writes nao-sincronizados e podem deixar pool em estado degradado. TrueNAS integra com NUT (System Settings -> UPS).

4. Layout ZFS

4.1 Hierarquia

flowchart TB
  POOL[Pool: tank] --> VDEV1[VDEV raidz2 #1<br/>6 discos]
  POOL --> VDEV2[VDEV raidz2 #2<br/>6 discos]
  POOL --> SLOG[SLOG VDEV<br/>NVMe mirror]
  POOL --> L2[L2ARC VDEV<br/>NVMe single]
  POOL --> SPARE[Spare<br/>1 disco]

  VDEV1 --> D1[disk1]
  VDEV1 --> D2[disk2]
  VDEV1 --> D3[disk3]
  VDEV1 --> D4[disk4]
  VDEV1 --> D5[disk5]
  VDEV1 --> D6[disk6]

4.2 Tipos de VDEV

4.3 Regras de ouro

1. VDEV e a unidade de redundancia. Perdeu um VDEV inteiro = perdeu o pool inteiro. Por isso voce nunca faz “raidz0” de varios raidz.
2. Pool e stripe dos VDEVs. Adicionar VDEV aumenta capacidade + IOPS, mas voce nao pode remover VDEV de pool com raidz (so de mirror).
3. Nao misture tamanhos dentro de um VDEV — ZFS usa o menor.
4. Nao misture tipos de VDEV no mesmo pool (mirror + raidz2 no mesmo pool e ma ideia).
5. Expansao: raidz2 expansion ja existe (OpenZFS 2.2+, disponivel em 24.10+), mas planeje VDEVs novos quando possivel.
6. Reserve 20% livre. ZFS performance cai feio acima de 80% de uso.

4.4 Calculo de capacidade

Formula simples para raidzN: capacidade_util ~= (n_discos - n_paridade) * tamanho_disco * 0.9 (10% de overhead).

Para 6 discos NAS de tamanhos grandes (>=8 TB), raidz2 e o default sensato — o rebuild de raidz1 com disco grande aumenta risco de um segundo disco falhar durante o resilver.

4.5 Boot-pool

Criado automaticamente no instalador, separado do pool de dados. Voce nao mexe nele manualmente. Mirror opcional na instalacao (2 SSDs de boot).

5. Pre-requisitos

Antes de iniciar a instalacao:

• Hardware montado, HBA em IT mode, todos os discos visiveis no firmware.
• Boot drive separado dos discos do pool. Saiba qual e qual (anote serial/posicao).
• IP estatico reservado no DHCP/router (ex.: 192.168.1.10).
• Hostname definido (ex.: truenas.lan).
• Timezone decidido (ex.: America/Sao_Paulo).
• ISO baixada — TrueNAS SCALE 25.04 download.
• Pen-drive de instalacao (>= 4 GB) gravado com dd ou Ventoy/Rufus.
• BIOS/UEFI: virtualizacao desligada (se bare-metal), boot UEFI, secure boot off, IOMMU on (se for usar passthrough depois ou se for VM hospedeiro).
• (Opcional) e-mail SMTP de aplicacao (Gmail App Password / Mailgun) para alertas.

6. Instalacao

1. Bootar pelo pen-drive (UEFI). Selecionar Install/Upgrade TrueNAS SCALE.
2. Aceitar EULA.
3. Selecionar o disco de boot — atencao: NUNCA selecione um disco que esteja no array de dados. Confirme pelo modelo/tamanho. Para mirror de boot, selecione dois SSDs.
4. Tipo de instalacao: Install.
5. Definir senha root (use senha forte; voce vai trocar para login admin depois).
6. Tipo de bootloader: BIOS ou UEFI conforme firmware.
7. Aguardar copia (~5 min).
8. Remover pen-drive, reboot.
9. Console mostra IP DHCP atribuido (ex.: http://192.168.1.10). Acessar pelo navegador em https://IP (porta 443, com cert auto-assinado).

7. Pos-instalacao

7.1 Primeiro login

• Login: root + senha definida na instalacao.
• A partir da 24.10, TrueNAS sugere criar um usuario admin com sudo e desabilitar login root direto. Faca isso:
  • Credentials -> Local Users -> Add -> usuario admin, shell bash, group wheel, marque sudo.
  • Logout e logue como admin.
  • Edite root e marque Disable Password.

7.2 Settings essenciais

System Settings -> General:

• Hostname: truenas
• Domain: lan (ou seu dominio interno)
• Timezone: America/Sao_Paulo
• Console keyboard: br-abnt2 se teclado fisico ABNT2
• GUI HTTPS: manter 443; opcionalmente importar cert valido (Let’s Encrypt via ACME)

System Settings -> Network:

• Editar interface fisica (ex.: enp3s0). Desmarcar DHCP, marcar Static.
• IPv4: 192.168.1.10/24
• Default gateway: 192.168.1.1
• Primary DNS: 192.168.1.1 (ou seu DNS interno)
• Test Changes -> se conexao mantiver, Save Changes.

System Settings -> Update:

• Selecionar Train: TrueNAS-SCALE-Fangtooth (release). Evite Prerelease em producao.
• Marcar Check for Updates Daily.

System Settings -> Email:

• GMail (App Password) via SMTP:
  • Outgoing mail server: smtp.gmail.com
  • Port: 587
  • Security: TLS (STARTTLS)
  • SMTP Authentication: on
  • Username: seu email
  • Password: App Password (16 chars, sem espacos)
  • From Email: mesmo email
  • Send Test Mail para validar.

Credentials -> 2FA:

• Habilitar 2FA TOTP para conta admin. Salvar QR code num cofre/Bitwarden.

System Settings -> Advanced:

• Console Setup Menu: on (acesso emergencial pelo console fisico).
• Syslog Level: NOTICE (default ok).
• Show console messages: off (limpa o boot).

8. Criando pool ZFS

8.1 Wizard

Storage -> Create Pool (ou Pools -> Create Pool em 25.04).

1. Pool name: tank (nome curto, sem espacos).
2. Encryption: opcional. Se habilitar, escolha passphrase (vs hex key); guarde a passphrase off-site — sem ela, dados perdidos.
3. Data VDEVs:
   • Layout: RAIDZ2 (recomendado para 6+ discos HDD).
   • Width: numero de discos por VDEV (ex.: 6).
   • Number of VDEVs: 1 (ou mais, se tiver discos para multiplos VDEVs).
   • Disk size: filtrar pelo tamanho.
   • Selecionar os discos manualmente OU usar Suggest Layout.
4. (Opcional) Log VDEV (SLOG): mirror de 2 SSDs com PLP. So se workload sync-heavy.
5. (Opcional) Cache VDEV (L2ARC): 1 SSD NVMe. So se houver hot dataset grande.
6. (Opcional) Spare VDEV: discos extras para hot-spare automatico.
7. (Opcional) Metadata Special VDEV: mirror de SSD para acelerar metadata + small files. Cuidado: se perder esse VDEV, perde o pool.
8. Create -> confirmar texto -> aguardar criacao.

Resultado: pool montado em /mnt/tank.

8.2 Erros comuns

• “Disk has existing partitions”: disco veio de outro pool/sistema. Storage -> Disks -> [disco] -> Wipe antes.
• Disco do boot aparece na lista de dados: NAO selecione. Confirme serial em Storage -> Disks.

8.3 Verificacao via shell

# acessar console via SSH (Credentials -> SSH Service -> habilitar; allow login admin)
ssh admin@192.168.1.10
sudo zpool status tank
sudo zpool list
sudo zfs list

9. Datasets

Datasets sao “subvolumes” ZFS dentro do pool. Cada um tem propriedades proprias (compressao, recordsize, ACL).

Storage -> tank -> Add Dataset.

9.1 Presets

9.2 Propriedades importantes

9.3 Quotas e reservations

• Quota = limite maximo que o dataset (e filhos) podem usar.
• Refquota = limite excluindo snapshots/filhos.
• Reservation = espaco garantido para esse dataset (impede outros datasets de “comer” tudo).

Exemplo: dataset tank/timemachine com quota de 2 TB.

Storage -> tank/timemachine -> Edit -> Quota for this dataset: 2 TiB.

9.4 Layout sugerido

tank/
  media/           recordsize=1M, compression=off (mp4/mkv ja comprimido)
    movies/
    series/
    music/
  backups/         recordsize=1M, compression=zstd
    restic-laptop/
    pbs/           (Proxmox Backup Server destino)
  timemachine/     recordsize=1M, compression=lz4, SMB preset, quota
  apps/            (auto-criado, recordsize=128K)
  iscsi/           (zvols dentro)
  docs/            recordsize=128K, compression=zstd

10. Zvols

Zvol = “bloco” ZFS — comporta-se como um disco bruto. Usado para iSCSI e VMs.

Storage -> tank -> Add Zvol.

• Name: vm-windows
• Size: 64 GiB (volsize)
• Sparse: on (thin provisioning — espaco alocado conforme escreve). Em pool com pouco espaco, desligue para evitar over-commit.
• Block size (volblocksize): 16K (default), 64K para VMs grandes, 128K para midia em zvol.
• Compression: lz4.
• Dedup: off.

Em shell:

sudo zfs create -V 64G -o volblocksize=16K -o compression=lz4 tank/vm-windows
sudo zfs list -t volume

11. Shares SMB (Windows / macOS / Time Machine)

11.1 Habilitar servico

System Settings -> Services -> SMB -> Start Automatically + Running.

11.2 Criar usuario

Credentials -> Local Users -> Add:

• Username: nasuser
• Password: forte
• Primary group: criar novo nasuser ou usar grupo compartilhado family
• Home: vazio (nao precisa)
• Shell: nologin
• SMB User: on

11.3 Criar share

1. Datasets -> tank/media -> Edit Permissions -> Permissions Editor:
   • Owner: nasuser, group: family
   • ACL: preset SMB Restricted ou SMB Open
   • Marcar Apply recursively na primeira vez.
2. Sharing -> Windows Shares (SMB) -> Add:
   • Path: /mnt/tank/media
   • Name: media
   • Purpose: Default share parameters
   • Enable Apple SMB2/3 extensions: marcar so se for usar Time Machine nesse share.
3. Save -> TrueNAS pergunta se quer reiniciar SMB -> Restart.

11.4 Time Machine — share dedicado

Time Machine quer share proprio com presets especificos.

1. Crie dataset tank/timemachine, com quota (Time Machine consome tudo que pode).
2. Sharing -> SMB -> Add:
   • Path: /mnt/tank/timemachine
   • Name: timemachine
   • Purpose: Multi-user Time Machine (preset que ja liga AAPL extensions + fruit:time machine = yes).
3. Save, restart SMB.
4. No macOS: System Settings -> General -> Time Machine -> Add Backup Disk. O share aparece como Time Machine on truenas. Login com usuario SMB.

11.5 Conectar clientes

# Linux (gio / Files)
gio mount smb://truenas.lan/media

# Linux (mount.cifs)
sudo mkdir /mnt/truenas-media
sudo mount -t cifs //truenas.lan/media /mnt/truenas-media \
  -o username=nasuser,vers=3.0,uid=$(id -u),gid=$(id -g)

# fstab (com credentials file)
//truenas.lan/media  /mnt/truenas-media  cifs  credentials=/root/.smbcreds,vers=3.0,_netdev,nofail  0  0

# Windows (PowerShell ou Explorer)
net use Z: \\truenas.lan\media /user:nasuser /persistent:yes

# macOS — Finder -> Cmd+K -> smb://truenas.lan/media

12. Shares NFS

NFS e melhor para Linux/Proxmox/ESXi (sem overhead SMB).

12.1 Habilitar servico

System Settings -> Services -> NFS:

• NFSv4: on (recomendado).
• NFSv3 ownership model for NFSv4: depende; para destino de PBS deixe off.
• Start Automatically + Running.

12.2 Criar export

Sharing -> Unix Shares (NFS) -> Add:

• Path: /mnt/tank/backups/pbs
• Description: PBS datastore
• Networks: 192.168.1.0/24 (libera so a LAN). NAO deixar vazio (libera para tudo).
• Hosts: ou IPs especificos (192.168.1.20).
• Maproot User: root (necessario para PBS criar arquivos como root). Para shares menos privilegiados, mapear para nobody.
• Advanced: Read Only se for o caso.

12.3 Mount no cliente

sudo mkdir -p /mnt/truenas-pbs
sudo mount -t nfs -o vers=4.2 truenas.lan:/mnt/tank/backups/pbs /mnt/truenas-pbs

# fstab
truenas.lan:/mnt/tank/backups/pbs  /mnt/truenas-pbs  nfs  vers=4.2,_netdev,nofail  0  0

Em Proxmox: Datacenter -> Storage -> Add -> NFS. Server truenas.lan, Export /mnt/tank/backups/pbs.

13. iSCSI (block storage)

Use para discos virtuais de VMs (ESXi/Proxmox) onde NFS nao serve.

1. Sharing -> Block Shares (iSCSI) -> Wizard:
   • Block device type: Device -> selecione zvol previamente criado (ex.: tank/iscsi/vm1).
   • Sharing platform: VMware: Extent block size 512b... ou Modern OS.
   • Target name: vm1.
2. Portal: bind a IP do servidor (192.168.1.10), porta 3260.
3. Initiators: liberar IQN do cliente ou ALL.
4. Authentication: opcional CHAP.
5. Services -> iSCSI -> Running.

Cliente Linux:

sudo apt install open-iscsi
sudo iscsiadm -m discovery -t st -p 192.168.1.10
sudo iscsiadm -m node --login
lsblk   # vai aparecer um /dev/sdX novo

14. Replicacao ZFS para outro TrueNAS

Esquema 3-2-1: pool primario -> snapshots automaticos -> replicar para TrueNAS secundario (mesma casa ou off-site).

14.1 SSH connection

No primario: Credentials -> Backup Credentials -> SSH Connections -> Add:

• Name: truenas-backup
• Setup Method: Semi-Automatic (TrueNAS Enterprise) ou Manual.
• Host: IP do secundario.
• Username: admin.
• Private Key: gerar nova em SSH Keypairs -> Add -> Generate.
• Copiar chave publica para o secundario em Credentials -> Local Users -> admin -> SSH Public Key.

14.2 Snapshot Task

Data Protection -> Periodic Snapshot Tasks -> Add:

• Dataset: tank/media (recursive: on para incluir filhos)
• Naming schema: auto-%Y-%m-%d_%H-%M
• Schedule: hourly, daily, etc.
• Retention: 2 weeks daily + 12 weeks weekly por exemplo.

14.3 Replication Task

Data Protection -> Replication Tasks -> Add (Wizard):

• Source location: On this System, dataset tank.
• Destination: On a Different System, SSH connection truenas-backup, destino backup/tank-replica.
• Task name: replicate-tank-daily.
• Transport: SSH+NETCAT (mais rapido em LAN) ou SSH (off-site).
• Schedule: depois do snapshot task (ex.: 03:00 daily).
• Snapshot retention no destino: Same as Source ou customizado.
• Encryption inheritance: se source for encrypted, decidir se replica encrypted ou nao.

14.4 Testar restore

Replicacao so vale se voce testou o restore. Periodicamente (trimestral):

# no secundario
sudo zfs list -t snapshot backup/tank-replica/media | tail
sudo zfs send backup/tank-replica/media@auto-2026-04-01_03-00 | ssh admin@truenas.lan "sudo zfs recv tank/restore-test"

15. Snapshots periodicos

Mesmo sem replicacao, snapshots locais ja salvam de “rm -rf” acidental.

Data Protection -> Periodic Snapshot Tasks -> Add:

• Dataset: tank (recursive)
• Lifetime: 2 WEEKS
• Naming: auto-%Y-%m-%d_%H-%M
• Schedule:
  • hourly (lifetime 24h)
  • daily (lifetime 14d)
  • weekly (lifetime 8 semanas)
  • monthly (lifetime 12 meses)

Restore via UI: Datasets -> tank/foo -> Snapshots -> [snapshot] -> Clone to New Dataset ou Rollback.

16. Apps (Docker, a partir do SCALE 24.10)

A partir da TrueNAS SCALE 24.10 (Electric Eel), o subsistema de apps deixou de ser k3s/Helm e passou a ser Docker nativo. Em 25.04 (Fangtooth) isso e o padrao unificado. Apps existentes em 24.04 (Dragonfish, k3s) tinham migracao automatica ate 1 de junho de 2025 — depois disso e redeploy manual.

16.1 Habilitar Apps

Apps -> Settings -> Choose Pool -> tank (cria dataset tank/ix-apps automaticamente).

16.2 Instalar app do catalogo

Apps -> Discover Apps -> escolher app (ex.: Plex, Jellyfin, Nextcloud, Vaultwarden, Home Assistant, Sonarr, Radarr, qBittorrent).

Para cada app:

• Storage: mapear Host Path Volumes para datasets dedicados (ex.: /mnt/tank/media -> /media no container).
• Networking: a partir de 25.04 voce pode atribuir IP proprio por app (similar a jails do CORE 13.x). Util para apps que conflitam em portas.
• Resources: limites de CPU/RAM/GPU. Para Plex/Jellyfin com transcode: passar GPU (Intel iGPU via QuickSync ou NVIDIA).

16.3 Custom App (Docker Compose YAML)

Apps -> Discover Apps -> Custom App -> dar nome -> colar YAML.

Exemplo vaultwarden:

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.lan.example"
      SIGNUPS_ALLOWED: "false"
      WEBSOCKET_ENABLED: "true"
      ADMIN_TOKEN: "${ADMIN_TOKEN}"
    volumes:
      - /mnt/tank/apps/vaultwarden:/data
    ports:
      - "8080:80"
      - "3012:3012"

Exemplo homepage:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - /mnt/tank/apps/homepage/config:/app/config
      - /mnt/tank/apps/homepage/icons:/app/public/icons
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      HOMEPAGE_ALLOWED_HOSTS: "homepage.lan.example,truenas.lan:3000"

Salvar -> TrueNAS roda docker compose up -d internamente.

16.4 Boas praticas

• Sempre mapear dados persistentes para datasets do pool, nunca para o disco de boot.
• Dataset dedicado por app (tank/apps/<nome>) facilita snapshot/replicacao por app.
• Snapshot do dataset tank/apps antes de update de app.
• Para apps publicos, ponha um reverse proxy (Caddy / NPM / Traefik) em vez de expor porta direto.

17. TrueNAS como destino de backup

17.1 Padroes

• Dataset dedicado por origem: tank/backups/<host>/<ferramenta>.
• Snapshot do dataset destino (periodic snapshot task) — protege contra ransomware que se autenticar como cliente de backup: mesmo que apague os arquivos, o snapshot ZFS imutavel preserva. Use retention longa (3-6 meses).
• Pull-based quando possivel: TrueNAS busca dados do cliente via rsync/SSH, em vez de cliente push. Reduz blast radius (cliente comprometido nao apaga o destino).
• Considerar dataset read-only apos commit e snapshot, ou usar zfs hold em snapshots criticos para impedir destroy.

17.2 Restic

# no laptop
restic -r sftp:nasuser@truenas.lan:/mnt/tank/backups/laptop init
restic -r sftp:nasuser@truenas.lan:/mnt/tank/backups/laptop backup ~/Documents

17.3 Borg

borg init --encryption=repokey-blake2 \
  ssh://nasuser@truenas.lan:22/mnt/tank/backups/laptop-borg
borg create ssh://.../laptop-borg::"{hostname}-{now}" ~/

17.4 rclone (cloud -> TrueNAS)

rclone sync gdrive:/Fotos /mnt/tank/backups/gdrive --progress --transfers 8

17.5 Proxmox Backup Server

• Crie dataset tank/backups/pbs exportado via NFS.
• Em PBS: Datastore -> Add -> NFS ou monte fstab e use como local datastore.
• Snapshot ZFS diario do dataset garante recuperacao caso PBS chunks corrompam.

18. TrueNAS em VM no Proxmox (HBA passthrough)

18.1 Pre-requisitos no host Proxmox

1. IOMMU habilitado na BIOS (VT-d Intel / AMD-Vi AMD).
2. Kernel cmdline (/etc/default/grub ou /etc/kernel/cmdline):
   • Intel: intel_iommu=on iommu=pt
   • AMD: amd_iommu=on iommu=pt
   • Aplicar: update-grub ou proxmox-boot-tool refresh, reboot.
3. Verificar:

dmesg | grep -e DMAR -e IOMMU
# deve mostrar "DMAR: IOMMU enabled" ou similar
ls /sys/kernel/iommu_groups/  # cada grupo e uma unidade de passthrough

4. Identificar o HBA e seu grupo IOMMU:

lspci -nnk | grep -A3 -i 'SAS\|LSI\|9211\|9300'
# anote o BDF (ex.: 03:00.0) e o vendor:device (ex.: 1000:0072)
for g in /sys/kernel/iommu_groups/*/devices/*; do
  echo "Group $(basename $(dirname $(dirname $g))): $(basename $g)"
done | grep 03:00

5. Reservar para vfio:

# /etc/modprobe.d/vfio.conf
options vfio-pci ids=1000:0072 disable_vga=1

# /etc/modules
vfio
vfio_iommu_type1
vfio_pci

update-initramfs -u && reboot.

18.2 Criar VM TrueNAS

GUI Proxmox:

• OS: ISO TrueNAS-SCALE-25.04.x.iso.
• System: BIOS OVMF (UEFI), Machine q35, EFI disk em pool local-zfs.
• Disks: disco virtual de 32-64 GB para boot do TrueNAS (SCSI single, discard on, ssd on). Nao crie discos virtuais para o pool de dados.
• CPU: host, 2-4 cores minimo, 4-8 ideal.
• Memory: 8 GB minimo, 16-24 GB ideal. Desligar ballooning (Ballooning Device: no) — ZFS nao curte memoria volatil.
• Network: virtio, bridge vmbr0.

Adicionar HBA via passthrough:

• VM -> Hardware -> Add -> PCI Device -> Raw Device -> selecionar o HBA (03:00.0). Marcar All Functions, PCI-Express.

Opcoes da VM:

• Start at boot: yes
• Boot order: scsi0 primeiro
• QEMU Guest Agent: enabled (instalar agent dentro do TrueNAS depois — opcional)

Iniciar VM. Instalacao igual bare-metal (secao 6).

18.3 Cuidados

• NUNCA apresente discos via qm set ... --scsi1 /dev/disk/by-id/... para o pool ZFS — TrueNAS perde controle direto, scrub e SMART nao funcionam corretamente, e voce arrisca corromper o pool em desligamento brusco do hypervisor.
• NIC virtio e ok; se quiser performance maxima, faca passthrough da NIC dedicada tambem.
• Backup da config da VM (/etc/pve/qemu-server/<vmid>.conf) para nao perder mapeamento PCI.
• Shutdown ordem: sempre shutdown pelo TrueNAS antes de desligar o Proxmox. Configure ACPI/QEMU guest agent.

19. Monitoramento

19.1 Reporting (built-in)

Reporting no menu lateral — graficos de CPU, memoria, ARC hit/miss, disco I/O, rede, temperatura. Dados em /var/db/netdata ou exportaveis para Graphite/Prometheus em versoes recentes.

19.2 SMART tests

Data Protection -> S.M.A.R.T. Tests -> Add:

• Short test: weekly (toda sexta 02:00, todos os discos do pool)
• Long test: monthly (1o domingo 03:00)

Validar manualmente:

sudo smartctl -a /dev/sda
sudo smartctl -t short /dev/sda
sudo smartctl -l selftest /dev/sda

19.3 Scrub

Data Protection -> Scrub Tasks:

• raidz2 / raidz3 HDD: mensal (ex.: 1o domingo).
• mirror SSD: trimestral e suficiente.

Scrub le todos os blocos e valida checksum — detecta bit-rot silencioso antes que vire problema.

19.4 Alertas

System Settings -> Alert Settings:

• Habilitar Email como destino para CRITICAL, ERROR, WARNING.
• Outras destinos: Slack, Telegram, PagerDuty, AWS SES.

19.5 Capacidade

Configurar alerta de >80% pool usage. ZFS performance derrete acima disso.

20. Troubleshooting

20.1 Pool degraded

sudo zpool status -v tank
# disco com FAULTED/REMOVED -> identificar serial
sudo zpool status -L tank | grep -E 'sd|nvme'

Substituicao via UI: Storage -> tank -> Manage Devices -> [disco] -> Replace. Selecionar disco novo, confirmar. Resilver comeca automatico.

sudo zpool status tank   # acompanhar progresso resilver

20.2 Boot pool cheio

Updates antigos acumulam boot environments.

System Settings -> Boot -> Boot Environments -> apagar BEs antigos (mantenha o atual + 1 anterior).

Via shell:

sudo beadm list
sudo beadm destroy <nome-antigo>

20.3 SMB lento

• Verificar atime esta off no dataset.
• Desligar SMB signing se nao precisa: Services -> SMB -> Advanced -> Server Min Protocol: SMB2_10 / Max: SMB3 + signing optional.
• Confirmar negociacao SMB3 multichannel se hardware suporta.
• Testar com iperf3 para descartar problema de rede.
• Verificar carga da CPU; SMB e single-thread por conexao — CPU lenta limita throughput.

20.4 Time Machine nao enxerga o share

• Confirmar purpose Multi-user Time Machine no share.
• Apple SMB2/3 Extensions ligado no servico SMB global.
• Mac: limpar entrada antiga em System Settings -> Time Machine.
• macOS Sonoma+: defaults write com.apple.systempreferences TMShowUnsupportedNetworkVolumes 1 so para shares fora do padrao.

20.5 Apps nao iniciam apos upgrade 24.04 -> 24.10

• Migracao automatica expirou em 01/06/2025. Para deployments mais antigos, redeploy via App Catalog (Docker).
• Comando manual de migracao (so se ainda for valido na release):

sudo midclt call -job k8s_to_docker.migrate tank

• Dados antigos em ix-applications/ -> os volumes PVC podem ser exportados antes (ver gist comunitario).

20.6 Passthrough VM: “no devices” / disco sumido

• Conferir IOMMU ativo (dmesg | grep IOMMU).
• Conferir HBA no grupo IOMMU isolado — se grupo tem outros devices criticos, usar pcie_acs_override=downstream,multifunction (em ultimo caso, quebra seguranca de isolamento).
• Conferir vfio-pci carregou e capturou o device:

lspci -nnk -s 03:00.0
# "Kernel driver in use: vfio-pci"

• Em hosts AMD antigos pode precisar pci=noaer.

20.7 Replicacao falhou

• Logs: Tasks -> Replication Tasks -> [task] -> View Logs.
• Causa comum: snapshot intermediario apagado no source antes da replicacao terminar -> resetar incremental_base ou marcar Allow Blocks Larger than 128KB no destino.
• Chave SSH errada -> testar ssh -i /root/.ssh/<key> admin@destino no shell.

20.8 Pool nao monta apos reboot (encryption)

Datasets/pool encrypted com passphrase pedem unlock manual:

Storage -> tank -> Unlock -> digitar passphrase. Ou via shell:

sudo zfs load-key tank
sudo zfs mount -a

20.9 Discos somem aleatoriamente

• Quase sempre cabo SAS/SATA ruim ou backplane.
• dmesg | grep -i 'reset\|sata\|sas' mostra reset frequente.
• Trocar cabo, mover slot, atualizar firmware do HBA.

21. Referencias

• TrueNAS SCALE Documentation Hub: https://www.truenas.com/docs/scale/
• TrueNAS SCALE 25.04 (Fangtooth) Release Notes: https://www.truenas.com/docs/scale/25.04/gettingstarted/scalereleasenotes/
• TrueNAS SCALE 24.10 (Electric Eel) Release Notes: https://www.truenas.com/docs/scale/24.10/gettingstarted/scalereleasenotes/
• Hardware Guide: https://www.truenas.com/docs/scale/gettingstarted/scalehardwareguide/
• Apps catalog: https://apps.truenas.com/
• TrueNAS Community Forums: https://forums.truenas.com/
• OpenZFS Documentation: https://openzfs.github.io/openzfs-docs/
• Migracao Apps k3s -> Docker: https://www.truenas.com/blog/truenas-apps-made-easy/
• Time Machine over SMB (Apple): https://support.apple.com/guide/mac-help/back-up-your-mac-with-time-machine-mh11421/mac
• Proxmox PCI(e) Passthrough: https://pve.proxmox.com/wiki/PCI_Passthrough