Skip to content

Encryption

gitsync edited this page Jul 14, 2026 · 6 revisions

ZNAS supports ZFS native AES-256-GCM encryption for pools and datasets. Encryption is handled entirely by the ZFS kernel module — the portal manages the key lifecycle.

How it works

  • Each encrypted pool or dataset has a raw key file stored in config/keys/
  • At startup, the portal automatically loads keys for all encrypted pools and datasets — encrypted volumes mount without manual intervention after a reboot
  • The ZFS kernel module encrypts/decrypts transparently

Creating encrypted storage

  • Encrypted pool: ZFS Pools → + Pool → enable the Encryption toggle → choose or generate a key
  • Encrypted dataset: Datasets & FS → + Dataset → Advanced Security section → enable Encryption

A padlock icon identifies encrypted pools and datasets throughout the UI.

Locking and unlocking

From the ⋮ menu of any encrypted dataset:

Action Effect
Lock Dataset Unmounts the dataset and unloads its key — data inaccessible until unlocked
Unlock Dataset Loads the key and mounts the dataset
  • Before locking, the portal checks for active SMB/NFS clients and warns you (with the option to force-disconnect)
  • Locking a dataset locks its children too
  • Stored keys unlock with one click; passphrase-based datasets (keylocation=prompt) prompt for the passphrase

Key Management

Settings → Key Management:

Operation Description
Generate Create a new random key file
Import Upload a key file (supports the TrueNAS export format)
Export Download a key file — keep an offline copy somewhere safe!
Delete Remove a key file (blocked while any pool/dataset uses it)

Each key shows a badge indicating which pool or dataset uses it.

TrueNAS compatibility: key files can be exchanged in both directions — export from TrueNAS and import here to migrate an encrypted pool, or vice versa.

Security considerations

Aspect Detail
Key storage config/keys/, readable only by the zfsnas OS user
Key format Raw 256-bit binary (keyformat=raw)
Key in transit Keys are never sent to the browser — only name/usage metadata
Removing encryption Not possible in-place; create an unencrypted dataset and copy data

Warning: without the key file (or passphrase), encrypted data is unrecoverable. Always export and safely store a copy of your keys.

Two-Factor Authentication (TOTP)

Portal logins can be protected with TOTP (RFC 6238) — see Security.

Clone this wiki locally