man/man8/zpoolprops.8

   1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or http://www.opensolaris.org/os/licensing.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\"
  22 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  23 .\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
  24 .\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
  25 .\" Copyright (c) 2017 Datto Inc.
  26 .\" Copyright (c) 2018 George Melikov. All Rights Reserved.
  27 .\" Copyright 2017 Nexenta Systems, Inc.
  28 .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
  29 .\"
  30 .Dd August 9, 2019
  31 .Dt ZPOOLPROPS 8
  32 .Os
  33 .Sh NAME
  34 .Nm zpoolprops
  35 .Nd available properties for ZFS storage pools
  36 .Sh DESCRIPTION
  37 Each pool has several properties associated with it.
  38 Some properties are read-only statistics while others are configurable and
  39 change the behavior of the pool.
  40 .Pp
  41 The following are read-only properties:
  42 .Bl -tag -width Ds
  43 .It Cm allocated
  44 Amount of storage used within the pool.
  45 See
  46 .Sy fragmentation
  47 and
  48 .Sy free
  49 for more information.
  50 .It Sy capacity
  51 Percentage of pool space used.
  52 This property can also be referred to by its shortened column name,
  53 .Sy cap .
  54 .It Sy expandsize
  55 Amount of uninitialized space within the pool or device that can be used to
  56 increase the total capacity of the pool.
  57 Uninitialized space consists of any space on an EFI labeled vdev which has not
  58 been brought online
  59 .Po e.g, using
  60 .Nm zpool Cm online Fl e
  61 .Pc .
  62 This space occurs when a LUN is dynamically expanded.
  63 .It Sy fragmentation
  64 The amount of fragmentation in the pool. As the amount of space
  65 .Sy allocated
  66 increases, it becomes more difficult to locate
  67 .Sy free
  68 space. This may result in lower write performance compared to pools with more
  69 unfragmented free space.
  70 .It Sy free
  71 The amount of free space available in the pool.
  72 By contrast, the
  73 .Xr zfs 8
  74 .Sy available
  75 property describes how much new data can be written to ZFS filesystems/volumes.
  76 The zpool
  77 .Sy free
  78 property is not generally useful for this purpose, and can be substantially more than the zfs
  79 .Sy available
  80 space. This discrepancy is due to several factors, including raidz parity; zfs
  81 reservation, quota, refreservation, and refquota properties; and space set aside by
  82 .Sy spa_slop_shift
  83 (see
  84 .Xr zfs-module-parameters 5
  85 for more information).
  86 .It Sy freeing
  87 After a file system or snapshot is destroyed, the space it was using is
  88 returned to the pool asynchronously.
  89 .Sy freeing
  90 is the amount of space remaining to be reclaimed.
  91 Over time
  92 .Sy freeing
  93 will decrease while
  94 .Sy free
  95 increases.
  96 .It Sy health
  97 The current health of the pool.
  98 Health can be one of
  99 .Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL .
 100 .It Sy guid
 101 A unique identifier for the pool.
 102 .It Sy load_guid
 103 A unique identifier for the pool.
 104 Unlike the
 105 .Sy guid
 106 property, this identifier is generated every time we load the pool (e.g. does
 107 not persist across imports/exports) and never changes while the pool is loaded
 108 (even if a
 109 .Sy reguid
 110 operation takes place).
 111 .It Sy size
 112 Total size of the storage pool.
 113 .It Sy unsupported@ Ns Em feature_guid
 114 Information about unsupported features that are enabled on the pool.
 115 See
 116 .Xr zpool-features 5
 117 for details.
 118 .El
 119 .Pp
 120 The space usage properties report actual physical space available to the
 121 storage pool.
 122 The physical space can be different from the total amount of space that any
 123 contained datasets can actually use.
 124 The amount of space used in a raidz configuration depends on the characteristics
 125 of the data being written.
 126 In addition, ZFS reserves some space for internal accounting that the
 127 .Xr zfs 8
 128 command takes into account, but the
 129 .Nm
 130 command does not.
 131 For non-full pools of a reasonable size, these effects should be invisible.
 132 For small pools, or pools that are close to being completely full, these
 133 discrepancies may become more noticeable.
 134 .Pp
 135 The following property can be set at creation time and import time:
 136 .Bl -tag -width Ds
 137 .It Sy altroot
 138 Alternate root directory.
 139 If set, this directory is prepended to any mount points within the pool.
 140 This can be used when examining an unknown pool where the mount points cannot be
 141 trusted, or in an alternate boot environment, where the typical paths are not
 142 valid.
 143 .Sy altroot
 144 is not a persistent property.
 145 It is valid only while the system is up.
 146 Setting
 147 .Sy altroot
 148 defaults to using
 149 .Sy cachefile Ns = Ns Sy none ,
 150 though this may be overridden using an explicit setting.
 151 .El
 152 .Pp
 153 The following property can be set only at import time:
 154 .Bl -tag -width Ds
 155 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
 156 If set to
 157 .Sy on ,
 158 the pool will be imported in read-only mode.
 159 This property can also be referred to by its shortened column name,
 160 .Sy rdonly .
 161 .El
 162 .Pp
 163 The following properties can be set at creation time and import time, and later
 164 changed with the
 165 .Nm zpool Cm set
 166 command:
 167 .Bl -tag -width Ds
 168 .It Sy ashift Ns = Ns Sy ashift
 169 Pool sector size exponent, to the power of
 170 .Sy 2
 171 (internally referred to as
 172 .Sy ashift
 173 ). Values from 9 to 16, inclusive, are valid; also, the
 174 value 0 (the default) means to auto-detect using the kernel's block
 175 layer and a ZFS internal exception list. I/O operations will be aligned
 176 to the specified size boundaries. Additionally, the minimum (disk)
 177 write size will be set to the specified size, so this represents a
 178 space vs. performance trade-off. For optimal performance, the pool
 179 sector size should be greater than or equal to the sector size of the
 180 underlying disks. The typical case for setting this property is when
 181 performance is important and the underlying disks use 4KiB sectors but
 182 report 512B sectors to the OS (for compatibility reasons); in that
 183 case, set
 184 .Sy ashift=12
 185 (which is 1<<12 = 4096). When set, this property is
 186 used as the default hint value in subsequent vdev operations (add,
 187 attach and replace). Changing this value will not modify any existing
 188 vdev, not even on disk replacement; however it can be used, for
 189 instance, to replace a dying 512B sectors disk with a newer 4KiB
 190 sectors device: this will probably result in bad performance but at the
 191 same time could prevent loss of data.
 192 .It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off
 193 Controls automatic pool expansion when the underlying LUN is grown.
 194 If set to
 195 .Sy on ,
 196 the pool will be resized according to the size of the expanded device.
 197 If the device is part of a mirror or raidz then all devices within that
 198 mirror/raidz group must be expanded before the new space is made available to
 199 the pool.
 200 The default behavior is
 201 .Sy off .
 202 This property can also be referred to by its shortened column name,
 203 .Sy expand .
 204 .It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off
 205 Controls automatic device replacement.
 206 If set to
 207 .Sy off ,
 208 device replacement must be initiated by the administrator by using the
 209 .Nm zpool Cm replace
 210 command.
 211 If set to
 212 .Sy on ,
 213 any new device, found in the same physical location as a device that previously
 214 belonged to the pool, is automatically formatted and replaced.
 215 The default behavior is
 216 .Sy off .
 217 This property can also be referred to by its shortened column name,
 218 .Sy replace .
 219 Autoreplace can also be used with virtual disks (like device
 220 mapper) provided that you use the /dev/disk/by-vdev paths setup by
 221 vdev_id.conf. See the
 222 .Xr vdev_id 8
 223 man page for more details.
 224 Autoreplace and autoonline require the ZFS Event Daemon be configured and
 225 running.  See the
 226 .Xr zed 8
 227 man page for more details.
 228 .It Sy autotrim Ns = Ns Sy on Ns | Ns Sy off
 229 When set to
 230 .Sy on
 231 space which has been recently freed, and is no longer allocated by the pool,
 232 will be periodically trimmed.  This allows block device vdevs which support
 233 BLKDISCARD, such as SSDs, or file vdevs on which the underlying file system
 234 supports hole-punching, to reclaim unused blocks.  The default setting for
 235 this property is
 236 .Sy off .
 237 .Pp
 238 Automatic TRIM does not immediately reclaim blocks after a free. Instead,
 239 it will optimistically delay allowing smaller ranges to be aggregated in to
 240 a few larger ones.  These can then be issued more efficiently to the storage.
 241 TRIM on L2ARC devices is enabled by setting
 242 .Sy l2arc_trim_ahead > 0 .
 243 .Pp
 244 Be aware that automatic trimming of recently freed data blocks can put
 245 significant stress on the underlying storage devices.  This will vary
 246 depending of how well the specific device handles these commands.  For
 247 lower end devices it is often possible to achieve most of the benefits
 248 of automatic trimming by running an on-demand (manual) TRIM periodically
 249 using the
 250 .Nm zpool Cm trim
 251 command.
 252 .It Sy bootfs Ns = Ns Sy (unset) Ns | Ns Ar pool Ns / Ns Ar dataset
 253 Identifies the default bootable dataset for the root pool. This property is
 254 expected to be set mainly by the installation and upgrade programs.
 255 Not all Linux distribution boot processes use the bootfs property.
 256 .It Sy cachefile Ns = Ns Ar path Ns | Ns Sy none
 257 Controls the location of where the pool configuration is cached.
 258 Discovering all pools on system startup requires a cached copy of the
 259 configuration data that is stored on the root file system.
 260 All pools in this cache are automatically imported when the system boots.
 261 Some environments, such as install and clustering, need to cache this
 262 information in a different location so that pools are not automatically
 263 imported.
 264 Setting this property caches the pool configuration in a different location that
 265 can later be imported with
 266 .Nm zpool Cm import Fl c .
 267 Setting it to the value
 268 .Sy none
 269 creates a temporary pool that is never cached, and the
 270 .Qq
 271 .Pq empty string
 272 uses the default location.
 273 .Pp
 274 Multiple pools can share the same cache file.
 275 Because the kernel destroys and recreates this file when pools are added and
 276 removed, care should be taken when attempting to access this file.
 277 When the last pool using a
 278 .Sy cachefile
 279 is exported or destroyed, the file will be empty.
 280 .It Sy comment Ns = Ns Ar text
 281 A text string consisting of printable ASCII characters that will be stored
 282 such that it is available even if the pool becomes faulted.
 283 An administrator can provide additional information about a pool using this
 284 property.
 285 .It Sy dedupditto Ns = Ns Ar number
 286 This property is deprecated and no longer has any effect.
 287 .It Sy delegation Ns = Ns Sy on Ns | Ns Sy off
 288 Controls whether a non-privileged user is granted access based on the dataset
 289 permissions defined on the dataset.
 290 See
 291 .Xr zfs 8
 292 for more information on ZFS delegated administration.
 293 .It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy panic
 294 Controls the system behavior in the event of catastrophic pool failure.
 295 This condition is typically a result of a loss of connectivity to the underlying
 296 storage device(s) or a failure of all devices within the pool.
 297 The behavior of such an event is determined as follows:
 298 .Bl -tag -width "continue"
 299 .It Sy wait
 300 Blocks all I/O access until the device connectivity is recovered and the errors
 301 are cleared.
 302 This is the default behavior.
 303 .It Sy continue
 304 Returns
 305 .Er EIO
 306 to any new write I/O requests but allows reads to any of the remaining healthy
 307 devices.
 308 Any write requests that have yet to be committed to disk would be blocked.
 309 .It Sy panic
 310 Prints out a message to the console and generates a system crash dump.
 311 .El
 312 .It Sy feature@ Ns Ar feature_name Ns = Ns Sy enabled
 313 The value of this property is the current state of
 314 .Ar feature_name .
 315 The only valid value when setting this property is
 316 .Sy enabled
 317 which moves
 318 .Ar feature_name
 319 to the enabled state.
 320 See
 321 .Xr zpool-features 5
 322 for details on feature states.
 323 .It Sy listsnapshots Ns = Ns Sy on Ns | Ns Sy off
 324 Controls whether information about snapshots associated with this pool is
 325 output when
 326 .Nm zfs Cm list
 327 is run without the
 328 .Fl t
 329 option.
 330 The default value is
 331 .Sy off .
 332 This property can also be referred to by its shortened name,
 333 .Sy listsnaps .
 334 .It Sy multihost Ns = Ns Sy on Ns | Ns Sy off
 335 Controls whether a pool activity check should be performed during
 336 .Nm zpool Cm import .
 337 When a pool is determined to be active it cannot be imported, even with the
 338 .Fl f
 339 option.  This property is intended to be used in failover configurations
 340 where multiple hosts have access to a pool on shared storage.
 341 .Pp
 342 Multihost provides protection on import only.  It does not protect against an
 343 individual device being used in multiple pools, regardless of the type of vdev.
 344 See the discussion under
 345 .Sy zpool create.
 346 .Pp
 347 When this property is on, periodic writes to storage occur to show the pool is
 348 in use.  See
 349 .Sy zfs_multihost_interval
 350 in the
 351 .Xr zfs-module-parameters 5
 352 man page.  In order to enable this property each host must set a unique hostid.
 353 See
 354 .Xr genhostid 1
 355 .Xr zgenhostid 8
 356 .Xr spl-module-parameters 5
 357 for additional details.  The default value is
 358 .Sy off .
 359 .It Sy version Ns = Ns Ar version
 360 The current on-disk version of the pool.
 361 This can be increased, but never decreased.
 362 The preferred method of updating pools is with the
 363 .Nm zpool Cm upgrade
 364 command, though this property can be used when a specific version is needed for
 365 backwards compatibility.
 366 Once feature flags are enabled on a pool this property will no longer have a
 367 value.
 368 .El