Image of the glider from the Game of Life by John Conway
Skip to content

ZFS Administration, Part VII- Zpool Properties

Table of Contents

Zpool Administration ZFS Administration Appendices
0. Install ZFS on Debian GNU/Linux 9. Copy-on-write A. Visualizing The ZFS Intent Log (ZIL)
1. VDEVs 10. Creating Filesystems B. Using USB Drives
2. RAIDZ 11. Compression and Deduplication C. Why You Should Use ECC RAM
3. The ZFS Intent Log (ZIL) 12. Snapshots and Clones D. The True Cost Of Deduplication
4. The Adjustable Replacement Cache (ARC) 13. Sending and Receiving Filesystems
5. Exporting and Importing Storage Pools 14. ZVOLs
6. Scrub and Resilver 15. iSCSI, NFS and Samba
7. Getting and Setting Properties 16. Getting and Setting Properties
8. Best Practices and Caveats 17. Best Practices and Caveats

Continuing from our last post on scrubbing and resilvering data in zpools, we move on to changing properties in the zpool.


With ext4, and many filesystems in GNU/Linux, we have a way for tuning various flags in the filesystem. Things like setting labels, default mount options, and other tunables. With ZFS, it's no different, and in fact, is far more verbose. These properties allow us to modify all sorts of variables, both for the pool, and for the datasets it contains. Thus, we can "tune" the filesystem to our liking or needs. However, not every property is tunable. Some are read-only. But, we'll define what each of the properties are and how they affect the pool. Note, we are only looking at zpool properties, and we will get to ZFS dataset properties when we reach the dataset subtopic.

Zpool Properties

  • allocated: The amount of data that has been committed into the pool by all of the ZFS datasets. This setting is read-only.
  • altroot: Identifies an alternate root directory. If set, this directory is prepended to any mount points within the pool. This property can be used when examining an unknown pool, if the mount points cannot be trusted, or in an alternate boot environment, where the typical paths are not valid.Setting altroot defaults to using "cachefile=none", though this may be overridden using an explicit setting.
  • ashift: Can only be set at pool creation time. Pool sector size exponent, to the power of 2. I/O operations will be aligned to the specified size boundaries. Default value is "9", as 2^9 = 512, the standard sector size operating system utilities use for reading and writing data. For advanced format drives with 4 KiB boundaries, the value should be set to "ashift=12", as 2^12 = 4096.
  • autoexpand: Must be set before replacing the first drive in your pool. Controls automatic pool expansion when the underlying LUN is grown. Default is "off". After all drives in the pool have been replaced with larger drives, the pool will automatically grow to the new size. This setting is a boolean, with values either "on" or "off".
  • autoreplace: Controls automatic device replacement of a "spare" VDEV in your pool. Default is set to "off". As such, device replacement must be initiated manually by using the "zpool replace" command. This setting is a boolean, with values either "on" or "off".
  • bootfs: Read-only setting that defines the bootable ZFS dataset in the pool. This is typically set by an installation program.
  • cachefile: Controls the location of where the pool configuration is cached. When importing a zpool on a system, ZFS can detect the drive geometry using the metadata on the disks. However, in some clustering environments, the cache file may need to be stored in a different location for pools that would not automatically be imported. Can be set to any string, but for most ZFS installations, the default location of "/etc/zfs/zpool.cache" should be sufficient.
  • capacity: Read-only value that identifies the percentage of pool space used.
  • comment: A text string consisting of no more than 32 printable ASCII characters that will be stored such that it is available even if the pool becomes faulted. An administrator can provide additional information about a pool using this setting.
  • dedupditto: Sets a block deduplication threshold, and if the reference count for a deduplicated block goes above the threshold, a duplicate copy of the block is stored automatically. The default value is 0. Can be any positive number.
  • dedupratio: Read-only deduplication ratio specified for a pool, expressed as a multiplier
  • delegation: Controls whether a non-privileged user can be granted access permissions that are defined for the dataset. The setting is a boolean, defaults to "on" and can be "on" or "off".
  • expandsize: Amount of uninitialized space within the pool or device that can be used to increase the total capacity of the pool. Uninitialized space consists of any space on an EFI labeled vdev which has not been brought online (i.e. "zpool online -e"). This space occurs when a LUN is dynamically expanded.
  • failmode: Controls the system behavior in the event of catastrophic pool failure. This condition is typically a result of a loss of connectivity to the underlying storage device(s) or a failure of all devices within the pool. The behavior of such an event is determined as follows:
    • wait: Blocks all I/O access until the device connectivity is recovered and the errors are cleared. This is the default behavior.
    • continue: Returns EIO to any new write I/O requests but allows reads to any of the remaining healthy devices. Any write requests that have yet to be committed to disk would be blocked.
    • panic: Prints out a message to the console and generates a system crash dump.
  • free: Read-only value that identifies the number of blocks within the pool that are not allocated.
  • guid: Read-only property that identifies the unique identifier for the pool. Similar to the UUID string for ext4 filesystems.
  • health: Read-only property that identifies the current health of the pool, as either ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, or UNAVAIL.
  • listsnapshots: Controls whether snapshot information that is associated with this pool is displayed with the "zfs list" command. If this property is disabled, snapshot information can be displayed with the "zfs list -t snapshot" command. The default value is "off". Boolean value that can be either "off" or "on".
  • readonly: Boolean value that can be either "off" or "on". Default value is "off". Controls setting the pool into read-only mode to prevent writes and/or data corruption.
  • size: Read-only property that identifies the total size of the storage pool.
  • version: Writable setting that identifies the current on-disk version of the pool. Can be any value from 1 to the output of the "zpool upgrade -v" command. This property can be used when a specific version is needed for backwards compatibility.

Getting and Setting Properties

There are a few ways you can get to the properties of your pool- you can get all properties at once, only one property, or more than one, comma-separated. For example, suppose I wanted to get just the health of the pool. I could issue the following command:

# zpool get health tank
tank  health    ONLINE  -

If I wanted to get multiple settings, say the health of the system, how much is free, and how much is allocated, I could issue this command instead:

# zpool get health,free,allocated tank
tank  health     ONLINE  -
tank  free       176G    -
tank  allocated  32.2G   -

And of course, if I wanted to get all the settings available, I could run:

# zpool get all tank
tank  size           208G        -
tank  capacity       15%         -
tank  altroot        -           default
tank  health         ONLINE      -
tank  guid           1695112377970346970  default
tank  version        28          default
tank  bootfs         -           default
tank  delegation     on          default
tank  autoreplace    off         default
tank  cachefile      -           default
tank  failmode       wait        default
tank  listsnapshots  off         default
tank  autoexpand     off         default
tank  dedupditto     0           default
tank  dedupratio     1.00x       -
tank  free           176G        -
tank  allocated      32.2G       -
tank  readonly       off         -
tank  ashift         0           default
tank  comment        -           default
tank  expandsize     0           -

Setting a property is just as easy. However, there is a catch. For properties that require a string argument, there is no way to get it back to default. At least not that I am aware of. With the rest of the properties, if you try to set a property to an invalid argument, an error will print to the screen letting you know what is available, but it will not notify you as to what is default. However, you can look at the 'SOURCE' column. If the value in that column is "default", then it's default. If it's "local", then it was user-defined.

Suppose I wanted to change the "comment" property, this is how I would do it:

# zpool set comment="Contact" tank
# zpool get comment tank
NAME  PROPERTY  VALUE                       SOURCE
tank  comment   Contact  local

As you can see, the SOURCE is "local" for the "comment" property. Thus, it was user-defined. As mentioned, I don't know of a way to get string properties back to default after being set. Further, any modifiable property can be set at pool creation time by using the "-o" switch, as follows:

# zpool create -o ashift=12 tank raid1 sda sdb

Final Thoughts

The zpool properties apply to the entire pool, which means ZFS datasets will inherit that property from the pool. Some properties that you set on your ZFS dataset, which will be discussed towards the end of this series, apply to the whole pool. For example, if you enable block deduplication for a ZFS dataset, it dedupes blocks found in the entire pool, not just in your dataset. However, only blocks in that dataset will be actively deduped, while other ZFS datasets may not. Also, setting a property is not retroactive. In the case of your "autoexpand" zpool property to automatically expand the zpool size when all the drives have been replaced, if you replaced a drive before enabling the property, that drive will be considered a smaller drive, even if it physically isn't. Setting properties only applies to operations on the data moving forward, and never backward.

Despite a few of these caveats, having the ability to change some parameters of your pool to fit your needs as a GNU/Linux storage administrator gives you great control that other filesystems don't. And, as we've discovered thus far, everything can be handled with a single command "zpool", and easy-to-recall subcommands. We'll have one more post discussing a thorough examination of caveats that you will want to consider before creating your pools, then we will leave the zpool category, and work our way towards ZFS datasets, the bread and butter of ZFS as a whole. If there is anything additional about zpools you would like me to post on, let me know now, and I can squeeze it in.

{ 5 } Comments

  1. Dominik Honnef using Google Chrome 24.0.1312.14 on GNU/Linux 64 bits | January 4, 2013 at 11:34 am | Permalink

    > I don’t know of a way to get string properties back to default after being set

    Indirectly, `zfs inherit`should be doing that, if you consider the inherited value the default. And if no parent specified it, it will truly be the default value.

  2. Dominik Honnef using Google Chrome 24.0.1312.14 on GNU/Linux 64 bits | January 4, 2013 at 11:38 am | Permalink

    Disregard previous comment, obviously zfs != zpool…

  3. Derek Scherger using Google Chrome 34.0.1847.116 on Mac OS | April 13, 2014 at 5:48 pm | Permalink

    I think you can set a string property back to its default with something like this:

    zpool set bootfs= rpool

    This worked for me at least.

  4. m.ardito using Firefox 31.0 on Windows 7 | April 10, 2015 at 7:48 am | Permalink

    Hi, I'm learning zfs through your wonderful pages, thanks for sharing this!
    I have a doubt:

    about ashift, you wrote "Default value is "9", as 2^9 = 512,"

    but then when you use "#zpool get all tank" you get, amongst other settings,
    "tank ashift 0 default"

    and this is apparently in contrast to "However, you can look at the 'SOURCE' column. If the value in that column is "default", then it's default. If it's "local", then it was user-defined."

    am I missing something?

  5. Darael using Google Chrome 40.0.2214.91 on GNU/Linux 64 bits | April 17, 2015 at 3:47 pm | Permalink

    m.ardito - 0 is the default value, but what 0 means is "use the size the disk reports", and since a lot of AF disks report 512b sectors for compatibility with old OSes, 0 functionally means 9, even though this is suboptimal. To say the default is 9 is a simplification, but close enough.

{ 6 } Trackbacks

  1. [...] Getting and Setting Properties [...]

  2. [...] Getting and Setting Properties [...]

  3. [...] Getting and Setting Properties [...]

  4. [...] Getting and Setting Properties [...]

  5. [...] Getting and Setting Properties [...]

  6. [...] Getting and Setting Properties [...]

Post a Comment

Your email is never published nor shared.