OpenZFS Native Encryption Explained

OpenZFS native encryption lets NAS administrators and self-hosters encrypt selected datasets without placing a separate encrypted block device beneath the pool. This guide explains what the feature protects, how dataset keys and encryption roots work, how encrypted replication differs from a normal send, and how to test the setup safely on an existing pool.

Why OpenZFS Native Encryption Is Being Discussed

Storage systems increasingly keep snapshots and replicas on hosts outside the primary server’s trust boundary. A ZFS pool can protect data against device failures, while dataset encryption can make stored contents unreadable to someone who obtains the disks or an encrypted replication stream without its key. These are separate controls: redundancy preserves availability, while encryption limits access to data at rest.

Native encryption is also useful when only some datasets need a different key or when a receiver should store backup data without being able to read it. The design still depends on key custody, restore testing, and the exact OpenZFS version and platform in use.

What Is OpenZFS Native Encryption?

OpenZFS native encryption encrypts the contents of a ZFS dataset and its descendants using keys managed by ZFS. It is configured as a dataset property when the encrypted dataset is created. Unlike LUKS, it does not encrypt an entire block device; unlike fscrypt, it does not apply policies to individual directories in a supported Linux filesystem.

The OpenZFS project develops the cross-platform ZFS implementation. Its dataset property documentation describes encryption algorithms, key formats, key locations, and inherited properties. The OpenZFS key-management manual covers loading, unloading, and changing dataset keys.

The Problem Native Encryption Solves

Without encryption, a person who can read pool devices or a copied dataset may be able to inspect the stored files even if the normal network share and account controls are unavailable. File permissions protect access through a running system, but they do not by themselves protect data on removed disks or copied storage.

Encryption adds a confidentiality boundary around dataset contents while allowing ZFS to keep managing the pool. It does not hide every operational detail: pool layout, dataset names, properties, and some structural metadata may remain visible. It also does not protect plaintext after a key is loaded and the dataset is available to authorized processes. An administrator with sufficient access to a running host can generally read mounted data.

How OpenZFS Native Encryption Works

ZFS encrypts data as it is written and decrypts it for authorized reads after the relevant key is loaded. Encryption is configured on a dataset, which becomes an encryption root when it has its own key. Child datasets normally inherit the parent’s encryption root and key. A child can instead be created as a separate encryption root when independent key handling is required.

The encryption property selects the cipher suite. OpenZFS supports AES-CCM and AES-GCM variants; setting encryption=on selects the documented default for that release. The NIST specification for Galois/Counter Mode (GCM) defines an authenticated encryption mode used by supported OpenZFS cipher suites. Verify supported features on both systems rather than assuming every platform or pool has identical capabilities.

A crucial replication detail is that zfs send without raw mode sends data unencrypted. A raw send (zfs send -w) preserves the on-disk encrypted representation and can be received by a host that does not have the dataset key. The OpenZFS send manual documents this behavior. Protect the receiver and its administration anyway: a raw stream is not a substitute for access controls, retention, or a tested restore.

Key Concepts and Variants

Key format and location are different settings. keyformat describes whether ZFS reads a raw key, hexadecimal key, or passphrase. keylocation describes where it obtains that material, such as a prompt, a local file, or a supported URL. A passphrase is processed to produce the encryption key; protect local key files and remote key services as credentials.

Key status is operational state. keystatus reports whether an encryption root’s key is loaded. Loading a key makes the dataset usable; unloading it removes access after datasets are unmounted. Descendants that inherit the same encryption root share its key-loading state. Use separate roots only when separate access or recovery policies justify the extra administration.

Changing a passphrase is not the same as re-encrypting stored data. zfs change-key changes the user key or its properties for an encryption root without rewriting every block. The cipher suite is selected when the dataset is created and cannot simply be changed in place. For a different cipher, create a new encrypted destination and migrate data using a planned, verified procedure.

Snapshots follow dataset encryption. Snapshots and descendants remain associated with their encryption root. Encryption does not make a snapshot independent: snapshots can still consume pool space, share the pool’s failure domain, and be deleted by an administrator with sufficient privileges.

Raw replication preserves encrypted data. Use raw sends when the destination should not receive plaintext or when the source key is not loaded during transfer. Keep the required key material in a separate, recoverable location. If an encrypted receiver is later restored, test key loading and application access, not only whether the stream arrived.

Real-World Use Cases

• NAS shares: encrypt a dataset containing private documents while leaving public media or other pool datasets unencrypted.
• Off-host backups: send raw encrypted streams to a separately administered ZFS receiver so its storage operators do not need the dataset key.
• Service separation: create an encryption root for a sensitive workload and control which operators can unlock it.
• Disk retirement: encryption can reduce exposure from stored contents, but disposal processes should still account for key copies, unencrypted exports, and backups.

For pool, vdev, and day-to-day administration context, see ZFS Administration and Tuning. For retention and send/receive workflows, see ZFS Snapshots and Replication.

Getting Started and Verifying a Dataset

Install the OpenZFS userland and platform-supported kernel integration using your operating system’s instructions. For example, Debian and Ubuntu commonly package the command-line tools as zfsutils-linux; FreeBSD systems install OpenZFS with pkg install openzfs. Check the OpenZFS documentation for platform support and setup details.

The following commands create a new encrypted dataset in an existing pool and prompt for a passphrase. Replace tank with a pool you control. This creates a separate dataset; it does not encrypt existing datasets or the pool as a whole.

# Create a dataset with its own passphrase-protected encryption root.
sudo zfs create \
  -o encryption=on \
  -o keyformat=passphrase \
  -o keylocation=prompt \
  tank/private

# Inspect the encryption settings and whether the key is loaded.
sudo zfs get encryption,encryptionroot,keyformat,keylocation,keystatus tank/private

Before using this for important data, confirm the installed OpenZFS version supports encryption, make a separate backup, and decide how authorized services will load the key after reboot. Do not put a passphrase in a shell command, script, or world-readable configuration file. For unattended systems, use an access-controlled key service or protected key file and document the recovery path.

Test the key lifecycle only on a dataset that is safe to unmount:

# Unmount the dataset before unloading its key.
sudo zfs unmount tank/private
sudo zfs unload-key tank/private
sudo zfs get keystatus tank/private

# Load the passphrase again, then make the filesystem available.
sudo zfs load-key tank/private
sudo zfs mount tank/private
sudo zfs get keystatus,mounted,mountpoint tank/private

For backup transfer, a raw send preserves the encrypted stream. The snapshot name must exist, and the receiver must be an OpenZFS system with a compatible pool and sufficient capacity:

# Create a snapshot, then send its raw encrypted representation.
sudo zfs snapshot tank/private@backup-test
sudo zfs send -w tank/private@backup-test |
  ssh backup-host sudo zfs receive -u backup/private

Use a protected SSH identity and a destination that is not writable by untrusted users. Confirm the received snapshot and rehearse a restore using the recovery key. Avoid testing with commands that overwrite a production destination; understand the receive options and target dataset before automating replication.

Common Misconceptions

“Encrypting one dataset encrypts the entire pool.”

It does not. Encryption is a dataset property, not a pool-wide switch. Other datasets, boot devices, exports, logs, snapshots copied without raw mode, and backup copies may have different protection.

“A raw encrypted send means the backup can never be read.”

The receiver cannot read the data without the key, but anyone who later obtains both the encrypted stream and its key can. Protect keys separately, restrict access to the source and receiver, and test key recovery.

“Changing a passphrase rewrites every block.”

Changing the user key for an encryption root does not require rewriting the dataset’s stored data. It also does not recover data if all usable keys are lost. Keep an independently protected recovery path and test it before relying on a key change.

“Encryption replaces snapshots, redundancy, or backups.”

Encryption protects confidentiality; snapshots, mirrors, RAIDZ, and replication address other needs. None guarantees recovery from every failure. Maintain independent backups and periodically verify that files and services can be restored.

Related Articles

• Linux Filesystem Encryption Explained compares LUKS2 and fscrypt with practical recovery guidance.
• ZFS Snapshots and Replication explains local recovery points and incremental transfers.
• ZFS Administration and Tuning covers pools, datasets, and maintenance.
• Btrfs vs. ZFS compares filesystem architecture and operational trade-offs.
• Self-Hosted Backups covers backup isolation and restore testing.

Changelog

• Initial publication.

Last Updated

• Initial publication.