There's two types of "data" in the pool: the actual data of whatever it is you're storing, and the metadata, which is all the tables, properties, indexes and other "stuff" that defines the pool structure, the datasets, and the pointers that tell ZFS where on disk to find the actual data.

Normally this is all mixed in together on the regular pool vdevs (mirror, raidz, etc). If you add a special vdev to your pool, then ZFS will prefer to store the metadata there, and send the data proper to the regular vdevs. The main reason for doing this is if you have "slow" data vdevs; adding a special vdev of a SSD mirror can speed up access times, as ZFS can look to the SSDs to know where on the data vdevs to find its data and go directly there, rather than loading the metadata off the slow vdevs and then needing another access to get the real data.

There's another possible advantage: ZFS can store "small" files on the special vdev, leaving larger ones for the regular data vdevs.

One important thing to remember is that special vdevs are a proper part of the pool, not an add-on - just like the regular data vdevs, if the special vdev fails, the pool is lost. An SSD mirror is typical for this vdev.

This is only a rough explanation, see also:

  • zpoolconcepts(7)
  • Level1Techs writeup
🌐
OpenZFS
openzfs.github.io › openzfs-docs › Basic Concepts › VDEVs.html
VDEVs — OpenZFS documentation
December 2, 2025 - When there is still enough redundancy ... failed vdev with a new one and ZFS will automatically resilver (rebuild) the data onto the new vdev to return the pool to a healthy state. Vdevs are managed using the zpool(8) command-line utility....
Discussions

ZFS Metadata Special Device | Proxmox Support Forum
Hello all, I would like to configure a metadata special device for my ZFS mirror pool (2x HDD's, 18TB each) but I am not entirely sure of the steps. I've found some documentation online but I am still hesitant as I don't want to mess things up & then re-build the mirror. I do have data backed... More on forum.proxmox.com
🌐 forum.proxmox.com
June 16, 2023
Redundancy necessary for special Metadata vdev?
New to the forums, but not new to FreeNAS/TrueNAS. I've been running TrueNAS 12 and Fusion pools but had a few questions about it. I can't figure out if I need to set up redundant mirrored disks for the speical Metadata vdev. If the Metadata vdev is lost with a single drive, will the data vdev... More on truenas.com
🌐 truenas.com
13
June 16, 2020
How do I make a metadata special device vdev?
I would highly recommend using something more robust than raidz1 on a 100TB pool. The likelihood of an error during a rebuild of a pool of that magnitude is not inconsequential. If this is just a backup pool, then so be it, but if this is to be primary storage then you're gambling with your data. More on reddit.com
🌐 r/zfs
16
3
January 31, 2023
PBS and ZFS Special Allocation Class VDEV ... aka Fusion Drive | Proxmox Support Forum
I've been chewing on this for months. Getting hardware into place to test it. Won't bore you with the story. I didn't waste much money if it isn't wonderful, but I'm hoping for wonderful. Special VDEV is ... you can add a couple SSDs to a ZFS pool to speed it up. This isn't old-style hybrid... More on forum.proxmox.com
🌐 forum.proxmox.com
June 14, 2024
People also ask

What is a ZFS vdev?

A ZFS vdev (virtual device) is the fundamental storage building block of a zpool, defining how disks are grouped for performance and fault tolerance.

🌐
klarasystems.com
klarasystems.com › home › openzfs – understanding zfs vdev types
OpenZFS - Understanding ZFS vdev Types - Klara Systems
Which ZFS topology is fastest?

Mirror vdevs generally provide the highest performance and lowest latency, especially for random I/O workloads. 

🌐
klarasystems.com
klarasystems.com › home › openzfs – understanding zfs vdev types
OpenZFS - Understanding ZFS vdev Types - Klara Systems
What happens if a SPECIAL vdev fails?

Losing a SPECIAL vdev destroys the entire pool because critical metadata is stored on it. 

🌐
klarasystems.com
klarasystems.com › home › openzfs – understanding zfs vdev types
OpenZFS - Understanding ZFS vdev Types - Klara Systems
🌐
Cr0x
cr0x.net › tuning › zfs special vdev sizing: how big it should be (so you don’t regret it)
ZFS Special VDEV Sizing: How Big It Should Be (So You Don’t Regret It) – cr0x.net
February 3, 2026 - cr0x@server:~$ zfs list -o name,used,avail,refer,mountpoint tank NAME USED AVAIL REFER MOUNTPOINT tank 120T 48T 256K /tank · Output meaning: Pool space is not the same as special vdev space. This command doesn’t show special usage directly.
🌐
GitHub
openzfs.github.io › openzfs-docs › man › master › 7 › zpoolconcepts.7.html
zpoolconcepts.7 — OpenZFS documentation
But, when an active device fails, it is automatically replaced by a hot spare. To create a pool with hot spares, specify a spare vdev with any number of devices. For example, ... Spares can be shared across multiple pools, and can be added with the zpool add command and removed with the zpool ...
🌐
Proxmox
forum.proxmox.com › home › forums › proxmox virtual environment › proxmox ve: installation and configuration
ZFS Metadata Special Device | Proxmox Support Forum
June 16, 2023 - Thanks in advance! Click to expand... It is more or less not much more than: zpool add POOLNAME special mirror /dev/sdX /dev/sdY and for the blocksize: zfs set special_small_blocks=1M POOLNAME
🌐
GitHub
openzfs.github.io › openzfs-docs › man › master › 7 › vdevprops.7.html
vdevprops.7 — OpenZFS documentation
Setting to special and dedup requires feature@allocation_classes to be enabled. At least one top-level vdev must remain in the normal (none) class. ... Controls how I/O requests are added to the vdev queue when reading or writing to this vdev. This property can be set on leaf vdevs. The value of these properties do not persist across vdev replacement. ... Let ZFS ...
🌐
TrueNAS Community
truenas.com › forums › developer's corner
Redundancy necessary for special Metadata vdev? | TrueNAS Community
June 16, 2020 - Is there a way to set a different ashift for each vdev? Click to expand... TrueNAS should default to ashift=12 for all devices including the special mirror, and honestly you shouldn't use anything less than that with how common 512e drives are. Are you looking to increase the ashift value? Increasing TrueNAS SCALE ARC Size beyond the default 50% Do you have an SLOG device, or think you need one? Check benchmarks in and add more data to this thread. ... zpool create library raidz2 /zfs/disk[1-8] -o ashift=12 # PLATTER DISKS zpool add library special mirror /zfs/meta[1-2] -o ashift=13 -f #Mirrored SSDs zpool add library cache /zfs/cache1 -o ashift=13 #NVME zpool add library log /zfs/slog11 -o ashift=13 #NVME And then add the below to put small blocks on the faster SSDs?
Find elsewhere
🌐
Klara Systems
klarasystems.com › home › openzfs – understanding zfs vdev types
OpenZFS - Understanding ZFS vdev Types - Klara Systems
May 9, 2023 - Now that we know the storage vdev topologies, let’s talk about vdev classes. (“Vdev class” and “support vdev” are not official ZFS terminology, but they offer a useful way to categorize and understand how ZFS manages storage!) Currently implemented support vdev types are LOG, CACHE, SPECIAL, and SPARE:
🌐
Techno Tim
technotim.com › posts › special-vdev-truenas
Boost ZFS Performance with a Special VDEV in TrueNAS | Techno Tim
January 7, 2026 - I’ll also share real-world benchmarks comparing pools with and without a special VDEV, so you can see the difference for yourself. ... The test script will try to create a pool based on 3 drives. HDD1, HDD2, and NVME_SPECIAL. You can modify these to match your disk Ids. ... You can also adjust the test files by changing TEST_COUNT however I found that 100,000 is a good number to get consistent results. Update the script with your disk Ids. ... It will create 2 pools, test-1 and test-2, test-2 has the special vdeb.
🌐
Oracle
docs.oracle.com › cd › E19253-01 › 819-5461 › gaynr › index.html
Creating a ZFS Storage Pool
You can install and boot from a ZFS root file system. Review the following root pool configuration information: Disks used for the root pool must have a VTOC (SMI) label, and the pool must be created with disk slices. The root pool must be created as a mirrored configuration or as a single-disk configuration. You cannot add additional disks to create multiple mirrored top-level virtual devices by using the zpool add command, but you can expand a mirrored virtual device by using the zpool attach command.
🌐
Cr0x
cr0x.net › health & recovery › zfs special vdev failure: how to survive the nightmare scenario
ZFS Special VDEV Failure: How to Survive the Nightmare Scenario – cr0x.net
February 3, 2026 - The way out is not clever commands. It’s redundancy, verification, and a refusal to treat tier-0 devices like accessories. Audit: run zpool status and confirm special vdevs are mirrored everywhere. Policy check: inventory special_small_blocks by dataset; decide where it’s justified and where it’s accidental. Monitoring: alert on ZFS checksum errors and NVMe media/data integrity errors, not just “online.”
🌐
Reddit
reddit.com › r/zfs › how do i make a metadata special device vdev?
r/zfs on Reddit: How do I make a metadata special device vdev?
January 31, 2023 -

I have 100 TB raidz1 pool that I am about to create, and I want to store the metadata for it on mirrored SSDs.

How do I create the metadata storage for only the 100TB pool (not the OS)?

zpool create -f -o ashift=12  -m /media storage \
			-o recordsize=1M \
		    -o primarycache=metadata -o secondarycache=none \
               raidz \
                  ata-ST3000DM001-9YN166_HWID \
                  ata-ST3000DM001-9YN166_HWID \
                  ata-ST3000DM001-9YN166_HWID \
                  ata-ST3000DM001-9YN166_HWID
zpool add storage -o ashift=12 special mirror /dev/ssd0n1 /dev/ssd1n1
zfs set special_small_blocks=128K storage 
🌐
Proxmox
forum.proxmox.com › home › forums › proxmox backup server › proxmox backup: installation and configuration
PBS and ZFS Special Allocation Class VDEV ... aka Fusion Drive | Proxmox Support Forum
June 14, 2024 - ===================================================== Add a special vdev. zpool add rpool -f -o ashift=12 special mirror scsi-<>-part3 scsi-<>-part3 scsi-<>-part3 Configure it. zfs set recordsize=1M rpool zfs set special_small_blocks=512K rpool ===================================================== Test results
🌐
Reddit
reddit.com › r/zfs › guidance on how the special vdev performs.
r/zfs on Reddit: Guidance on how the special vdev performs.
January 31, 2022 -

Racking my brain trying to figure out it's actual behavior. No documentation anywhere I can find actually comments on this.

The special vdev is used to store metadata from the pool, so operations like directory listing are at the speed of an NVME drive, which will also improve the performance of spinning rust by reducing the load of small IO required to lookup the pool metadata. This makes sense.

What confuses me is the behavior of the small block allocation class when the special vdev is at capacity. There seems to be a few scenarios that aren't talked about anywhere in the documentation that would be important for performance in various scenarios.

From how i've seen it talked about my understanding is that it acts as a write back cache for small IO based on the special_small_blocks value of the dataset, and when the special vdev is at capacity or needs more space for metadata, small block allocation is offloaded back to the data vdevs.

However i've never actually seen this mentioned anywhere. From the closest thing to a confirmation is in the TrueNas documentation on a fusion pool saying

If the special class becomes full, then allocations spill back into the normal class.

By spill, does that mean, removed from the special class so new incoming small block writes are added to the cache. Or does that mean when the special class is full small IO is sent directly back to the normal class bypassing the special vdev.

Top answer
1 of 2
11
I have answered my own question eventually, partially from some old forum posts and practical testing. Once the special VDEV is full it stays full. The standard small block allocation is 75% of the drive space(default but adjustable), after that further blocks will be sent directly to the backing storage. It can be expanded after the fact, and also striped to another vdev if space becomes constrained, but there is no way to rebalance. Furthermore, the special vdev hits it's allocation limit and later expanded, the small IO will have to be re-written to move it back to it's allocation class. As long as you're using all striped mirrors in your pool with the same ashift(I am), you can "flush" the metadata and small IO back to your main pool by removing the special vdev. I.E zpool remove pool mirror- with x being the mirrored SSD's vdev name This will write all metadata and small blocks back to the main pool. But it also prevents the special vdev from being useful again if re-added without re-writing all your data as new metadata is only added on write.
2 of 2
2
What confuses me is the behavior of the small block allocation class when the special vdev is at capacity. There seems to be a few scenarios that aren't talked about anywhere in the documentation that would be important for performance in various scenarios. When it reaches 75% full, all further small blocks writes go to regular vdevs like normal. Current blocks stay where they are. The remaining space will be reserved for just metadata. Adjust the percentage here: /etc/modprobe.d/zfs.conf by adding zfs_special_class_metadata_reserve_pct=10% for example and rebooting. There might be a way to do it live (only lasts until reboot) I think, but I forget right now. You can search the source code here for "zfs_special_class_metadata_reserve_pct" and find what it touches. Sometimes there are comments you might find helpful. Searching the github issue and pull requests can also be helpful. You're probably thinking that all of this is horribly documented and scattered around like marbles. You're right. As long as you're using all striped mirrors in your pool with the same ashift(I am), you can "flush" the metadata and small IO back to your main pool by removing the special vdev Make absolutely certain you have things backed up and confirmed good (scrubbed) before you try this. This has rarely resulted in problems, mercenary_sysadmin saw corruption I believe when he did some testing when special vdevs first came out. The issue was never resolved and I don't know if he's revisited it. I personally won't trust vdev removal for a long time. Also I do highly recommend a triple mirror as the smallest you consider. Preferably on old enterprise ssds with real PLP (visible capacitors), which are cheap enough to find on ebay. Here's some other references for those curious about special vdevs. Various findings: https://forum.level1techs.com/t/zfs-metadata-special-device-z/159954 Generate a histogram of block sizes Calculate data from ZDB output Clarifies behavior of what goes where when setting small block size: https://github.com/openzfs/zfs/issues/9131#issuecomment-528562601 Small blocks can now be set to anything you can set recordsize to (512B-1M) and even bigger if you enable larger recordsizes (up to 16M): https://github.com/openzfs/zfs/pull/9355
🌐
GitHub
openzfs.github.io › openzfs-docs › man › 7 › zpoolconcepts.7.html
zpoolconcepts.7
You should have been redirected · If not, click here to continue
🌐
GitHub
openzfs.github.io › openzfs-docs › man › v0.8 › 8 › zpool.8.html
zpool.8 — OpenZFS documentation
Cause zpool subcommands to output full vdev path names by default. This behavior is identical to the zpool status -p command line option. ... Older ZFS on Linux implementations had issues when attempting to display pool config VDEV names if a devid NVP value is present in the pool's config.
🌐
Howto-Do
howto-do.it › home › understanding zfs: what is a vdev in zfs?
Understanding ZFS: What is a vdev in ZFS? - Howto-Do.IT
ZFS is available on various operating systems and can be installed from repositories or specific distributions that include ZFS by default. Once installed, you can create a zpool, configure vdevs, create datasets, and assign properties using the ZFS command-line interface (CLI).
Published   July 2, 2024
🌐
FreeBSD
forums.freebsd.org › base system › storage
ZFS - ZFS special device on shared drive | The FreeBSD Forums
September 7, 2022 - With those two slots I have to create mirror vdevs that will host the OS/swap & special device ... Click to expand... What's this "special device" you keep mentioning? Why do you need 7 TB of metadata? Metadata of what exactly? ... SirDice "ZFS special allocation class" (I think).
🌐
Reddit
reddit.com › r/zfs › advice on the special vdev in my zfs setup
r/zfs on Reddit: Advice on the special VDEV in my ZFS setup
March 6, 2023 -

I am planning out my ZFS setup as I'm moving from snapraid. I bought a few sticks of 118gb optane to play around with and am considering using them or some high end SSD's mirrored in a special vdev. I'm considering using some 2tb sn850x's instead of optane to be able to store small blocks on the special vdev. I store mostly video and photos in my server and plan on having a 5x20tb raidz2 and a 3x8tb mirror vdev in my pool. I have 64gb of non ecc ram and my server is on a 1gbit nic. The performance improvement I want to see is faster loading of my folders as it currently takes 10-20 seconds to load the file structure and thumbnails in the worse case. Would a special vdev suit my needs or would arc and l2arc be fine enough for my needs? I would appreciate any advice on my setup.