ZFS Plugin For OMV8

This guide covers installation, configuration, and daily use of the openmediavault-zfs plugin. It assumes OpenMediaVault 8 (OMV8) is already installed and operational.

1. 1. What is ZFS?
2. 2. Prerequisites
3. 3. Installation
4. 4. Understanding ZFS Structure
5. 5. Pool Management
6. 6. Dataset Management
7. 7. Snapshots
8. 8. Encryption
9. 9. Scheduled Snapshot Jobs
10. 10. Scheduled Scrub Jobs
11. 11. Replication Jobs
12. 12. Properties
13. 13. Discovery (OMV Sync)
14. 14. Dashboard Widgets and ARC Statistics
15. 15. Settings
16. 16. Tips and Best Practices

ZFS (Zettabyte File System) is a mature, enterprise-grade filesystem and logical volume manager originally developed by Sun Microsystems for Solaris and now maintained by the OpenZFS project on Linux. It combines the roles of a traditional filesystem and a volume manager into a single unified layer, which gives it capabilities that older filesystems like ext4 or XFS cannot match.

Copy-on-write with checksums. Every block is checksummed when written and verified when read. If a checksum mismatch is detected (bit rot, failing drive, firmware bug) ZFS knows exactly which block is corrupt. In a redundant pool it can automatically repair the corruption from the good copy without any user intervention.

Snapshots and clones. A snapshot is a read-only, point-in-time copy of a filesystem. It consumes no space at creation — space is only used as data in the original filesystem diverges from the snapshot. Clones are writable copies derived from a snapshot.

Pooled storage. Disks are combined into a pool. One or more filesystems and volumes live inside the pool and share its available space. There are no fixed partition sizes to worry about.

Built-in RAID. RAID is handled by ZFS natively through its VDEV system. No separate hardware RAID controller is required or recommended.

Compression. Transparent, per-dataset compression (LZ4, Zstandard, gzip, etc.) can reduce storage consumption and often increase throughput because less data is written to disk.

Self-healing. When a scrub detects corruption in a redundant pool, ZFS restores the damaged data automatically from the surviving copy.

RAM requirements. ZFS does not require large amounts of RAM to function correctly. It will use available RAM for the Adaptive Replacement Cache (ARC) to speed up reads, but this is a benefit rather than a burden — the ARC is sized dynamically and returns memory to other processes when needed. A system with 4–8 GB of RAM running a home NAS workload is perfectly fine.

ECC memory. ECC RAM is desirable because it prevents the CPU from writing corrupted data to disk in the first place. It is not required — ZFS's checksumming still catches errors that reach storage regardless.

• 64-bit (amd64) system. ZFS on Linux is not supported on 32-bit or ARM single-board computers such as the Raspberry Pi.
• OMV-Extras plugin installed (provides access to additional plugins including this one and the Kernel plugin).
• Proxmox kernel (strongly recommended). The standard Debian backports kernel can lose ZFS module packages across kernel upgrades, causing pools to become inaccessible. The Proxmox kernel ships with prebuilt ZFS modules and is updated in lockstep with the ZFS packages, eliminating this risk. Install it via the Kernel plugin before installing openmediavault-zfs.

1. In the OMV web interface, go to System → Update Management and apply all pending updates.
2. If you have not already done so, install the Kernel plugin from System → Plugins, then use it to install the Proxmox kernel and reboot.
3. Go to System → Plugins, search for zfs, and install openmediavault-zfs.
4. After installation the Storage → ZFS section appears in the navigation.

Before creating anything, it helps to understand how ZFS organises storage.

Pool (tank)
├── VDEV 1 — mirror: sda, sdb       ← redundancy lives here
├── VDEV 2 — mirror: sdc, sdd       ← adding a second VDEV expands capacity
├── [log VDEV]                       ← optional sync write accelerator (SLOG)
├── [cache VDEV]                     ← optional read cache (L2ARC)
└── [spare]                          ← optional hot spare

Datasets inside the pool
├── tank                             ← pool root (itself a dataset)
├── tank/documents
├── tank/media
│   ├── tank/media/movies
│   └── tank/media/music
└── tank/vm-disks
    └── tank/vm-disks/win11          ← a zvol (block device), not a filesystem

A pool is the top-level storage container. It is built from one or more VDEVs.

A VDEV (Virtual Device) is the redundancy unit. The most important rule: if a VDEV fails entirely, the pool is lost. Redundancy protects against individual disk failures within a VDEV, not between VDEVs.

A basic VDEV can be converted to mirror, but a mirror VDEV cannot be converted to a RAIDZ VDEV and RAIDZ1 cannot later become a RAIDZ2 VDEV. Adding more disks to expand a RAIDZ VDEV is possible via RAIDZ expansion (if the pool has feature@raidz_expansion active) but this is a slow, one-at-a-time process.

Datasets are the filesystems and volumes that live inside a pool. There are three types:

• Filesystem — a mounted directory tree, like a normal folder.
• Volume (zvol) — a block device that appears as a raw disk. Used for virtual machine images, iSCSI targets, or anything that needs a block interface.
• Snapshot — a read-only point-in-time copy of a filesystem or volume.

Datasets inherit properties from their parent unless overridden. Creating a child dataset tank/media/movies with a different recordsize than tank/media is valid — only the property on tank/media/movies changes.

Always create at least one named filesystem under the pool and use that for data. The pool root dataset is typically left with minimal configuration and its mountpoint set to none or /tank. This keeps administration cleaner and preserves flexibility for property inheritance.

Navigate to Storage → ZFS → Pools.

Click Pool → Add pool. The form fields are:

After the pool is created it appears in the table with its health state, size, free space, and fragmentation.

Select a pool and use the action menus:

To replace all disks in a VDEV with larger ones (for example, upgrading from 4 TB to 8 TB drives in a mirror):

1. Replace one disk at a time using Device → Replace. Wait for resilvering to complete (zpool status shows scan: resilvered … with 0 errors).
2. Repeat for each disk in the VDEV.
3. Once all disks are replaced, the pool will automatically expand to use the full capacity because autoexpand is enabled by default on new pools.

Navigate to Storage → ZFS → Datasets. The table shows all pools, filesystems, volumes, and snapshots in a hierarchy. Use the Type filter at the top to show only filesystems, only snapshots, etc.

Select a pool or parent filesystem and click Add → Add filesystem.

After creating a filesystem it can be used as a shared folder target in OMV (Storage → Shared Folders) once registered with Discover → Add new (see Section 13).

Select a pool or parent filesystem and click Add → Add volume.

Volumes appear as block devices under /dev/zvol/<pool>/<name>.

Select a filesystem or volume and click Add → Add snapshot.

Alternatively, Add → Quick snapshot creates a snapshot with an auto-generated timestamp name (<dataset>@<dataset>-YYYYMMDD-HHMMSS) without prompting. Add → Quick recursive snapshot does the same recursively.

A clone is a writable filesystem derived from a snapshot.

Select a filesystem and click Clone. The plugin automatically creates a snapshot of the source dataset (named <source>-clone-base-YYYYMMDD-HHMMSS) and uses it as the clone origin. The clone initially shares all data blocks with the source and uses no additional space.

Cloned datasets cannot be encrypted independently — they inherit the encryption root of their origin. To create an independent encrypted dataset, promote the clone first.

A clone depends on its origin snapshot — the origin cannot be deleted while the clone exists. Promote reverses this relationship: the clone becomes the independent dataset and the origin becomes dependent on it instead.

Select a clone and click Promote. After promotion the original source dataset becomes the dependent and can be deleted independently.

Select a filesystem or volume and click Rename. The dataset is renamed in ZFS, its mountpoint is updated, and OMV's fstab database is updated to reflect the new path.

Renaming a dataset that has active shared folders is blocked — remove the shares first.

Select any dataset and click Delete. The plugin checks for dependent clones and active shares before proceeding. Snapshots of a filesystem are listed and must be removed (or confirmed) before the parent can be deleted.

For encrypted datasets with auto-unlock configured, always delete through the plugin rather than via zfs destroy on the command line — the plugin cleans up keyfiles, systemd units, and the ZFS list cache correctly. See the README for manual cleanup steps if needed.

Storage → ZFS → Snapshots shows all snapshots across all pools with their size, referenced data, creation time, and origin.

Select a snapshot to access:

ZFS snapshots are accessible in the .zfs/snapshot/<name>/ hidden directory under the filesystem's mountpoint. For example, if tank/documents is mounted at /tank/documents, the snapshot tank/documents@2024-01-15 is browsable at:

/tank/documents/.zfs/snapshot/2024-01-15/

No mounting or special tools are needed — simply copy the file back from the snapshot directory.

ZFS native encryption protects dataset contents at rest. The encryption key is required to mount and read a dataset. Without the key the data is unreadable even with physical access to the disks.

Select a pool or parent filesystem and click Add → Add encrypted filesystem.

<note>Note on child datasets: Child filesystems created under an encrypted dataset inherit the encryption and key of their parent. They share the same encryption root and are unlocked and locked together with the parent.</note>

A locked dataset is unmounted and its contents are inaccessible. To lock a dataset, select it and click Encryption → Unload key (lock). To unlock it, click Encryption → Load key (unlock) and enter the passphrase.

Cloned datasets that are not the encryption root cannot be independently locked or unlocked — use the original encryption root instead.

Local auto-unlock stores the passphrase as a file in /etc/zfs/keys/ and configures ZFS to load the key automatically at boot. This protects against drive theft (an attacker who steals only the disks cannot read them without the server) but does not protect against someone who steals the entire server.

Select an encrypted dataset and click Encryption → Enable auto-unlock → Local file. Enter the passphrase to confirm. The plugin:

1. Writes the keyfile to /etc/zfs/keys/<pool_dataset>.key.
2. Sets keylocation=file:/etc/zfs/keys/<pool_dataset>.key on the dataset. - Unmasks the zfs-load-key@<instance>.service systemd unit so it runs at boot. - Writes the dataset path into the ZFS list cache so zfs-mount-generator generates the correct mount unit. To remove auto-unlock, click Encryption → Disable auto-unlock. The keyfile is deleted, keylocation is reset to prompt, and the systemd unit is masked so no passphrase prompt appears at boot (the dataset simply stays locked until manually unlocked). ==== Auto-unlock: remote HTTPS ==== Remote auto-unlock fetches the encryption key from an HTTPS server at boot. The key is never stored on the local machine. This protects against both drive theft and full server theft — an attacker cannot decrypt the data without network access to the key server. Select an encrypted dataset and click Encryption → Enable auto-unlock → Remote HTTPS. ^ Field ^ Description ^ | Key URL | Full HTTPS URL where the key material is served. Must begin with https:. |

| Skip certificate verification | Disable TLS certificate validation. Use only with self-signed certificates on a trusted network. |

The zfs-remote-unlock service runs at boot, fetches the key, and loads it before the ZFS mount units start.

Select an encrypted dataset and click Encryption → Change encryption key. Enter the current passphrase and the new passphrase. The key change applies to the encryption root; all child datasets sharing the root are automatically covered.

Navigate to Storage → ZFS → Snapshot Jobs.

Snapshot jobs run omv-zfs-snapshot on a schedule to create snapshots automatically and prune old ones according to your retention policy.

Click Add to open the form.

• Count mode: After creating the new snapshot, count all snapshots whose names match the prefix. Delete the oldest ones until only Keep remain.
• Time mode: Delete any snapshot whose embedded timestamp is older than Keep units ago. For example, Keep=30, Days deletes snapshots older than 30 days.

Select a job in the table and click Run. The job executes immediately in the background. Check Storage → ZFS → Logs → ZFS Snapshot to see the output.

Navigate to Storage → ZFS → Scrub Jobs.

Scrub jobs run zpool scrub on a schedule to periodically verify pool integrity. The scrub reads every block, checks its checksum, and repairs any corruption it finds using redundant copies. Regular scrubbing is the primary mechanism for detecting and correcting silent corruption before it spreads.

<note important>Important: A scrub job starts the scrub and exits immediately. The actual scrub runs asynchronously in the background and may take hours on a large pool. Monitor progress via Pool → Scrub → Scrub status or zpool status in the shell.</note>

Recommended schedule: Monthly is sufficient for healthy pools on consumer hardware. Weekly is appropriate for pools under heavy write load. Scrubbing is I/O-intensive — schedule it during off-peak hours.

Navigate to Storage → ZFS → Replication Jobs.

Replication jobs copy a ZFS dataset (and its snapshots) to another location using zfs send and zfs receive. Subsequent runs send only the incremental difference since the last replication, making them efficient even for large datasets. Replication can target a local pool or a remote host over SSH.

Same scheduling and email options as snapshot and scrub jobs.

Scenario: daily replication with independent snapshot retention

This is the most common setup. A snapshot job manages snapshots on the source; the replication job sends them to the destination without creating its own.

1. Create a snapshot job for tank/documents with prefix daily, execution Daily, keep 30 Days.
2. Create a replication job for tank/documents with prefix daily, execution Daily, Use existing snapshots enabled, Keep snapshots on source = 0, destination backup/documents on a local backup pool.

The snapshot job runs first (or within the same cron minute), then the replication job sends the newest daily-* snapshot incrementally.

Scenario: self-contained replication with source pruning

When no separate snapshot job exists:

1. Create a replication job for tank/vm-disks with prefix replicate, keep 3 on source, destination on a remote server.

The replication job creates its own snapshot, sends it, then prunes old replication snapshots on the source to keep only 3.

Scenario: efficient replication with bookmarks

Suitable when disk space on the source is limited:

1. Create a snapshot job for tank/photos with prefix weekly, keep 1 Snapshots.
2. Create a replication job for tank/photos with prefix weekly, Use existing snapshots enabled, Use ZFS bookmarks enabled.

The replication job uses the bookmark from the previous run as its incremental base, so the single retained snapshot is sufficient — there is no need to keep an older snapshot just for the next send.

Before creating a remote replication job:

1. In OMV, go to System → Certificates → SSH and generate a new SSH key pair.
2. Click Copy to Remote for that certificate, entering the destination host, user, and password. This copies the public key to ~/.ssh/authorized_keys on the remote host.
3. In the replication job form, select that certificate under SSH Certificate.

The replication script uses strict host key checking — the first connection to a new host is accepted automatically, but subsequent connections reject unknown key changes.

Job output is written to /var/log/omv-zfs-replicate.log and is also viewable in the OMV web interface under Storage → ZFS → Logs → ZFS Replicate.

ZFS properties control the behaviour of pools and datasets. They can be inherited from a parent (shown as source inherited) or set explicitly on a dataset (source local).

Select any pool, filesystem, volume, or snapshot and click Properties. The table shows every property, its current value, its source, and whether it can be edited. Click the edit icon on a row to change a property's value.

Custom user-defined properties (in namespace:name format) can also be added.

Select a dataset and click Details to see the raw output of zpool status -v (for pools) or zfs get all (for filesystems, volumes, and snapshots). This is useful for debugging or checking the exact value of any property without the filtered view.

ZFS filesystems must be registered in OMV's internal database before they can be used as shared folder targets. Discovery synchronises OMV's fstab database with the live ZFS state.

This is accessible from both the Pools table and the Datasets table under Discover.

<note>Note: The plugin backs up config.xml before every discovery operation. The 20 most recent backups are kept at /etc/openmediavault/config.xml.<timestamp>.</note>

<note>Locked encrypted datasets are never removed by Delete missing — the plugin recognises that a dataset may simply be locked rather than deleted.</note>

The plugin adds four dashboard widgets. Enable them via Dashboard → Configure widgets (the gear icon on the dashboard).

Navigate to Storage → ZFS → ARC Stats for a full text dump of ARC internals: total size, MRU/MFU cache sizes, hit/miss counters, prefetch statistics, and more. This is the same output as the arc_summary/zarcsummary command-line tool.

Five log viewers are available under Storage → ZFS → Logs:

Navigate to Storage → ZFS → Settings.

This page controls system-level ZFS tuning that applies globally, independent of any individual pool or dataset.

Changes are written to /etc/modprobe.d/zfs.conf and take effect after a reboot or after reloading the ZFS module.

Designing a ZFS pool layout is about balancing performance, redundancy, capacity, and future flexibility. Decisions made up front may be hard to change later, so plan carefully.

The optimum pool layout depends on how the data will be used. For sequential workloads (media, backups, archive) RAIDZ works well, but prefer RAIDZ2 for larger drives to reduce resilver second-failure risk. For random I/O (containers, VMs, databases) use mirrors — they offer the best combination of read performance (spread across disks), write performance, and faster resilver after disk replacement.

Do not add optional devices (log, cache, and/or special VDEV) without justification and understanding. For example, a “log device” is useless on a home NAS which does not generate sync writes (SMB shares do not, NFS shares do). Analyse first, but the answer to improving pool performance may simply be to add RAM.

For a mix of SSDs and HDDs, consider using the SSDs in a mirror pool and the HDDs in a separate RAIDZ pool. In a home NAS this separation is preferable to trying to enhance RAIDZ performance by using a log, cache, and/or special VDEV, which only adds complexity and cost (typical consumer SSD/NVMe devices are not suitable for these optional VDEVs).

Beware adding a basic VDEV to an existing mirror/RAIDZ pool. This turns a pool into a stripe, where losing a single drive can lose the entire pool.

• Use by-id device identification. Device names like /dev/sda can change after a reboot if drives are added or removed. Stable by-id paths ensure ZFS always finds the right disk.
• Enable compression on all datasets. lz4 is essentially free — it is so fast that on most systems it improves throughput even for data that compresses modestly.

• Create a filesystem per use case rather than dumping everything into the pool root. Separate datasets for documents, media, backups, and VM images let you tune recordsize, compression, and quotas independently.
• Set recordsize=1M for media libraries (movies, music, photos). Sequential reads of large files benefit enormously from large record sizes.
• Set recordsize=4K or 8K for database files (PostgreSQL, MySQL, SQLite). These databases do their own internal block management and need ZFS's blocks to match.
• Disable atime on busy datasets. Every file read normally triggers a metadata write to update the access time. atime=off eliminates this overhead.

• Automate snapshots with scheduled jobs rather than relying on manual creation. A daily snapshot job with 30-day retention costs almost nothing in disk space for typical NAS data and provides a safety net against accidental deletion.
• Name snapshot prefixes clearly. Use daily, weekly, monthly rather than auto when running multiple snapshot jobs per dataset at different frequencies.
• Do not delete the most recent common snapshot before replication. The replication script needs at least one snapshot that exists on both source and destination to perform an incremental send. Deleting it forces a full send.

• Schedule monthly scrubs at minimum. On systems with heavy write loads or older disks, weekly is better. Scrubs are the only way to find silent corruption before it becomes unrecoverable.
• Check scrub results in the ZFS Events log or via zpool status after each scrub. Any errors reported warrant investigation.

• Choose AES-256-GCM. It is the strongest available option and is hardware-accelerated on all x86-64 CPUs with AES-NI (essentially all modern systems).
• Keep a copy of your passphrase offline. A lost passphrase means permanently lost data. Store it in a password manager and print a copy kept in a physically secure location.
• Use remote HTTPS auto-unlock for maximum security. Local keyfile auto-unlock is convenient but an attacker who steals the whole server gets the key with the disks. A remote key server eliminates this risk.
• Always delete encrypted datasets through the plugin, not via zfs destroy. The plugin cleans up keyfiles, systemd units, and the ZFS list cache. A bare zfs destroy leaves orphaned artifacts.

• Test your replication jobs by running them manually and verifying the destination has the expected datasets. Check the replication log for errors.
• Use a separate snapshot job with Use existing snapshots rather than letting the replication job manage its own snapshots. This gives you independent control over local snapshot retention and avoids conflicts if you run multiple replication jobs for the same dataset.
• Remote replication requires a working SSH trust relationship. Use OMV's System → Certificates → SSH → Copy to Remote to set this up before creating the job.

You can use the documentation written for OMV7 as a reference as well but some things may be out of date.

Go to → ZFS Plugin For OMV7