Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZPOOLPROPS(8)		    System Manager's Manual		 ZPOOLPROPS(8)

NAME
       zpoolprops -- available properties for ZFS storage pools

DESCRIPTION
       Each  pool  has several properties associated with it.  Some properties
       are read-only statistics	while others are configurable and  change  the
       behavior	of the pool.

       The following are read-only properties:

       allocated
	       Amount  of storage used within the pool.	 See fragmentation and
	       free for	more information.

       capacity
	       Percentage of pool space	used.  This property can also  be  re-
	       ferred to by its	shortened column name, cap.

       expandsize
	       Amount  of  uninitialized  space	within the pool	or device that
	       can be used to increase the total capacity  of  the  pool.   On
	       whole-disk  vdevs,  this	is the space beyond the	end of the GPT
	       typically occurring when	a LUN is  dynamically  expanded	 or  a
	       disk  replaced  with a larger one.  On partition	vdevs, this is
	       the space appended to the partition after it was	added  to  the
	       pool   most  likely  by resizing	it in-place.  The space	can be
	       claimed for the pool by bringing	it online  with	 autoexpand=on
	       or using	zpool online -e.

       fragmentation
	       The amount of fragmentation in the pool.	As the amount of space
	       allocated  increases,  it becomes more difficult	to locate free
	       space. This may result in lower write performance  compared  to
	       pools with more unfragmented free space.

       free    The  amount  of free space available in the pool.  By contrast,
	       the zfs(8) available property describes how much	new  data  can
	       be written to ZFS filesystems/volumes.  The zpool free property
	       is  not	generally useful for this purpose, and can be substan-
	       tially more than	the zfs	available space. This  discrepancy  is
	       due  to	several	 factors, including raidz parity; zfs reserva-
	       tion, quota, refreservation, and	refquota properties; and space
	       set aside by spa_slop_shift (see	 zfs-module-parameters(5)  for
	       more information).

       freeing
	       After  a	file system or snapshot	is destroyed, the space	it was
	       using is	returned to the	pool asynchronously.  freeing  is  the
	       amount  of  space remaining to be reclaimed.  Over time freeing
	       will decrease while free	increases.

       health  The current health of the pool.	Health can be one  of  ONLINE,
	       DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL.

       guid    A unique	identifier for the pool.

       load_guid
	       A  unique  identifier  for the pool.  Unlike the	guid property,
	       this identifier is generated every time we load the pool	 (e.g.
	       does  not  persist  across  imports/exports)  and never changes
	       while the pool is loaded	(even  if  a  reguid  operation	 takes
	       place).

       size    Total size of the storage pool.

       unsupported@feature_guid
	       Information  about unsupported features that are	enabled	on the
	       pool.  See zpool-features(5) for	details.

       The space usage properties report actual	physical  space	 available  to
       the  storage  pool.  The	physical space can be different	from the total
       amount of space that any	contained  datasets  can  actually  use.   The
       amount of space used in a raidz configuration depends on	the character-
       istics of the data being	written.  In addition, ZFS reserves some space
       for internal accounting that the	zfs(8) command takes into account, but
       the  zpoolprops	command	 does not.  For	non-full pools of a reasonable
       size, these effects should be invisible.	 For  small  pools,  or	 pools
       that are	close to being completely full,	these discrepancies may	become
       more noticeable.

       The following property can be set at creation time and import time:

       altroot
	       Alternate  root directory.  If set, this	directory is prepended
	       to any mount points within the pool.  This can be used when ex-
	       amining an unknown  pool	 where	the  mount  points  cannot  be
	       trusted,	or in an alternate boot	environment, where the typical
	       paths are not valid.  altroot is	not a persistent property.  It
	       is valid	only while the system is up.  Setting altroot defaults
	       to using	cachefile=none,	though this may	be overridden using an
	       explicit	setting.

       The following property can be set only at import	time:

       readonly=on|off
	       If  set	to  on,	 the  pool will	be imported in read-only mode.
	       This property can also be referred to by	its  shortened	column
	       name, rdonly.

       The  following  properties can be set at	creation time and import time,
       and later changed with the zpool	set command:

       ashift=ashift
	       Pool sector size	exponent, to the power of  2  (internally  re-
	       ferred  to  as  ashift  ).  Values from 9 to 16,	inclusive, are
	       valid; also, the	value 0	(the default) means to auto-detect us-
	       ing the kernel's	block layer and	a ZFS internal exception list.
	       I/O operations will be aligned to  the  specified  size	bound-
	       aries.  Additionally, the minimum (disk)	write size will	be set
	       to the specified	size, so this represents a space  vs.  perfor-
	       mance  trade-off. For optimal performance, the pool sector size
	       should be greater than or equal to the sector size of  the  un-
	       derlying	 disks.	 The typical case for setting this property is
	       when performance	is important and the underlying	disks use 4KiB
	       sectors but report 512B sectors to the  OS  (for	 compatibility
	       reasons);  in that case,	set ashift=12 (which is	1<<12 =	4096).
	       When set, this property is used as the default  hint  value  in
	       subsequent  vdev	operations (add, attach	and replace). Changing
	       this value will not modify any existing vdev, not even on  disk
	       replacement; however it can be used, for	instance, to replace a
	       dying  512B sectors disk	with a newer 4KiB sectors device: this
	       will probably result in bad performance but at  the  same  time
	       could prevent loss of data.

       autoexpand=on|off
	       Controls	 automatic  pool  expansion when the underlying	LUN is
	       grown.  If set to on, the pool will be resized according	to the
	       size of the expanded device.  If	the device is part of a	mirror
	       or raidz	then all devices within	that mirror/raidz  group  must
	       be expanded before the new space	is made	available to the pool.
	       The  default  behavior  is  off.	 This property can also	be re-
	       ferred to by its	shortened column name, expand.

       autoreplace=on|off
	       Controls	automatic device replacement.  If set to  off,	device
	       replacement must	be initiated by	the administrator by using the
	       zpool  replace command.	If set to on, any new device, found in
	       the same	physical location as a device that previously belonged
	       to the pool, is automatically formatted and replaced.  The  de-
	       fault  behavior	is off.	 This property can also	be referred to
	       by its shortened	column name, replace.  Autoreplace can also be
	       used with virtual disks (like device mapper) provided that  you
	       use  the	/dev/disk/by-vdev paths	setup by vdev_id.conf. See the
	       vdev_id(8) man page for more details.  Autoreplace and  autoon-
	       line  require  the  ZFS Event Daemon be configured and running.
	       See the zed(8) man page for more	details.

       autotrim=on|off
	       When set	to on space which has been recently freed, and	is  no
	       longer  allocated  by  the  pool, will be periodically trimmed.
	       This allows block device	vdevs which support  BLKDISCARD,  such
	       as SSDs,	or file	vdevs on which the underlying file system sup-
	       ports  hole-punching,  to  reclaim  unused blocks.  The default
	       setting for this	property is off.

	       Automatic TRIM does not	immediately  reclaim  blocks  after  a
	       free.  Instead,	it  will optimistically	delay allowing smaller
	       ranges to be aggregated in to a few  larger  ones.   These  can
	       then  be	issued more efficiently	to the storage.	 TRIM on L2ARC
	       devices is enabled by setting l2arc_trim_ahead >	0.

	       Be aware	that automatic trimming	of recently freed data	blocks
	       can  put	 significant stress on the underlying storage devices.
	       This will vary depending	of how well the	specific  device  han-
	       dles  these commands.  For lower	end devices it is often	possi-
	       ble to achieve most of the benefits of  automatic  trimming  by
	       running an on-demand (manual) TRIM periodically using the zpool
	       trim command.

       bootfs=(unset)|pool/dataset
	       Identifies the default bootable dataset for the root pool. This
	       property	 is  expected to be set	mainly by the installation and
	       upgrade programs.  Not all Linux	 distribution  boot  processes
	       use the bootfs property.

       cachefile=path|none
	       Controls	 the  location	of  where  the	pool  configuration is
	       cached.	Discovering all	pools on  system  startup  requires  a
	       cached  copy  of	 the  configuration data that is stored	on the
	       root file system.  All pools in this  cache  are	 automatically
	       imported	when the system	boots.	Some environments, such	as in-
	       stall  and clustering, need to cache this information in	a dif-
	       ferent location so that pools are not  automatically  imported.
	       Setting	this  property caches the pool configuration in	a dif-
	       ferent location that can	later be imported  with	 zpool	import
	       -c.  Setting it to the value none creates a temporary pool that
	       is never	cached,	and the	"" (empty string) uses the default lo-
	       cation.

	       Multiple	pools can share	the same cache file.  Because the ker-
	       nel  destroys  and recreates this file when pools are added and
	       removed,	care should be taken when attempting  to  access  this
	       file.   When the	last pool using	a cachefile is exported	or de-
	       stroyed,	the file will be empty.

       comment=text
	       A text string consisting	of  printable  ASCII  characters  that
	       will  be	 stored	such that it is	available even if the pool be-
	       comes faulted.  An administrator	can provide additional	infor-
	       mation about a pool using this property.

       dedupditto=number
	       This property is	deprecated and no longer has any effect.

       delegation=on|off
	       Controls	 whether a non-privileged user is granted access based
	       on the dataset permissions defined on the dataset.  See	zfs(8)
	       for more	information on ZFS delegated administration.

       failmode=wait|continue|panic
	       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.

       feature@feature_name=enabled
	       The  value  of  this  property  is   the	  current   state   of
	       feature_name.   The only	valid value when setting this property
	       is enabled which	moves feature_name to the enabled state.   See
	       zpool-features(5) for details on	feature	states.

       listsnapshots=on|off
	       Controls	 whether  information  about snapshots associated with
	       this pool is output when	zfs list is run	without	the -t option.
	       The default value is off.  This property	can also  be  referred
	       to by its shortened name, listsnaps.

       multihost=on|off
	       Controls	whether	a pool activity	check should be	performed dur-
	       ing  zpool  import.   When a pool is determined to be active it
	       cannot be imported, even	with the -f option.  This property  is
	       intended	 to  be	used in	failover configurations	where multiple
	       hosts have access to a pool on shared storage.

	       Multihost provides protection on	import only.  It does not pro-
	       tect against an individual device being used in multiple	pools,
	       regardless of the type of vdev.	See the	discussion under zpool
	       create.

	       When this property is on, periodic writes to storage  occur  to
	       show  the  pool	is  in use.  See zfs_multihost_interval	in the
	       zfs-module-parameters(5)	man page.  In  order  to  enable  this
	       property	 each host must	set a unique hostid.  See genhostid(1)
	       zgenhostid(8) spl-module-parameters(5) for additional  details.
	       The default value is off.

       version=version
	       The  current  on-disk  version  of  the	pool.  This can	be in-
	       creased,	but never decreased.  The preferred method of updating
	       pools is	with the zpool upgrade command,	though	this  property
	       can  be	used  when  a specific version is needed for backwards
	       compatibility.  Once feature flags are enabled on a  pool  this
	       property	will no	longer have a value.

FreeBSD	13.0			August 9, 2019			 ZPOOLPROPS(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=zpoolprops&manpath=FreeBSD+13.0-RELEASE>

home | help