Montando um NAS RAIDZ1 no Debian 13 com OpenZFS: datasets, compressão e as mentiras que o dd me contou

Ilustração de um NAS RAIDZ1 montado com OpenZFS no Debian

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski

⚠️ Alguns comandos deste post criam pools ZFS ou apagam e sobrescrevem dados. Faça um backup antes, teste num sistema de testes e adapte nomes de dispositivos e caminhos ao seu ambiente.

🪟➡️🐧 Contexto: aposentando a máquina Windows

Um pouco de história, já que “por que essa máquina Debian qualquer de repente tem três discos e opiniões fortes sobre compressão” merece uma resposta. Até pouco tempo atrás, um Windows Server cuidava aqui tanto do Active Directory quanto das funções de servidor de arquivos/NAS — e, justiça seja feita, ele fazia o trabalho perfeitamente bem. Os logins funcionavam, os shares funcionavam, ninguém reclamava, nada estava pegando fogo. Mas toda vez que eu trocava de contexto daquela máquina para qualquer coisa com cara de DevSecOps, sentia o atrito: modelo mental diferente, ferramentas diferentes, memória muscular diferente para “tá, como eu vejo de verdade o que está acontecendo aqui”. O servidor Windows existia só para NAS + login no AD, enquanto uma máquina separada continuava fazendo em silêncio todo o trabalho real de Linux — funções de jump host, uma ou outra tarefa meio CI e, ultimamente, também a coisa que está gerando esta mesma frase. Dois servidores, duas filosofias de operação e uma sensação crescente de que eu estava curando um pequeno museu de “como isso era feito antigamente” em vez de operar um setup coerente. 🏛️ Claro, eu poderia ter apelado para o Proxmox e virtualizado meu caminho em volta da decisão em vez de realmente tomá-la — subir um guest Windows, manter o AD por hábito e chamar isso de consolidação. Mas cheguei ao ponto em que eu prefiro de verdade colocar tudo no Linux, numa máquina só, e abraçar isso: um toolchain, uma coisa para aplicar patches, uma coisa para monitorar, em vez de manter dois mundos totalmente diferentes por causa de um share de arquivos e de uma tela de login. E correr atrás dessa consolidação foi exatamente o que me trouxe de volta ao OpenZFS — se eu vou reconstruir a função de NAS do zero no Linux de qualquer jeito, quero que a camada de armazenamento por baixo seja boa de verdade, e não só “boa o suficiente para o Explorer parar de reclamar”. Então: reinstalei uma máquina sobrando com um Debian 13 (trixie) limpinho e decidi que era hora de parar de tratar o armazenamento como algo secundário — sabe, aquela mentira clássica de “um dia eu organizo meus arquivos direito” que todos nós contamos para nós mesmos. Entraram três SSDs WD Red SA500 de 2TB, e o objetivo era simples no papel: um pool redundante, uma compressão que se paga e shares por usuário que não pisem no pé uns dos outros. O OpenZFS tornou isso genuinamente agradável — depois que superei uma peculiaridade de empacotamento, um bug cosmético do upstream que me fez duvidar da minha sanidade por dez minutos e o meu próprio primeiro benchmark, profundamente constrangedor. Aqui vai o passo a passo completo, com verrugas e tudo. 🐛

🤔 Por que ZFS e não NTFS ou mdadm + ext4

Versão curta: eu queria dados com checksum, compressão transparente, snapshots baratos e uma camada de armazenamento que entenda “dataset” como um conceito de primeira classe, e não como “diretório que eu prometo tratar de forma especial, juradinho”. Depois de anos de NTFS naquele Windows Server, e tendo convivido com ext4 em todo o resto, vale a pena explicar de verdade o que o ZFS faz de diferente em vez de só afirmar que ele é melhor — porque, no papel, NTFS e ext4 parecem ótimos. Eles montam, guardam arquivos e estão em produção há décadas. As diferenças só aparecem quando algo dá errado em silêncio, que é exatamente o cenário que nenhum dos dois foi feito para pegar. Checksums — a verdadeira atração principal. O ZFS calcula checksum de cada bloco de dados e de cada bloco de metadados, e verifica esse checksum em cada leitura, não só durante uma varredura agendada de vez em quando. O NTFS não tem checksum de dados nenhum — o recurso de integrity streams só cobre metadados, é opcional e foi discretamente limitado no ReFS em versões posteriores do Windows Server a nada além de metadados. O ext4 está no mesmo barco: metadata_csum protege a contabilidade interna do próprio sistema de arquivos, mas o conteúdo real dos seus arquivos é aceito às cegas. Se um bit vira em algum lugar da mídia física — e em qualquer disco grande e velho o bastante, alguns bits vão virar um dia — NTFS e ext4 vão te entregar o byte corrompido com um sorriso e zero indicação de que algo aconteceu. Isso é bit-rot silencioso, e “silencioso” é a palavra-chave: nenhum erro, nenhuma entrada de log, nenhum alerta, só um pixel levemente errado numa foto ou um byte levemente errado num arquivo de backup que ninguém percebe até que faça diferença. Autocorreção, não só detecção. É aqui que o ZFS passa na frente até de alternativas com checksum: como ele gerencia a redundância (RAIDZ, mirrors) e os checksums na mesma camada, ele consegue não só dizer “este bloco está errado”, mas reconstruir o valor correto a partir da paridade e regravá-lo automaticamente — durante leituras normais e, de forma abrangente, durante um zpool scrub. Compare isso com a pilha clássica mdadm + ext4: a camada de RAID e a camada do sistema de arquivos não conversam entre si. O mdadm consegue te dizer que um disco inteiro morreu. Ele não consegue te dizer que um bloco específico estragou em silêncio enquanto todos os discos dizem “estou bem” — não há checksum sendo comparado, então não há nada sobre o que discordar. A corrupção simplesmente se propaga em silêncio por todos os cálculos de paridade como se fosse dado correto, porque, para o RAID, ela é. Sem “resync inicial” na criação, porque paridade não é um conceito separado. Quem já montou um array mdadm RAID5/6 conhece o ritual: cria o array e depois espera — às vezes por horas — enquanto ele mói um resync inicial do array inteiro, gravando paridade consistente em cada bloco, quer aquele bloco tenha dados reais, quer ainda esteja completamente vazio. Ele precisa fazer isso: o mdadm opera puramente no nível de dispositivo de bloco, abaixo do sistema de arquivos, sem nenhuma visibilidade sobre quais blocos são “de verdade” e quais são espaço não usado. Ele não pode pular nada, então não pula. Já o zpool create neste mesmo conjunto de três discos levou alguns segundos. Sem resync, sem espera, nada para pôr em dia — porque no ZFS a paridade é calculada e gravada como parte da mesma escrita atômica que grava os próprios dados, e espaço não alocado simplesmente não tem paridade que possa estar inconsistente. Não existe “estado inicial” para corrigir, porque nunca existe um momento em que dados e paridade discordem. O equivalente mais próximo de um rebuild de RAID no ZFS é um resilver — disparado quando um disco com falha é substituído ou um novo é anexado a um mirror — e até ele herda a mesma vantagem de conhecer o sistema de arquivos: o ZFS faz resilver só dos blocos realmente alocados, não da capacidade bruta total do disco. Um pool 40% cheio só precisa fazer resilver de 40% de dados; um rebuild tradicional do mdadm moeria 100% do array de qualquer jeito, porque ele não sabe a diferença. O equivalente proativo de uma passada check/repair do mdadm é o zpool scrub — mesma ideia, mesmo ganho de eficiência: ele percorre e verifica (e, ao contrário de uma checagem de RAID burra, realmente corrige) cada bloco alocado contra o seu checksum, e pula tudo o que nunca foi gravado. Copy-on-write vs. journaling. ext4 e NTFS são ambos sistemas de arquivos com journaling: eles registram mudanças de metadados antes de efetivá-las, então um crash no meio de uma escrita deixa metadados consistentes, mas uma escrita de dados em andamento ainda pode te deixar com um arquivo meio gravado. O ZFS nunca sobrescreve dados ativos no lugar — toda escrita vai para um bloco novo, e o sistema de arquivos troca atomicamente assim que ela estiver totalmente efetivada. Não existe janela em que um crash possa deixar um arquivo meio velho, meio novo; você vê ou o último estado completo ou o novo estado completo, nunca uma mistura dos dois. Snapshots que são baratos de verdade. O NTFS tem o Volume Shadow Copy, que funciona, mas está amarrado a um serviço VSS separado, tem limites práticos de quantos você realisticamente vai manter e pode ficar visivelmente lento à medida que as mudanças se acumulam. O ext4 não tem nada nativo — você acaba recorrendo a snapshots LVM por baixo, que são uma camada própria com seu próprio custo de desempenho conforme divergem da origem. Snapshots ZFS são quase instantâneos (copy-on-write de novo — um snapshot significa só “pare de recuperar estes blocos por enquanto”), não custam nada até os dados realmente mudarem, e dá para manter dezenas deles por aí sem pensar duas vezes. Compressão como padrão, não como concessão. A compressão do NTFS existe, mas é velha, single-threaded e lenta o bastante para que ativá-la em qualquer coisa sensível a desempenho seja um erro que a maioria dos admins comete só uma vez. O ext4 não tem compressão nativa nenhuma. A compressão lz4 do ZFS, como mostro abaixo, é rápida o suficiente para que deixá-la ligada seja simplesmente o padrão correto — não um trade-off sobre o qual você precise pensar. Armazenamento em pool como modelo nativo. Aumentar um volume NTFS ou um sistema de arquivos ext4 significa brigar com o Storage Spaces ou com LVM/mdadm, respectivamente — ferramentas separadas aparafusadas por baixo, cada uma com seu próprio modelo mental e seus próprios modos de falha. Pools e datasets ZFS são a abstração nativa, não um acessório: adicionar capacidade, criar um novo dataset ou definir uma quota por dataset são só subcomandos zpool/zfs, sem segundo toolchain.

RecursoNTFSext4ZFS
Checksums de dadosNãoNãoSim, cada bloco, verificado em cada leitura
Autocorreção automáticaNãoNãoSim, via redundância + checksums juntos
Consistência após crashSó metadados com journalingSó metadados com journalingCopy-on-write completo, sem sobrescrita no lugar
SnapshotsVSS (limitado, fica lento com o tempo)Nada nativo (precisa de LVM)Nativos, quase instantâneos, baratos
CompressãoLenta, raramente usadaNada nativoRápida (lz4), ligada por padrão
Armazenamento em pool / quotasStorage Spaces (aparafusado)LVM (aparafusado)Nativo do sistema de arquivos

Nada disso faz do NTFS ou do ext4 sistemas de arquivos ruins — eles são maduros, bem compreendidos, e o NTFS em particular rodou aquele Windows Server sem falhas por anos. Mas “sem falhas, até onde eu sei” é exatamente a frase que deveria te deixar nervoso em relação a corrupção silenciosa: a questão toda é que nenhum dos dois teria me avisado se tivesse acontecido. mdadm + LVM + ext4 conseguem se aproximar de parte da lista de recursos do ZFS com fita adesiva e disciplina pessoal suficientes. O ZFS simplesmente tem tudo isso, com pilhas inclusas, e não te pede para segurar três ferramentas separadas na base da força de vontade — nem para confiar que nada vai dar errado em silêncio justamente no eixo que ninguém está vigiando.

📦 Passo 1: colocando o OpenZFS no Debian 13

O Debian não distribui o ZFS no main por questões de licença (CDDL vs GPL — a briga mais longa da história do licenciamento de software, mais velha do que a maioria dos discos deste pool), então ele mora no contrib. Esse componente não vem habilitado por padrão:

# /etc/apt/sources.list — add contrib
deb http://deb.debian.org/debian trixie main contrib
deb http://deb.debian.org/debian trixie-updates main contrib
deb http://security.debian.org/debian-security trixie-security main contrib
apt-get update
apt-get install -y linux-headers-amd64 zfs-dkms zfsutils-linux

Isso puxa o DKMS, compila zfs.ko e spl.ko contra o kernel em execução (6.12.107+deb13-amd64 na época) e — como assinatura de módulos para Secure Boot agora é uma realidade — gera na hora uma MOK (Machine Owner Key) autoassinada para assinar os módulos recém-compilados. Se a sua máquina tem Secure Boot ativado, você vai precisar registrar essa MOK no próximo reboot; esta não tinha, então não foi problema, mas vale saber que o DKMS está forjando discretamente suas próprias credenciais de assinatura em segundo plano, como um falsificador muito educado e muito legal. 🔏

🏗️ Passo 2: criando o pool

Três discos, RAIDZ1 (um disco de paridade — a escolha certa para três drives; RAIDZ2 pede mais discos para não desperdiçar capacidade demais). A única regra que realmente importa para mim aqui: nunca aponte o ZFS para /dev/sdX. As letras dos dispositivos são atribuídas no boot e podem se embaralhar depois de uma atualização de kernel, uma mudança na BIOS ou simplesmente um dia ruim do universo. Use os caminhos estáveis de /dev/disk/by-id/, a não ser que você goste do horror específico de ver seu disco de paridade virar em silêncio seu disco de dados:

zpool create -o ashift=12 \
  -O compression=lz4 \
  -O atime=off \
  -O xattr=sa \
  storage raidz1 \
  /dev/disk/by-id/ata-WD_Red_SA500_2.5_2TB_25273ZD00458 \
  /dev/disk/by-id/ata-WD_Red_SA500_2.5_2TB_25273ZD01387 \
  /dev/disk/by-id/ata-WD_Red_SA500_2.5_2TB_25273ZD02050

zpool set autotrim=on storage
zfs set relatime=on storage

ashift=12 diz ao ZFS que estes são dispositivos com setores de 4K (SSDs são, sem exceção, mesmo quando mentem no firmware e informam setores lógicos de 512 bytes como se ainda fosse 2009). Erre isso na criação do pool e você não consegue corrigir depois sem destruir e reconstruir o pool — esta é a única configuração de todo este projeto sem volta, por isso ela ganha o negrito assustador. autotrim=on importa especificamente porque são SSDs; sem ele, você depende de um zpool trim manual periódico e deixa a write amplification subir em silêncio em segundo plano, como um colesterol da camada de armazenamento. Resultado final: três drives de 2TB, ~5,45TB brutos, ~3,6TB utilizáveis depois da paridade do RAIDZ1. Os ~1,85TB que faltam não sumiram — são o pedágio de “um disco pode morrer e eu continuo com meus dados”.

🗜️ Compressão: lz4, e por que não zstd

A compressão do ZFS é transparente, por dataset e — com lz4 — praticamente de graça, o que, em termos de nerd de armazenamento, é o mais perto de um almoço grátis que alguém vai te oferecer. O lz4 foi feito sob medida para ser tão rápido que ativá-lo nunca represente uma perda de throughput; ele também tem uma heurística de early-abort que desiste imediatamente diante de dados incompressíveis (vídeo já comprimido, blobs criptografados), em vez de tentar mesmo assim, teimosamente, e queimar CPU à toa. O zstd comprime mais, mas custa mais CPU por byte. Para uma carga de NAS de uso geral — documentos, fotos, uma ou outra imagem de VM, repositórios de código — o lz4 era o padrão óbvio. Se isto fosse um destino de backup guardando principalmente dumps em texto puro, eu teria escolhido zstd-3 e pago o imposto de CPU com prazer. Agora que há dados reais nele em vez de arquivos sintéticos de benchmark, eis o que ela realmente me rende — e, no espírito do tema recorrente deste post, a resposta honesta é “não muito”, e é exatamente isso que você esperaria quando sabe o que está armazenado:

$ zfs get compressratio storage storage/user3   storage/user1    storage/user2   storage/nextcloud
NAME               PROPERTY       VALUE
storage            compressratio  1.01x
storage/user3      compressratio  1.00x
storage/user1      compressratio  1.05x
storage/user2      compressratio  1.05x
storage/nextcloud  compressratio  1.03x
DatasetLógico (sem compressão)Real (em disco)Razão
storage/user31.21T1.20T1.00x
storage/user115.0G14.3G1.05x
storage/user2247G236G1.05x
storage/nextcloud385G375G1.03x

Razões quase inexistentes, e o motivo não é uma configuração errada — são os próprios dados. Este pool é principalmente fotos, vídeos, arquivos PST do Outlook e arquivos já comprimidos: exatamente o conteúdo que a heurística de early-abort do lz4 foi feita para reconhecer, parando de desperdiçar CPU com ele. Isso não é uma falha da compressão, é a compressão funcionando corretamente e saindo do caminho. Os datasets mais perto de realmente se beneficiar são storage/user2 e storage/user1, com 1.05x — ainda modesto, mas uma economia real e gratuita em qualquer fração desses dados que seja mais próxima de texto (documentos, arquivos de configuração, o overhead de metadados de centenas de milhares de arquivos pequenos). Se este pool hospedasse um dump de banco de dados ou uma pilha de arquivos de log em vez de um arquivo de fotos da família, esta tabela seria bem mais impressionante — e essa é a lição de verdade: a razão de compressão diz tanto sobre os seus dados quanto sobre o seu sistema de arquivos.

👻 O bug cosmético que me fez duvidar de mim mesmo

Defini xattr=sa na criação do pool (atributos estendidos guardados diretamente no dnode em vez de entradas de diretório ocultas — mais rápido e necessário para um desempenho decente de ACL). O comando saiu com 0, sem reclamações, sem drama. Aí zfs get xattr storage teimava em mostrar on em vez de sa, toda santa vez, como se nunca tivesse ouvido falar da configuração que eu tinha acabado de passar. Acontece que este é um bug de exibição conhecido e confirmado no OpenZFS 2.3.2 (veja a discussão #16996 do openzfs/zfs se quiser os detalhes sangrentos) — a propriedade está definida corretamente, o zfs get só mostra o rótulo errado. Não é configuração errada, só ruído cosmético que vai, com certeza, te fazer duvidar de si mesmo e rodar o mesmo comando cinco vezes antes de você pensar em pesquisar no Google. 🕵️

🧠 Ajuste do ARC: deixando RAM para todo o resto

O Adaptive Replacement Cache (ARC) do ZFS vai comer alegremente a maior parte da sua RAM se você deixar — o que é ótimo num appliance de armazenamento dedicado e bem menos ótimo numa máquina que também roda outros serviços e gostaria de dar uma palavrinha. Sem limite, o ARC se comporta exatamente como um adolescente sozinho com a geladeira: dê espaço e ele vai ocupar, e não vai devolver nada por iniciativa própria. Com 31GB de RAM no total, eu o limitei:

# /etc/modprobe.d/zfs.conf
options zfs zfs_arc_max=17179869184
options zfs zfs_arc_min=2147483648

Máximo de 16GiB, mínimo de 2GiB. Aplicado em tempo real via /sys/module/zfs/parameters/zfs_arc_max para efeito imediato e depois embutido no initramfs (update-initramfs -u -k all) para sobreviver a um reboot e não voltar simplesmente a assaltar a geladeira.

🤥 Benchmark, ou: como menti para mim mesmo por cinco minutos

Na primeira passada, fiz o que todo novato em ZFS faz e me arrependi na hora:

dd if=/dev/zero of=/storage/testfile bs=1M count=10000

8,7 GB/s de escrita. 14,1 GB/s de leitura. Em três SSDs SATA. Numa rede doméstica. Por um instante pensei em escrever um post enfático no LinkedIn sobre como SSDs de consumo são subestimados. Aí lembrei como compressão funciona: /dev/zero produz um fluxo infinito de zeros, o lz4 comprime uma sequência de zeros a quase nada, e eu tinha acabado de fazer benchmark do meu compressor, não dos meus discos. Profundamente bobo, brevemente empolgante, no fim sem sentido nenhum — o equivalente em armazenamento a cronometrar a velocidade com que você lê um livro lendo só páginas em branco. 📖💨 Refiz direito com dados incompressíveis, porque mentir para si mesmo só tem graça uma vez:

dd if=/dev/urandom of=/storage/testfile bs=1M count=4096          # buffered write
dd if=/dev/urandom of=/storage/testfile bs=1M count=4096 oflag=direct   # O_DIRECT write
dd if=/storage/testfile of=/dev/null bs=1M                        # buffered read
dd if=/storage/testfile of=/dev/null bs=1M iflag=direct           # O_DIRECT read

Rodei isso direito uma segunda vez, semanas depois, quando o pool já tinha dados reais e — o que é importante — quando todos os outros jobs da máquina (uma migração de 380GB, uma movimentação de 235GB entre datasets, uma reconstrução de ACLs) tinham de fato terminado e o load average tinha voltado para perto de zero. Fazer benchmark de um pool que ainda está digerindo o trabalho de ontem é só medir contenção, não os discos.

TesteResultado
Escrita, com buffer138 MB/s
Escrita, O_DIRECT15,4 MB/s
Leitura, com buffer1,1 GB/s
Leitura, O_DIRECT931 MB/s

Essa linha de escrita não é erro de digitação, e me surpreendeu tanto que conferi duas, três vezes se não era contenção de outra coisa antes de acreditar: escritas O_DIRECT saíram cerca de 9x mais lentas que escritas com buffer neste pool, o oposto da intuição que a maioria das pessoas traz de outros sistemas de arquivos (“direct I/O pula uma camada, então deveria ser mais rápido”). No ZFS especificamente, essa intuição se inverte. O caminho com buffer não é só “cache” — é onde o ZFS faz sua otimização de escrita de verdade: as escritas que chegam são agrupadas na memória e gravadas no vdev RAIDZ como parte de um transaction group, alinhadas e combinadas em escritas eficientes de stripe completo. O O_DIRECT, por design, pula exatamente essa camada de agrupamento, então cada escrita precisa ir direto para o vdev por conta própria — o que, num array baseado em paridade, pode significar I/O menor e menos alinhado, com o overhead que vem junto. Contornar o cache aqui não contorna nenhuma ineficiência real; contorna justamente a coisa que estava deixando as escritas eficientes. Atualização (6 de outubro de 2026): a maior parte dessa diferença de 9x acabou não sendo culpa do ZFS. O firmware do servidor tinha desligado o cache de escrita dos próprios SSDs, então cada escrita não agrupada tinha que esperar pela própria memória flash (e os 138 MB/s com buffer também eram baixos). A explicação do agrupamento abaixo continua verdadeira, mas era a parte menor. História completa: Duas coisas que faltavam nos meus SSDs: TRIM depois do BitLocker e um cache de escrita que meu servidor HPE desligou discretamente. Os números de leitura ganham o mesmo asterisco de antes: isto é throughput single-thread de um único arquivo, não uma imagem realista do desempenho agregado do pool sob carga concorrente, e ambos os valores de leitura podem ter sido servidos em parte pelo ARC em vez de vir do disco — o ARC não é a mesma coisa que o page cache do Linux, então echo 3 > /proc/sys/vm/drop_caches não faz nada para limpá-lo, e o caminho de leitura O_DIRECT do OpenZFS continua te entregando alegremente blocos que estão no ARC em vez de forçar uma leitura real do disco se os dados já estiverem lá. Encare números de uma única execução de dd como um teste de sanidade de “tem algo obviamente quebrado?”, não como uma ficha técnica para colocar num slide de vendas — e, se você for lembrar de uma coisa só desta seção, que seja “não presuma que O_DIRECT é o caminho rápido sem medir antes no seu sistema de arquivos específico”.

👨‍👩‍👧 Por que cada usuário ganha seu próprio dataset

O pool atende três pessoas, cada uma com um share Samba. A raiz do share de cada pessoa é seu próprio dataset ZFS (storage/user3, storage/user1, storage/user2) em vez de três diretórios simples dentro de um dataset grande. Isso não foi um padrão em que eu caí por acaso — é uma escolha estrutural deliberada, e ela compensa de formas com as quais uma árvore de diretórios compartilhada simplesmente não consegue competir:

  • Quotas. zfs set quota=500G storage/user2 limita um usuário sem mexer nos outros. Uma quota é uma propriedade do dataset; um diretório não tem esse conceito por si só, por mais severamente que você peça.
  • Snapshots independentes. zfs snapshot storage/user2@before-cleanup permite que uma pessoa desfaça um momento ruim de “apagar tudo” sem arrastar os outros dois datasets junto.
  • Contabilidade de uso instantânea. zfs list lê o uso de espaço direto dos metadados do dataset. Nada de percorrer a árvore, nada de du -sh moendo centenas de gigabytes de arquivos pequenos por um minuto e meio enquanto você encara um cursor piscando e questiona suas escolhas de carreira.
  • Fronteiras de propriedade limpas. O mountpoint de cada dataset corresponde 1:1 ao seu share Samba, com seu próprio dono Unix. As permissões do sistema de arquivos e as do share ficam em sincronia, em vez de depender só de truques na camada do Samba.
  • Ajuste por dataset. Compressão, atime, record size — tudo pode ser sobrescrito por dataset se a carga de um usuário um dia justificar algo diferente do padrão do pool.
  • Replicação granular. zfs send/receive funciona por dataset. Quer fazer backup só do share de uma pessoa num disco externo sem mexer nos outros? Uma linha só, não uma lista de exclusões seletiva do rsync mantida de pé à base de arrependimento.

O preço de tudo isso: mover dados entre datasets deixa de ser de graça. 😬 Um mv dentro de um único dataset é um simples rename — só metadados, instantâneo independentemente do tamanho. Um mv entre datasets é um bicho completamente diferente, mesmo que os dois datasets estejam no mesmo pool e nos mesmos discos físicos: o ZFS trata cada dataset como um sistema de arquivos próprio, então o kernel precisa de fato copiar cada byte para o novo local e depois apagar o original. Reaprendi isso do jeito divertido enquanto desembaraçava uma confusão de pastas aninhadas — um achatamento dentro do mesmo dataset terminou na hora, e uma movimentação de ~235GB entre datasets ficou lá por boa parte de uma hora fazendo, para todos os efeitos práticos, uma cópia completa, enquanto eu encarava um terminal sem barra de progresso me perguntando se tinha quebrado alguma coisa. Não é você, ZFS, são as fronteiras dos datasets. Vale saber antes de disparar um esperando a mágica de três segundos do anterior.

🔑 Um admin, três shares: por que um simples chmod não dava conta

O modelo de acesso que eu queria é simples de dizer em voz alta: cada um tem acesso total à sua própria pasta, e eu, além disso, tenho acesso total às pastas de todo mundo, tanto no share Samba quanto no sistema de arquivos Linux bruto por baixo. Simples de dizer — e aí eu tentei de verdade montar isso com o chmod clássico e bati na hora na parede em que todo sysadmin bate uma hora: um arquivo Unix tem exatamente um dono e exatamente um grupo. Só isso. Esse é o elenco inteiro. Todo o resto cai no único balde chamado “other”. Esse modelo consegue expressar “o dono tem acesso” e “este grupo tem acesso” — não consegue expressar “user1 tem acesso E user3 também tem acesso, mas user2 não”, porque não existe um segundo slot de grupo para colocar o user3 sem também inventar um grupo compartilhado, decidir quem mais pode entrar nele depois e torcer para ninguém adicionar a pessoa errada daqui a seis meses. Você pode contornar isso adicionando o user3 como membro secundário dos grupos privados do user1 e do user2 e ativando o bit setgid para que novos arquivos herdem o grupo — e, para muitos setups, essa é uma resposta perfeitamente boa, entediante e de pouco esforço. Aqui eu não gostei dela por dois motivos: ela concede acesso no nível do grupo (então muda em silêncio se a associação ao grupo mudar algum dia por um motivo não relacionado), e a herança em arquivos novos depende do bit setgid mais a umask que o processo criador estiver usando — o que funciona, mas “funciona porque três mecanismos separados se alinharam corretamente” não é uma frase que inspire confiança às 2 da manhã. As ACLs POSIX resolvem o problema real em vez de contorná-lo: elas permitem que um arquivo ou diretório carregue entradas adicionais, nomeadas explicitamente de usuário e de grupo, além da tríade clássica owner/group/other. “user1 é o dono disto, e user3 especificamente também tem rwx, ponto final” — sem grupo compartilhado, sem espectadores. Primeiro, o suporte a ACL precisa ser ativado por dataset (desligado por padrão):

zfs set acltype=posixacl storage/user1
zfs set acltype=posixacl storage/user2

Depois a concessão em si, em duas partes — uma concessão recursiva para tudo o que já existe e uma ACL default para que tudo o que for criado daqui em diante herde automaticamente a mesma regra, sem depender da roleta da umask:

setfacl -R    -m u:user3:rwx /storage/user1       # apply to everything that exists now
setfacl -R -d -m u:user3:rwx /storage/user1       # apply to everything created from now on

As mesmas duas linhas para /storage/user2. Junto com as permissões de cada pasta travadas em 750 (só dono e grupo, nada para “other” — então user2 e user1 categoricamente não conseguem entrar nos dados um do outro nem por acidente), o estado final é exatamente o objetivo declarado: cada pessoa manda na sua própria pasta, eu mando nas três, e ninguém ganha uma porta lateral acidental. Vale a pena conferir o efeito real em vez de confiar que o comando não virou um no-op silencioso:

$ getfacl /storage/user1
user::rwx
user:user3:rwx
group::r-x
mask::rwx
other::---
default:user::rwx
default:user:user3:rwx
default:group::r-x
default:mask::rwx
default:other::---

E do lado do Samba, esse trabalho com ACLs acabou importando menos do que eu esperava — os três shares já usam force user, o que faz toda conexão a um share operar como o dono daquele share, independentemente de quem realmente se autenticou. Então meu acesso aos shares do user1 e do user2 via SMB já estava coberto por essa diretiva, desde que a pasta por baixo realmente pertencesse à pessoa certa — o que, num divertido episódio de arqueologia autoinfligida, por um tempo não era o caso (um resto de uma reorganização anterior tinha deixado um dataset com dono eu em vez do usuário real, me dando em silêncio um acesso de escrita via SMB que eu não pretendia e negando à dona legítima da pasta os direitos padrão dela, até eu perceber e corrigir). As ACLs fecham especificamente a outra lacuna: o acesso puro via SSH / shell local, que não passa pelo force user e responde só às permissões Unix brutas.

😵 “Peraí, isso ainda é um pool só?” — a confusão do df

Algumas semanas depois de colocar isso para rodar, um rápido df -h fez parecer que algo tinha dado muito errado:

Filesystem       Size  Used Avail Use% Mounted on
storage          1.9T  256K  1.9T   1% /storage
storage/user3    3.1T  1.2T  1.9T  40% /storage/user3
storage/user1    1.9T   15G  1.9T   1% /storage/user1
storage/user2    2.1T  236G  1.9T  12% /storage/user2

Quatro valores diferentes de “Size”, num pool que deveria ser um bloco unificado de armazenamento agindo como um RAID5. Ele se fragmentou em silêncio em pools separados durante a noite? Eu configurei algo errado? 😱 Não — isso é o df sendo tecnicamente correto da forma menos útil possível. Datasets ZFS não têm um tamanho fixo como uma partição RAID clássica. A coluna “Size” do df é calculada por mount como Used + Available, e — esta é a parte que realmente importa — Available é idêntico em todos os datasets, porque é o mesmo espaço livre compartilhado no mesmo pool. Só “Used” difere, porque esse é de fato diferente para cada pessoa. Rode zfs list em vez disso e o mistério acaba:

$ zfs list -r storage
NAME                USED  AVAIL  REFER  MOUNTPOINT
storage            1.67T  1.85T   160K  /storage
storage/user1      14.3G  1.85T  14.3G  /storage/user1
storage/user2       235G  1.85T   235G  /storage/user2
storage/nextcloud   232G  1.85T   232G  /storage/nextcloud
storage/user3      1.20T  1.85T  1.20T  /storage/user3

O mesmo AVAIL — 1.85T — em todas as linhas, porque é um pote compartilhado. O “size” de 3.1T do user3 no df é só 1.20T usados + 1.85T disponíveis; os 1.9T do user1 são 14.3G + 1.85T. Nada fragmentado, nada perdido — no momento em que alguém grava um gigabyte, esse AVAIL compartilhado cai para todo mundo de uma vez, que é exatamente o comportamento tipo RAID5 que se esperava desde o início. O zpool list resolve de vez:

$ zpool list storage
NAME      SIZE  ALLOC   FREE  CKPOINT  EXPANDSZ   FRAG    CAP  DEDUP    HEALTH
storage  5.45T  2.50T  2.95T        -         -     0%    45%  1.00x    ONLINE

Um pool, 5.45T brutos, um vdev RAIDZ1, os três discos nele. O df só não foi feito pensando em “vários sistemas de arquivos compartilhando dinamicamente um pool de capacidade” — ele está informando honestamente, só está respondendo a uma pergunta (“qual o tamanho deste mount”) que aqui não se aplica do mesmo jeito. zfs list / zpool list são as ferramentas que de fato respondem “quanto espaço eu tenho”, não o df.

📋 Cheatsheet: os comandos que eu realmente uso neste pool

Metade de aprender ZFS é perceber que o subcomando que você quer quase certamente já existe, enterrado sob um nome que faz todo o sentido em retrospecto. Aqui está o conjunto de trabalho para exatamente este setup — pool storage, datasets storage/user3, storage/user1, storage/user2, storage/nextcloud. Saúde do pool

# Is everything online? Any read/write/checksum errors?
zpool status storage

# One-line health summary, good for a cron/monitoring check
zpool status -x

# I/O activity per vdev, refreshed every 2s
zpool iostat -v storage 2

# Manually kick a trim outside the autotrim schedule
zpool trim storage

# Integrity scrub — reads and verifies every block against its checksum
zpool scrub storage
zpool status storage   # shows progress while it's running

Datasets: listagem e uso de espaço

# All datasets under the pool, with usage — instant, no tree walk
zfs list -r storage

# Include snapshots in the listing
zfs list -t all -r storage

# Just one dataset
zfs list storage/user2

Compressão: quanto ela realmente me rende

# The headline number: ratio of logical (pre-compression) to physical size
zfs get compressratio storage
zfs get compressratio storage/user3   storage/user1    storage/user2   storage/nextcloud

# Same thing, the manual way — logicalused is what it WOULD take uncompressed,
# used is what it actually takes on disk
zfs get logicalused,used storage

# Which compression algorithm is actually active per dataset
zfs get compression storage/user3   storage/nextcloud

Quotas e reservas

# Cap a user's dataset so they can't eat the whole pool
zfs set quota=500G storage/user2

# Guarantee a dataset a minimum amount of space, even if others fill up
zfs set reservation=100G storage/nextcloud

# See what's currently set
zfs get quota,reservation -r storage

Snapshots

# Take one
zfs snapshot storage/user2@2026-09-01-before-cleanup

# List them
zfs list -t snapshot -r storage

# Roll back to one (destroys anything written after it — says so loudly for a reason)
zfs rollback storage/user2@2026-09-01-before-cleanup

# Recover a single file without a full rollback — snapshots are browsable here
ls /storage/user2/.zfs/snapshot/2026-09-01-before-cleanup/

# Done with it
zfs destroy storage/user2@2026-09-01-before-cleanup

Propriedades: get/set, a forma geral

# Everything set on a dataset, and where each value comes from
# (default / inherited / local override)
zfs get all storage/user3   | grep -v default

# Set anything per-dataset — overrides pool default for that subtree only
zfs set atime=off storage/nextcloud
zfs set recordsize=1M storage/nextcloud   # bigger records suit large sequential files

ARC (o cache em RAM)

# Live stats: hit rate, size, current bounds
cat /proc/spl/kstat/zfs/arcstats | grep -E '^(size|c_max|c_min|hits|misses) '

# Or the friendlier summary, if arcstat is installed
arcstat 2

Replicação

# Full send of a dataset to another pool/host, piped over SSH
zfs snapshot storage/user2@backup-2026-09-01
zfs send storage/user2@backup-2026-09-01 | ssh backup-host zfs receive backuppool/user2

# Incremental send — only what changed since the last snapshot
zfs send -i storage/user2@backup-2026-08-01 storage/user2@backup-2026-09-01 | ssh backup-host zfs receive backuppool/user2

🚑 Troubleshooting: o que eu realmente precisei até agora

A maior parte da vida deste pool tem sido entediante, que é exatamente o objetivo de rodar ZFS — tédio é um recurso. Mas algumas coisas apareceram durante a montagem que vale a pena ter registradas para a próxima vez, guardadas aqui para que o eu do futuro não precise reaprender nada disso do jeito difícil duas vezes. Pool está DEGRADED ou um disco aparece como FAULTED

# First stop: what exactly is wrong, and with which vdev/disk
zpool status -v storage

# Confirm the disk is still physically present and matches the pool's idea of it
ls -la /dev/disk/by-id/ | grep WD_Red

# Once the disk is physically replaced, tell ZFS to resilver the new one in
zpool replace storage ata-WD_Red_SA500_2.5_2TB_OLDSERIAL ata-WD_Red_SA500_2.5_2TB_NEWSERIAL

# Watch the resilver progress
zpool status storage

# If a disk had a transient error but is actually fine (loose cable, one-off glitch),
# clear the error counters instead of replacing anything
zpool clear storage

Resilver ou scrub parece travado / está demorando uma eternidade

# Check it's actually making progress, not hung
zpool status storage   # look at the % done and time-remaining estimate, run twice a few minutes apart

# See if something else is hammering the pool's I/O concurrently
zpool iostat -v storage 2

# Scrub/resilver speed is throttled by design so it doesn't starve normal I/O;
# these bump the priority if you genuinely need it to finish faster
cat /sys/module/zfs/parameters/zfs_scan_vdev_limit
echo 33554432 > /sys/module/zfs/parameters/zfs_scan_vdev_limit   # example: raise the per-vdev scan limit

Dataset não monta / “filesystem already mounted” / “dataset is busy”

# What does ZFS think is mounted where
zfs mount

# Force ZFS to (re)mount everything it thinks should be mounted
zfs mount -a

# "Device or resource busy" on unmount usually means an open file handle —
# find who's holding it
lsof +D /storage/user2
fuser -vm /storage/user2

# Last resort: force-unmount (drops any open handles, use with care)
umount -l /storage/user2

“Permission denied” ao mover/gravar no dataset de outro usuário Dei de cara com isso ao mover os arquivos da user2 para o dataset dela como o usuário Unix user3 — o dono e o modo do dataset não concedem acesso de escrita, por design, e o ZFS não estava nem aí para as minhas desculpas. Ou faça a operação como root, ou corrija o dono depois:

# Check who actually owns the mountpoint and what the mode is
ls -ld /storage/user2

# Do the privileged operation, then hand ownership back if root touched it
chown -R user2:user2 /storage/user2

Módulo de kernel do ZFS sumiu depois de uma atualização de kernel Como ele é compilado via DKMS (out-of-tree), um kernel novo significa que o DKMS precisa recompilar zfs.ko/spl.ko contra ele antes que o módulo carregue — isso normalmente acontece automaticamente como parte do postinst do pacote do kernel, mas é a primeira coisa a verificar se um pool se recusa a importar depois de um reboot e você fica por um instante convencido de que perdeu 3,6TB de dados para o vazio:

# Is the module actually loaded for the running kernel?
lsmod | grep zfs

# Does DKMS have a built module for this exact kernel version?
dkms status

# If not, force a rebuild against the current kernel
dkms install zfs/$(dkms status zfs | head -1 | cut -d, -f2 | tr -d ' ')  -k $(uname -r)

# Then try importing again
zpool import storage

Um serviço dependente (GitLab, um container, qualquer coisa) sobe antes de o pool estar montado Sintoma: o serviço sobe normalmente, mas grava num diretório vazio do sistema de arquivos raiz em vez dos dados reais no ZFS, porque o mountpoint dele ainda não estava pronto no boot — em silêncio, sem erro, que é o pior tipo de bug. Verifique a ordem real no systemd em vez de presumir que está tudo certo:

# Does local-fs.target really wait for this dataset's mount unit?
systemctl show local-fs.target -p After | tr ' ' '\n' | grep storage

# Is the mount unit itself enabled and correctly ordered before local-fs.target?
systemctl show storage-user2.mount -p Before,After,WantedBy

# And does the dependent service start late enough (after multi-user.target,
# which itself sits after local-fs.target)?
systemctl show gitlab-runsvdir.service -p After

O espaço livre “sumiu” e o du não explica

# Snapshots hold on to space for blocks that changed since they were taken —
# a forgotten snapshot is the single most common cause of "where did my space go"
zfs list -t snapshot -r storage -o name,used,creation

# See exactly how much of a dataset's usage is snapshots vs. live data
zfs get usedbydataset,usedbysnapshots storage/user2

O ARC está comendo toda a RAM

# Confirm it's actually ARC and not something else
free -h
cat /proc/spl/kstat/zfs/arcstats | grep '^size '

# Confirm the cap is actually applied (compare against zfs_arc_max in modprobe.d)
cat /sys/module/zfs/parameters/zfs_arc_max

# If the modprobe.d change hasn't taken effect yet, push it live without a reboot
echo 17179869184 > /sys/module/zfs/parameters/zfs_arc_max

🏁 Layout final

$ zpool status storage
  pool: storage
 state: ONLINE
config:
        NAME                                       STATE
        storage                                    ONLINE
          raidz1-0                                 ONLINE
            ata-WD_Red_SA500_2.5_2TB_25273ZD00458   ONLINE
            ata-WD_Red_SA500_2.5_2TB_25273ZD01387   ONLINE
            ata-WD_Red_SA500_2.5_2TB_25273ZD02050   ONLINE
errors: No known data errors

$ zfs list -r storage
NAME               USED  AVAIL  REFER  MOUNTPOINT
storage           ...    3.5T   ...    /storage
storage/user3      ...    3.5T   ...    /storage/user3
storage/user1      ...    3.5T   ...    /storage/user1
storage/user2      ...    3.5T   ...    /storage/user2

Três SSDs, redundância equivalente a um disco de paridade, compressão transparente que não custa nada e datasets por usuário que transformam quotas, snapshots e backups numa linha só em vez de num projeto. Nada mal para uma tarde — mesmo contando os dez minutos que passei brigando com um bug que não era real e os cinco minutos em que fiquei impressionado com um benchmark que era, na verdade, pura ficção. 🎉


📚 Mais nesta série: o NAS RAIDZ1

Alguns textos e imagens deste site foram criados com a ajuda de IA ou gerados por IA. Detalhes