VDEVPROPS(7)

💖 VDEVPROPS 💖

okay bestie, welcome to the vdevprops page from the Miscellaneous Information Manual — it's literally all about the native and user-defined properties of ZFS vdevs. grab a boba, we're doing this 🧋✨

---

🌸 NAME 🌸

vdevprops — native and user-defined properties of ZFS vdevs 🦋

---

✨ DESCRIPTION ✨

So properties come in two flavors, and no we're not doing a personality quiz, it's just facts: native properties and user-defined (a.k.a. "user") properties. 💅

Native properties either export internal statistics or control ZFS behavior. And on top of that, native properties are either editable or read-only, okay? Pick a lane.

User properties have no effect on ZFS behavior, but bestie you can absolutely use them to annotate vdevs in a way that's meaningful in your environment. Want the deets on those? Scroll to the "User Properties" section below, it's right there. 👇

---

🎀 Native Properties 🎀

Every vdev has a set of properties that export statistics about the vdev as well as control various behaviors. And here's the tea: properties are not inherited from top-level vdevs, with the exception of checksum_n, checksum_t, io_n, io_t, slow_io_events, slow_io_n, and slow_io_t. Those seven are the nepo babies. 👑

The values of numeric properties can be specified using human-readable suffixes (for example, k, KB, M, Gb, and so forth, up to Z for zettabyte). The following are all valid (and equal) specifications: 1536M, 1.5g, 1.50GB. Same energy, different outfit. 💃

The values of non-numeric properties are case sensitive and must be lowercase. no cap. 🔡

---

💫 Read-Only Statistics 💫

The following native properties consist of read-only statistics about the vdev. These properties can not be changed. Look, don't touch. 🙈

• capacity — Percentage of vdev space used
• state — state of this vdev such as online, faulted, or offline
• guid — globally unique id of this vdev
• asize — The allocatable size of this vdev
• psize — The physical size of this vdev
• ashift — The physical sector size of this vdev expressed as the power of two
• size — The total size of this vdev
• free — The amount of remaining free space on this vdev
• allocated — The amount of allocated space on this vdev
• expandsize — How much this vdev can expand by
• fragmentation — Percent of fragmentation in this vdev
• parity — The level of parity for this vdev
• devid — The device id for this vdev
• physpath — The physical path to the device
• encpath — The enclosure path to the device
• fru — Field Replaceable Unit, usually a model number
• parent — Parent of this vdev
• children — Comma separated list of children of this vdev
• numchildren — The number of children belonging to this vdev
• read_errors, write_errors, checksum_errors, initialize_errors, trim_errors — The number of errors of each type encountered by this vdev 😭
• slow_ios — This indicates the number of slow I/O operations encountered by this vdev. A slow I/O is defined as an operation that did not complete within the zio_slow_io_ms threshold in milliseconds (30000 by default). For RAIDZ and DRAID configurations, this value also represents the number of times the vdev was identified as an outlier and excluded from participating in read I/O operations. it's giving "you're on timeout" 💀
• null_ops, read_ops, write_ops, free_ops, claim_ops, trim_ops — The number of I/O operations of each type performed by this vdev
• null_bytes, read_bytes, write_bytes, free_bytes, claim_bytes, trim_bytes — The cumulative size of all operations of each type performed by this vdev
• removing — If this device is currently being removed from the pool
• trim_support — Indicates if a leaf device supports trim operations.

---

🔥 Editable Behavior Properties 🔥

The following native properties can be used to change the behavior of a vdev. main character energy only. 👑

• checksum_n, checksum_t, io_n, io_t, slow_io_n, slow_io_t — Tune the fault management daemon by specifying checksum/io thresholds of <N> errors in <T> seconds, respectively. These properties can be set on leaf and top-level vdevs. When the property is set on the leaf and top-level vdev, the value of the leaf vdev will be used. If the property is only set on the top-level vdev, this value will be used. The value of these properties do not persist across vdev replacement. For this reason, it is advisable to set the property on the top-level vdev — not on the leaf vdev itself. The default values for OpenZFS on Linux are 10 errors in 600 seconds. For OpenZFS on FreeBSD defaults see zfsd(8).

⚠️ bestie pls set these on the top-level vdev, because leaf-level values get dropped on replacement and that's a whole situation. 💀

• slow_io_events — property controls whether slow I/O events are generated. Even when disabled, slow I/Os will be included in the zpool status -s output. so like, it's still watching. always watching. 👀
• comment — A text comment up to 8192 characters long ✍️
• bootsize — The amount of space to reserve for the EFI system partition
• failfast — If this device should propagate BIO errors back to ZFS, used to disable failfast.
• sit_out — Only valid for RAIDZ and DRAID vdevs. True when a slow disk outlier was detected and the vdev is currently in a sit out state. This property can be manually set to cause vdevs to sit out. It will also be automatically set by the autosit logic if that is enabled. While sitting out, the vdev will not participate in normal reads, instead its data will be reconstructed as needed from parity. literally taking a self-care break from reads 🧘
• autosit — Only valid for RAIDZ and DRAID vdevs. If set, this enables the kernel-level slow disk detection logic. This logic automatically causes any vdevs that are significant negative performance outliers to sit out, as described in the sit_out property.
• path — The path to the device for this vdev
• allocating — If this device should perform new allocations, used to disable a device when it is scheduled for later removal. See zpool-remove(8).

---

🦋 User Properties 🦋

In addition to the standard native properties, ZFS supports arbitrary user properties. User properties have no effect on ZFS behavior, but applications or administrators can use them to annotate vdevs. it's a notes app but for your pool. 📝

User property names must contain a colon (":") character to distinguish them from native properties. They may contain lowercase letters, numbers, and the following punctuation characters: colon (":"), dash ("-"), period ("."), and underscore ("_"). The expected convention is that the property name is divided into two portions such as module:property, but this namespace is not enforced by ZFS. User property names can be at most 256 characters, and cannot begin with a dash ("-"). 🚫

When making programmatic use of user properties, it is strongly suggested to use a reversed DNS domain name for the module component of property names to reduce the chance that two independently-developed packages use the same property name for different purposes. don't be the girl who picks a username someone already has, iykyk. 💅

The values of user properties are arbitrary strings and are never validated. Use the zpool set command with a blank value to clear a user property. Property values are limited to 8192 bytes. no vibes checks here, ZFS trusts you fr fr 🫶

---

👑 SEE ALSO 👑

• zpoolprops(7)
• zpool-set(8)

---

and that's the whole page, bestie!! 🎀✨ this was the OpenZFS VDEVPROPS(7) page, dated July 23, 2024 — go forth and annotate your vdevs, you absolute icon 🌈💖🦋