diff options
Diffstat (limited to 'man/man8')
38 files changed, 494 insertions, 3285 deletions
diff --git a/man/man8/mount.zfs.8 b/man/man8/mount.zfs.8 index 5d36dbdb1..2101f70cd 100644 --- a/man/man8/mount.zfs.8 +++ b/man/man8/mount.zfs.8 @@ -56,7 +56,7 @@ in most cases. are handled according to the .Em Temporary Mount Point Properties section in -.Xr zfsprops 8 , +.Xr zfsprops 7 , except for those described below. .Pp If diff --git a/man/man8/zed.8.in b/man/man8/zed.8.in index e0d9f0404..b0b26bfcf 100644 --- a/man/man8/zed.8.in +++ b/man/man8/zed.8.in @@ -237,7 +237,6 @@ Terminate the daemon. .El . .Sh SEE ALSO -.Xr zfs-events 5 , .Xr zfs 8 , .Xr zpool 8 , .Xr zpool-events 8 diff --git a/man/man8/zfs-bookmark.8 b/man/man8/zfs-bookmark.8 index d8833c3fb..094a7b309 100644 --- a/man/man8/zfs-bookmark.8 +++ b/man/man8/zfs-bookmark.8 @@ -56,7 +56,7 @@ a redaction bookmark. .Pp This feature must be enabled to be used. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on ZFS feature flags and the .Sy bookmarks feature. diff --git a/man/man8/zfs-clone.8 b/man/man8/zfs-clone.8 index 24784ecb9..0640244f2 100644 --- a/man/man8/zfs-clone.8 +++ b/man/man8/zfs-clone.8 @@ -47,7 +47,7 @@ See the .Sx Clones section of -.Xr zfsconcepts 8 +.Xr zfsconcepts 7 for details. The target dataset can be located anywhere in the ZFS hierarchy, and is created as the same type as the original. diff --git a/man/man8/zfs-create.8 b/man/man8/zfs-create.8 index 100a6deed..55397fa66 100644 --- a/man/man8/zfs-create.8 +++ b/man/man8/zfs-create.8 @@ -184,7 +184,7 @@ See in the .Em Native Properties section of -.Xr zfsprops 8 +.Xr zfsprops 7 for more information about sparse volumes. .It Fl n Do a dry-run diff --git a/man/man8/zfs-jail.8 b/man/man8/zfs-jail.8 index d4a04073e..4f9faaea9 100644 --- a/man/man8/zfs-jail.8 +++ b/man/man8/zfs-jail.8 @@ -119,5 +119,5 @@ or name .Ar jailname . .El .Sh SEE ALSO -.Xr jail 8 , -.Xr zfsprops 8 +.Xr zfsprops 7 , +.Xr jail 8 diff --git a/man/man8/zfs-list.8 b/man/man8/zfs-list.8 index 0313b3a14..520048386 100644 --- a/man/man8/zfs-list.8 +++ b/man/man8/zfs-list.8 @@ -90,7 +90,7 @@ The property must be: One of the properties described in the .Sx Native Properties section of -.Xr zfsprops 8 +.Xr zfsprops 7 .It A user property .It @@ -118,7 +118,7 @@ value of the property. The property must be one of the properties described in the .Sx Properties section of -.Xr zfsprops 8 +.Xr zfsprops 7 or the value .Sy name to sort by the dataset name. @@ -158,5 +158,5 @@ displays only snapshots. .El . .Sh SEE ALSO -.Xr zfs-get 8 , -.Xr zfsprops 8 +.Xr zfsprops 7 , +.Xr zfs-get 8 diff --git a/man/man8/zfs-load-key.8 b/man/man8/zfs-load-key.8 index f29d3df82..ed89b65d7 100644 --- a/man/man8/zfs-load-key.8 +++ b/man/man8/zfs-load-key.8 @@ -296,6 +296,6 @@ Deduplication with encryption will leak information about which blocks are equivalent in a dataset and will incur an extra CPU cost for each block written. . .Sh SEE ALSO +.Xr zfsprops 7 , .Xr zfs-create 8 , -.Xr zfs-set 8 , -.Xr zfsprops 8 +.Xr zfs-set 8 diff --git a/man/man8/zfs-mount-generator.8.in b/man/man8/zfs-mount-generator.8.in index e4117101b..7aa332ba8 100644 --- a/man/man8/zfs-mount-generator.8.in +++ b/man/man8/zfs-mount-generator.8.in @@ -186,7 +186,7 @@ to re-run all generators: .Xr systemd.mount 5 , .Xr systemd.target 5 , .Xr zfs 5 , -.Xr zfs-events 5 , .Xr systemd.generator 7 , .Xr systemd.special 7 , -.Xr zed 8 +.Xr zed 8 , +.Xr zpool-events 8 diff --git a/man/man8/zfs-mount.8 b/man/man8/zfs-mount.8 index 62275242c..42ce6b5ca 100644 --- a/man/man8/zfs-mount.8 +++ b/man/man8/zfs-mount.8 @@ -91,7 +91,7 @@ duration of the mount. See the .Em Temporary Mount Point Properties section of -.Xr zfsprops 8 +.Xr zfsprops 7 for details. .It Fl l Load keys for encrypted filesystems as they are being mounted. diff --git a/man/man8/zfs-receive.8 b/man/man8/zfs-receive.8 index ceb6e64ce..d2cec42a8 100644 --- a/man/man8/zfs-receive.8 +++ b/man/man8/zfs-receive.8 @@ -357,7 +357,7 @@ To use this flag, the storage pool must have the .Sy extensible_dataset feature enabled. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on ZFS feature flags. .It Fl u File system that is associated with the received stream is not mounted. diff --git a/man/man8/zfs-send.8 b/man/man8/zfs-send.8 index 47b6c47ad..a3d08fbf6 100644 --- a/man/man8/zfs-send.8 +++ b/man/man8/zfs-send.8 @@ -110,7 +110,7 @@ The receiving system must have the .Sy large_blocks pool feature enabled as well. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on ZFS feature flags and the .Sy large_blocks feature. @@ -161,7 +161,7 @@ received as an encrypted dataset, since encrypted datasets cannot use the .Sy embedded_data feature. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on ZFS feature flags and the .Sy embedded_data feature. @@ -308,7 +308,7 @@ The receiving system must have the .Sy large_blocks pool feature enabled as well. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on ZFS feature flags and the .Sy large_blocks feature. @@ -372,7 +372,7 @@ since encrypted datasets cannot use the .Sy embedded_data feature. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on ZFS feature flags and the .Sy embedded_data feature. diff --git a/man/man8/zfs-set.8 b/man/man8/zfs-set.8 index 83709fa61..a3588cc26 100644 --- a/man/man8/zfs-set.8 +++ b/man/man8/zfs-set.8 @@ -65,7 +65,7 @@ .Xc Only some properties can be edited. See -.Xr zfsprops 8 +.Xr zfsprops 7 for more information on what properties can be set and acceptable values. Numeric values can be specified as exact values, or in a human-readable form @@ -78,7 +78,7 @@ User properties can be set on snapshots. For more information, see the .Em User Properties section of -.Xr zfsprops 8 . +.Xr zfsprops 7 . .It Xo .Nm zfs .Cm get @@ -114,7 +114,7 @@ This command takes a comma-separated list of properties as described in the and .Sx User Properties sections of -.Xr zfsprops 8 . +.Xr zfsprops 7 . .Pp The value .Sy all @@ -163,7 +163,7 @@ restored to default if no ancestor has the property set, or with the .Fl S option reverted to the received value if one exists. See -.Xr zfsprops 8 +.Xr zfsprops 7 for a listing of default values, and details on which properties can be inherited. .Bl -tag -width "-r" @@ -178,5 +178,5 @@ option was not specified. .El . .Sh SEE ALSO -.Xr zfs-list 8 , -.Xr zfsprops 8 +.Xr zfsprops 7 , +.Xr zfs-list 8 diff --git a/man/man8/zfs-share.8 b/man/man8/zfs-share.8 index 369f667c9..e30d53881 100644 --- a/man/man8/zfs-share.8 +++ b/man/man8/zfs-share.8 @@ -87,4 +87,4 @@ The command can also be given a path to a ZFS file system shared on the system. .Sh SEE ALSO .Xr exports 5 , .Xr smb.conf 5 , -.Xr zfsprops 8 +.Xr zfsprops 7 diff --git a/man/man8/zfs-snapshot.8 b/man/man8/zfs-snapshot.8 index fdff39fbc..225123f44 100644 --- a/man/man8/zfs-snapshot.8 +++ b/man/man8/zfs-snapshot.8 @@ -54,7 +54,7 @@ can be used as an alias for See the .Sx Snapshots section of -.Xr zfsconcepts 8 +.Xr zfsconcepts 7 for details. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value diff --git a/man/man8/zfs-upgrade.8 b/man/man8/zfs-upgrade.8 index 0ba276dc6..f3620faa6 100644 --- a/man/man8/zfs-upgrade.8 +++ b/man/man8/zfs-upgrade.8 @@ -77,7 +77,7 @@ systems running older versions of ZFS. .Pp In general, the file system version is independent of the pool version. See -.Xr zpool-features 5 +.Xr zpool-features 7 for information on features of ZFS storage pools. .Pp In some cases, the file system version and the pool version are interrelated and diff --git a/man/man8/zfs-userspace.8 b/man/man8/zfs-userspace.8 index d09e35e1f..b7bd61b57 100644 --- a/man/man8/zfs-userspace.8 +++ b/man/man8/zfs-userspace.8 @@ -183,5 +183,5 @@ for types. .El . .Sh SEE ALSO -.Xr zfs-set 8 , -.Xr zfsprops 8 +.Xr zfsprops 7 , +.Xr zfs-set 8 diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index 16c874eb2..fca1ba00d 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -96,7 +96,7 @@ or .El .Pp See -.Xr zfsconcepts 8 +.Xr zfsconcepts 7 for details. . .Ss Properties @@ -108,7 +108,7 @@ In addition, native properties are either editable or read-only. User properties have no effect on ZFS behavior, but you can use them to annotate datasets in a way that is meaningful in your environment. For more information about properties, see -.Xr zfsprops 8 . +.Xr zfsprops 7 . . .Ss Encryption Enabling the @@ -354,7 +354,7 @@ Snapshots are displayed if The default is .Sy off . See -.Xr zpoolprops 8 +.Xr zpoolprops 7 for more information on pool properties. .Bd -literal -compact -offset Ds .No # Nm zfs Cm list @@ -728,6 +728,8 @@ This option is provided for backwards compatibility with older ZFS versions. .Xr acl 5 , .Xr attributes 5 , .Xr exports 5 , +.Xr zfsconcepts 7 , +.Xr zfsprops 7 , .Xr exportfs 8 , .Xr mount 8 , .Xr net 8 , @@ -768,6 +770,4 @@ This option is provided for backwards compatibility with older ZFS versions. .Xr zfs-upgrade 8 , .Xr zfs-userspace 8 , .Xr zfs-wait 8 , -.Xr zfsconcepts 8 , -.Xr zfsprops 8 , .Xr zpool 8 diff --git a/man/man8/zfsconcepts.8 b/man/man8/zfsconcepts.8 deleted file mode 100644 index 3403d53bf..000000000 --- a/man/man8/zfsconcepts.8 +++ /dev/null @@ -1,206 +0,0 @@ -.\" -.\" CDDL HEADER START -.\" -.\" The contents of this file are subject to the terms of the -.\" Common Development and Distribution License (the "License"). -.\" You may not use this file except in compliance with the License. -.\" -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE -.\" or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions -.\" and limitations under the License. -.\" -.\" When distributing Covered Code, include this CDDL HEADER in each -.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. -.\" If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] -.\" -.\" CDDL HEADER END -.\" -.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright 2011 Joshua M. Clulow <[email protected]> -.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. -.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. -.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. -.\" Copyright (c) 2014 by Adam Stevko. All rights reserved. -.\" Copyright (c) 2014 Integros [integros.com] -.\" Copyright 2019 Richard Laager. All rights reserved. -.\" Copyright 2018 Nexenta Systems, Inc. -.\" Copyright 2019 Joyent, Inc. -.\" -.Dd June 30, 2019 -.Dt ZFSCONCEPTS 8 -.Os -. -.Sh NAME -.Nm zfsconcepts -.Nd overview of ZFS concepts -. -.Sh DESCRIPTION -.Ss ZFS File System Hierarchy -A ZFS storage pool is a logical collection of devices that provide space for -datasets. -A storage pool is also the root of the ZFS file system hierarchy. -.Pp -The root of the pool can be accessed as a file system, such as mounting and -unmounting, taking snapshots, and setting properties. -The physical storage characteristics, however, are managed by the -.Xr zpool 8 -command. -.Pp -See -.Xr zpool 8 -for more information on creating and administering pools. -.Ss Snapshots -A snapshot is a read-only copy of a file system or volume. -Snapshots can be created extremely quickly, and initially consume no additional -space within the pool. -As data within the active dataset changes, the snapshot consumes more data than -would otherwise be shared with the active dataset. -.Pp -Snapshots can have arbitrary names. -Snapshots of volumes can be cloned or rolled back, visibility is determined -by the -.Sy snapdev -property of the parent volume. -.Pp -File system snapshots can be accessed under the -.Pa .zfs/snapshot -directory in the root of the file system. -Snapshots are automatically mounted on demand and may be unmounted at regular -intervals. -The visibility of the -.Pa .zfs -directory can be controlled by the -.Sy snapdir -property. -.Ss Bookmarks -A bookmark is like a snapshot, a read-only copy of a file system or volume. -Bookmarks can be created extremely quickly, compared to snapshots, and they -consume no additional space within the pool. -Bookmarks can also have arbitrary names, much like snapshots. -.Pp -Unlike snapshots, bookmarks can not be accessed through the filesystem in any way. -From a storage standpoint a bookmark just provides a way to reference -when a snapshot was created as a distinct object. -Bookmarks are initially tied to a snapshot, not the filesystem or volume, -and they will survive if the snapshot itself is destroyed. -Since they are very light weight there's little incentive to destroy them. -.Ss Clones -A clone is a writable volume or file system whose initial contents are the same -as another dataset. -As with snapshots, creating a clone is nearly instantaneous, and initially -consumes no additional space. -.Pp -Clones can only be created from a snapshot. -When a snapshot is cloned, it creates an implicit dependency between the parent -and child. -Even though the clone is created somewhere else in the dataset hierarchy, the -original snapshot cannot be destroyed as long as a clone exists. -The -.Sy origin -property exposes this dependency, and the -.Cm destroy -command lists any such dependencies, if they exist. -.Pp -The clone parent-child dependency relationship can be reversed by using the -.Cm promote -subcommand. -This causes the -.Qq origin -file system to become a clone of the specified file system, which makes it -possible to destroy the file system that the clone was created from. -.Ss "Mount Points" -Creating a ZFS file system is a simple operation, so the number of file systems -per system is likely to be numerous. -To cope with this, ZFS automatically manages mounting and unmounting file -systems without the need to edit the -.Pa /etc/fstab -file. -All automatically managed file systems are mounted by ZFS at boot time. -.Pp -By default, file systems are mounted under -.Pa /path , -where -.Ar path -is the name of the file system in the ZFS namespace. -Directories are created and destroyed as needed. -.Pp -A file system can also have a mount point set in the -.Sy mountpoint -property. -This directory is created as needed, and ZFS automatically mounts the file -system when the -.Nm zfs Cm mount Fl a -command is invoked -.Po without editing -.Pa /etc/fstab -.Pc . -The -.Sy mountpoint -property can be inherited, so if -.Em pool/home -has a mount point of -.Pa /export/stuff , -then -.Em pool/home/user -automatically inherits a mount point of -.Pa /export/stuff/user . -.Pp -A file system -.Sy mountpoint -property of -.Sy none -prevents the file system from being mounted. -.Pp -If needed, ZFS file systems can also be managed with traditional tools -.Po -.Nm mount , -.Nm umount , -.Pa /etc/fstab -.Pc . -If a file system's mount point is set to -.Sy legacy , -ZFS makes no attempt to manage the file system, and the administrator is -responsible for mounting and unmounting the file system. -Because pools must -be imported before a legacy mount can succeed, administrators should ensure -that legacy mounts are only attempted after the zpool import process -finishes at boot time. -For example, on machines using systemd, the mount option -.Pp -.Nm x-systemd.requires=zfs-import.target -.Pp -will ensure that the zfs-import completes before systemd attempts mounting -the filesystem. -See -.Xr systemd.mount 5 -for details. -.Ss Deduplication -Deduplication is the process for removing redundant data at the block level, -reducing the total amount of data stored. -If a file system has the -.Sy dedup -property enabled, duplicate data blocks are removed synchronously. -The result -is that only unique data is stored and common components are shared among files. -.Pp -Deduplicating data is a very resource-intensive operation. -It is generally recommended that you have at least 1.25 GiB of RAM -per 1 TiB of storage when you enable deduplication. -Calculating the exact requirement depends heavily -on the type of data stored in the pool. -.Pp -Enabling deduplication on an improperly-designed system can result in -performance issues (slow IO and administrative operations). -It can potentially lead to problems importing a pool due to memory exhaustion. -Deduplication can consume significant processing power (CPU) and memory as well -as generate additional disk IO. -.Pp -Before creating a pool with deduplication enabled, ensure that you have planned -your hardware requirements appropriately and implemented appropriate recovery -practices, such as regular backups. -Consider using the -.Sy compression -property as a less resource-intensive alternative. diff --git a/man/man8/zfsprops.8 b/man/man8/zfsprops.8 deleted file mode 100644 index 1b985c98e..000000000 --- a/man/man8/zfsprops.8 +++ /dev/null @@ -1,2067 +0,0 @@ -.\" -.\" CDDL HEADER START -.\" -.\" The contents of this file are subject to the terms of the -.\" Common Development and Distribution License (the "License"). -.\" You may not use this file except in compliance with the License. -.\" -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE -.\" or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions -.\" and limitations under the License. -.\" -.\" When distributing Covered Code, include this CDDL HEADER in each -.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. -.\" If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] -.\" -.\" CDDL HEADER END -.\" -.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright 2011 Joshua M. Clulow <[email protected]> -.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. -.\" Copyright (c) 2011, Pawel Jakub Dawidek <[email protected]> -.\" Copyright (c) 2012, Glen Barber <[email protected]> -.\" Copyright (c) 2012, Bryan Drewery <[email protected]> -.\" Copyright (c) 2013, Steven Hartland <[email protected]> -.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. -.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. -.\" Copyright (c) 2014 by Adam Stevko. All rights reserved. -.\" Copyright (c) 2014 Integros [integros.com] -.\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved. -.\" Copyright (c) 2014, Xin LI <[email protected]> -.\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved. -.\" Copyright 2019 Richard Laager. All rights reserved. -.\" Copyright 2018 Nexenta Systems, Inc. -.\" Copyright 2019 Joyent, Inc. -.\" Copyright (c) 2019, Kjeld Schouten-Lebbing -.\" -.Dd May 24, 2021 -.Dt ZFSPROPS 8 -.Os -. -.Sh NAME -.Nm zfsprops -.Nd native and user-defined properties of ZFS datasets -. -.Sh DESCRIPTION -Properties are divided into two types, native properties and user-defined -.Po or -.Qq user -.Pc -properties. -Native properties either export internal statistics or control ZFS behavior. -In addition, native properties are either editable or read-only. -User properties have no effect on ZFS behavior, but you can use them to annotate -datasets in a way that is meaningful in your environment. -For more information about user properties, see the -.Sx User Properties -section, below. -. -.Ss Native Properties -Every dataset has a set of properties that export statistics about the dataset -as well as control various behaviors. -Properties are inherited from the parent unless overridden by the child. -Some properties apply only to certain types of datasets -.Pq file systems, volumes, or snapshots . -.Pp -The values of numeric properties can be specified using human-readable suffixes -.Po for example, -.Sy k , -.Sy KB , -.Sy M , -.Sy Gb , -and so forth, up to -.Sy Z -for zettabyte -.Pc . -The following are all valid -.Pq and equal -specifications: -.Li 1536M, 1.5g, 1.50GB . -.Pp -The values of non-numeric properties are case sensitive and must be lowercase, -except for -.Sy mountpoint , -.Sy sharenfs , -and -.Sy sharesmb . -.Pp -The following native properties consist of read-only statistics about the -dataset. -These properties can be neither set, nor inherited. -Native properties apply to all dataset types unless otherwise noted. -.Bl -tag -width "usedbyrefreservation" -.It Sy available -The amount of space available to the dataset and all its children, assuming that -there is no other activity in the pool. -Because space is shared within a pool, availability can be limited by any number -of factors, including physical pool size, quotas, reservations, or other -datasets within the pool. -.Pp -This property can also be referred to by its shortened column name, -.Sy avail . -.It Sy compressratio -For non-snapshots, the compression ratio achieved for the -.Sy used -space of this dataset, expressed as a multiplier. -The -.Sy used -property includes descendant datasets, and, for clones, does not include the -space shared with the origin snapshot. -For snapshots, the -.Sy compressratio -is the same as the -.Sy refcompressratio -property. -Compression can be turned on by running: -.Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . -The default value is -.Sy off . -.It Sy createtxg -The transaction group (txg) in which the dataset was created. -Bookmarks have the same -.Sy createtxg -as the snapshot they are initially tied to. -This property is suitable for ordering a list of snapshots, -e.g. for incremental send and receive. -.It Sy creation -The time this dataset was created. -.It Sy clones -For snapshots, this property is a comma-separated list of filesystems or volumes -which are clones of this snapshot. -The clones' -.Sy origin -property is this snapshot. -If the -.Sy clones -property is not empty, then this snapshot can not be destroyed -.Po even with the -.Fl r -or -.Fl f -options -.Pc . -The roles of origin and clone can be swapped by promoting the clone with the -.Nm zfs Cm promote -command. -.It Sy defer_destroy -This property is -.Sy on -if the snapshot has been marked for deferred destroy by using the -.Nm zfs Cm destroy Fl d -command. -Otherwise, the property is -.Sy off . -.It Sy encryptionroot -For encrypted datasets, indicates where the dataset is currently inheriting its -encryption key from. -Loading or unloading a key for the -.Sy encryptionroot -will implicitly load / unload the key for any inheriting datasets (see -.Nm zfs Cm load-key -and -.Nm zfs Cm unload-key -for details). -Clones will always share an -encryption key with their origin. -See the -.Sx Encryption -section of -.Xr zfs-load-key 8 -for details. -.It Sy filesystem_count -The total number of filesystems and volumes that exist under this location in -the dataset tree. -This value is only available when a -.Sy filesystem_limit -has been set somewhere in the tree under which the dataset resides. -.It Sy keystatus -Indicates if an encryption key is currently loaded into ZFS. -The possible values are -.Sy none , -.Sy available , -and -.Sy unavailable . -See -.Nm zfs Cm load-key -and -.Nm zfs Cm unload-key . -.It Sy guid -The 64 bit GUID of this dataset or bookmark which does not change over its -entire lifetime. -When a snapshot is sent to another pool, the received snapshot has the same GUID. -Thus, the -.Sy guid -is suitable to identify a snapshot across pools. -.It Sy logicalreferenced -The amount of space that is -.Qq logically -accessible by this dataset. -See the -.Sy referenced -property. -The logical space ignores the effect of the -.Sy compression -and -.Sy copies -properties, giving a quantity closer to the amount of data that applications -see. -However, it does include space consumed by metadata. -.Pp -This property can also be referred to by its shortened column name, -.Sy lrefer . -.It Sy logicalused -The amount of space that is -.Qq logically -consumed by this dataset and all its descendents. -See the -.Sy used -property. -The logical space ignores the effect of the -.Sy compression -and -.Sy copies -properties, giving a quantity closer to the amount of data that applications -see. -However, it does include space consumed by metadata. -.Pp -This property can also be referred to by its shortened column name, -.Sy lused . -.It Sy mounted -For file systems, indicates whether the file system is currently mounted. -This property can be either -.Sy yes -or -.Sy no . -.It Sy objsetid -A unique identifier for this dataset within the pool. -Unlike the dataset's -.Sy guid , No the Sy objsetid -of a dataset is not transferred to other pools when the snapshot is copied -with a send/receive operation. -The -.Sy objsetid -can be reused (for a new dataset) after the dataset is deleted. -.It Sy origin -For cloned file systems or volumes, the snapshot from which the clone was -created. -See also the -.Sy clones -property. -.It Sy receive_resume_token -For filesystems or volumes which have saved partially-completed state from -.Nm zfs Cm receive Fl s , -this opaque token can be provided to -.Nm zfs Cm send Fl t -to resume and complete the -.Nm zfs Cm receive . -.It Sy redact_snaps -For bookmarks, this is the list of snapshot guids the bookmark contains a redaction -list for. -For snapshots, this is the list of snapshot guids the snapshot is redacted with -respect to. -.It Sy referenced -The amount of data that is accessible by this dataset, which may or may not be -shared with other datasets in the pool. -When a snapshot or clone is created, it initially references the same amount of -space as the file system or snapshot it was created from, since its contents are -identical. -.Pp -This property can also be referred to by its shortened column name, -.Sy refer . -.It Sy refcompressratio -The compression ratio achieved for the -.Sy referenced -space of this dataset, expressed as a multiplier. -See also the -.Sy compressratio -property. -.It Sy snapshot_count -The total number of snapshots that exist under this location in the dataset -tree. -This value is only available when a -.Sy snapshot_limit -has been set somewhere in the tree under which the dataset resides. -.It Sy type -The type of dataset: -.Sy filesystem , -.Sy volume , -.Sy snapshot , -or -.Sy bookmark . -.It Sy used -The amount of space consumed by this dataset and all its descendents. -This is the value that is checked against this dataset's quota and reservation. -The space used does not include this dataset's reservation, but does take into -account the reservations of any descendent datasets. -The amount of space that a dataset consumes from its parent, as well as the -amount of space that is freed if this dataset is recursively destroyed, is the -greater of its space used and its reservation. -.Pp -The used space of a snapshot -.Po see the -.Sx Snapshots -section of -.Xr zfsconcepts 8 -.Pc -is space that is referenced exclusively by this snapshot. -If this snapshot is destroyed, the amount of -.Sy used -space will be freed. -Space that is shared by multiple snapshots isn't accounted for in this metric. -When a snapshot is destroyed, space that was previously shared with this -snapshot can become unique to snapshots adjacent to it, thus changing the used -space of those snapshots. -The used space of the latest snapshot can also be affected by changes in the -file system. -Note that the -.Sy used -space of a snapshot is a subset of the -.Sy written -space of the snapshot. -.Pp -The amount of space used, available, or referenced does not take into account -pending changes. -Pending changes are generally accounted for within a few seconds. -Committing a change to a disk using -.Xr fsync 2 -or -.Sy O_SYNC -does not necessarily guarantee that the space usage information is updated -immediately. -.It Sy usedby* -The -.Sy usedby* -properties decompose the -.Sy used -properties into the various reasons that space is used. -Specifically, -.Sy used No = -.Sy usedbychildren No + -.Sy usedbydataset No + -.Sy usedbyrefreservation No + -.Sy usedbysnapshots . -These properties are only available for datasets created on -.Nm zpool -.Qo version 13 Qc -pools. -.It Sy usedbychildren -The amount of space used by children of this dataset, which would be freed if -all the dataset's children were destroyed. -.It Sy usedbydataset -The amount of space used by this dataset itself, which would be freed if the -dataset were destroyed -.Po after first removing any -.Sy refreservation -and destroying any necessary snapshots or descendents -.Pc . -.It Sy usedbyrefreservation -The amount of space used by a -.Sy refreservation -set on this dataset, which would be freed if the -.Sy refreservation -was removed. -.It Sy usedbysnapshots -The amount of space consumed by snapshots of this dataset. -In particular, it is the amount of space that would be freed if all of this -dataset's snapshots were destroyed. -Note that this is not simply the sum of the snapshots' -.Sy used -properties because space can be shared by multiple snapshots. -.It Sy userused Ns @ Ns Ar user -The amount of space consumed by the specified user in this dataset. -Space is charged to the owner of each file, as displayed by -.Nm ls Fl l . -The amount of space charged is displayed by -.Nm du No and Nm ls Fl s . -See the -.Nm zfs Cm userspace -command for more information. -.Pp -Unprivileged users can access only their own space usage. -The root user, or a user who has been granted the -.Sy userused -privilege with -.Nm zfs Cm allow , -can access everyone's usage. -.Pp -The -.Sy userused Ns @ Ns Ar ... -properties are not displayed by -.Nm zfs Cm get Sy all . -The user's name must be appended after the -.Sy @ -symbol, using one of the following forms: -.Bl -bullet -compact -offset 4n -.It -POSIX name -.Pq Qq joe -.It -POSIX numeric ID -.Pq Qq 789 -.It -SID name -.Pq Qq joe.smith@mydomain -.It -SID numeric ID -.Pq Qq S-1-123-456-789 -.El -.Pp -Files created on Linux always have POSIX owners. -.It Sy userobjused Ns @ Ns Ar user -The -.Sy userobjused -property is similar to -.Sy userused -but instead it counts the number of objects consumed by a user. -This property counts all objects allocated on behalf of the user, -it may differ from the results of system tools such as -.Nm df Fl i . -.Pp -When the property -.Sy xattr Ns = Ns Sy on -is set on a file system additional objects will be created per-file to store -extended attributes. -These additional objects are reflected in the -.Sy userobjused -value and are counted against the user's -.Sy userobjquota . -When a file system is configured to use -.Sy xattr Ns = Ns Sy sa -no additional internal objects are normally required. -.It Sy userrefs -This property is set to the number of user holds on this snapshot. -User holds are set by using the -.Nm zfs Cm hold -command. -.It Sy groupused Ns @ Ns Ar group -The amount of space consumed by the specified group in this dataset. -Space is charged to the group of each file, as displayed by -.Nm ls Fl l . -See the -.Sy userused Ns @ Ns Ar user -property for more information. -.Pp -Unprivileged users can only access their own groups' space usage. -The root user, or a user who has been granted the -.Sy groupused -privilege with -.Nm zfs Cm allow , -can access all groups' usage. -.It Sy groupobjused Ns @ Ns Ar group -The number of objects consumed by the specified group in this dataset. -Multiple objects may be charged to the group for each file when extended -attributes are in use. -See the -.Sy userobjused Ns @ Ns Ar user -property for more information. -.Pp -Unprivileged users can only access their own groups' space usage. -The root user, or a user who has been granted the -.Sy groupobjused -privilege with -.Nm zfs Cm allow , -can access all groups' usage. -.It Sy projectused Ns @ Ns Ar project -The amount of space consumed by the specified project in this dataset. -Project is identified via the project identifier (ID) that is object-based -numeral attribute. -An object can inherit the project ID from its parent object (if the -parent has the flag of inherit project ID that can be set and changed via -.Nm chattr Fl /+P -or -.Nm zfs project Fl s ) -when being created. -The privileged user can set and change object's project -ID via -.Nm chattr Fl p -or -.Nm zfs project Fl s -anytime. -Space is charged to the project of each file, as displayed by -.Nm lsattr Fl p -or -.Nm zfs project . -See the -.Sy userused Ns @ Ns Ar user -property for more information. -.Pp -The root user, or a user who has been granted the -.Sy projectused -privilege with -.Nm zfs allow , -can access all projects' usage. -.It Sy projectobjused Ns @ Ns Ar project -The -.Sy projectobjused -is similar to -.Sy projectused -but instead it counts the number of objects consumed by project. -When the property -.Sy xattr Ns = Ns Sy on -is set on a fileset, ZFS will create additional objects per-file to store -extended attributes. -These additional objects are reflected in the -.Sy projectobjused -value and are counted against the project's -.Sy projectobjquota . -When a filesystem is configured to use -.Sy xattr Ns = Ns Sy sa -no additional internal objects are required. -See the -.Sy userobjused Ns @ Ns Ar user -property for more information. -.Pp -The root user, or a user who has been granted the -.Sy projectobjused -privilege with -.Nm zfs allow , -can access all projects' objects usage. -.It Sy volblocksize -For volumes, specifies the block size of the volume. -The -.Sy blocksize -cannot be changed once the volume has been written, so it should be set at -volume creation time. -The default -.Sy blocksize -for volumes is 8 Kbytes. -Any power of 2 from 512 bytes to 128 Kbytes is valid. -.Pp -This property can also be referred to by its shortened column name, -.Sy volblock . -.It Sy written -The amount of space -.Sy referenced -by this dataset, that was written since the previous snapshot -.Pq i.e. that is not referenced by the previous snapshot . -.It Sy written Ns @ Ns Ar snapshot -The amount of -.Sy referenced -space written to this dataset since the specified snapshot. -This is the space that is referenced by this dataset but was not referenced by -the specified snapshot. -.Pp -The -.Ar snapshot -may be specified as a short snapshot name -.Pq just the part after the Sy @ , -in which case it will be interpreted as a snapshot in the same filesystem as -this dataset. -The -.Ar snapshot -may be a full snapshot name -.Pq Ar filesystem Ns @ Ns Ar snapshot , -which for clones may be a snapshot in the origin's filesystem -.Pq or the origin of the origin's filesystem, etc. -.El -.Pp -The following native properties can be used to change the behavior of a ZFS -dataset. -.Bl -tag -width "" -.It Xo -.Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns -.Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x -.Xc -Controls how ACEs are inherited when files and directories are created. -.Bl -tag -compact -offset 4n -width "passthrough-x" -.It Sy discard -does not inherit any ACEs. -.It Sy noallow -only inherits inheritable ACEs that specify -.Qq deny -permissions. -.It Sy restricted -default, removes the -.Sy write_acl -and -.Sy write_owner -permissions when the ACE is inherited. -.It Sy passthrough -inherits all inheritable ACEs without any modifications. -.It Sy passthrough-x -same meaning as -.Sy passthrough , -except that the -.Sy owner@ , group@ , No and Sy everyone@ -ACEs inherit the execute permission only if the file creation mode also requests -the execute bit. -.El -.Pp -When the property value is set to -.Sy passthrough , -files are created with a mode determined by the inheritable ACEs. -If no inheritable ACEs exist that affect the mode, then the mode is set in -accordance to the requested mode from the application. -.Pp -The -.Sy aclinherit -property does not apply to POSIX ACLs. -.It Xo -.Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns -.Sy passthrough Ns | Ns Sy restricted Ns -.Xc -Controls how an ACL is modified during chmod(2) and how inherited ACEs -are modified by the file creation mode: -.Bl -tag -compact -offset 4n -width "passthrough" -.It Sy discard -default, deletes all -.Sy ACEs -except for those representing -the mode of the file or directory requested by -.Xr chmod 2 . -.It Sy groupmask -reduces permissions granted in all -.Sy ALLOW -entries found in the -.Sy ACL -such that they are no greater than the group permissions specified by -.Xr chmod 2 . -.It Sy passthrough -indicates that no changes are made to the ACL other than creating or updating -the necessary ACL entries to represent the new mode of the file or directory. -.It Sy restricted -will cause the -.Xr chmod 2 -operation to return an error when used on any file or directory which has -a non-trivial ACL whose entries can not be represented by a mode. -.Xr chmod 2 -is required to change the set user ID, set group ID, or sticky bits on a file -or directory, as they do not have equivalent ACL entries. -In order to use -.Xr chmod 2 -on a file or directory with a non-trivial ACL when -.Sy aclmode -is set to -.Sy restricted , -you must first remove all ACL entries which do not represent the current mode. -.El -.It Sy acltype Ns = Ns Sy off Ns | Ns Sy nfsv4 Ns | Ns Sy posix -Controls whether ACLs are enabled and if so what type of ACL to use. -When this property is set to a type of ACL not supported by the current -platform, the behavior is the same as if it were set to -.Sy off . -.Bl -tag -compact -offset 4n -width "posixacl" -.It Sy off -default on Linux, when a file system has the -.Sy acltype -property set to off then ACLs are disabled. -.It Sy noacl -an alias for -.Sy off -.It Sy nfsv4 -default on -.Fx , -indicates that NFSv4-style ZFS ACLs should be used. -These ACLs can be managed with the -.Xr getfacl 1 -and -.Xr setfacl 1 . -The -.Sy nfsv4 -ZFS ACL type is not yet supported on Linux. -.It Sy posix -indicates POSIX ACLs should be used. -POSIX ACLs are specific to Linux and are not functional on other platforms. -POSIX ACLs are stored as an extended -attribute and therefore will not overwrite any existing NFSv4 ACLs which -may be set. -.It Sy posixacl -an alias for -.Sy posix -.El -.Pp -To obtain the best performance when setting -.Sy posix -users are strongly encouraged to set the -.Sy xattr Ns = Ns Sy sa -property. -This will result in the POSIX ACL being stored more efficiently on disk. -But as a consequence, all new extended attributes will only be -accessible from OpenZFS implementations which support the -.Sy xattr Ns = Ns Sy sa -property. -See the -.Sy xattr -property for more details. -.It Sy atime Ns = Ns Sy on Ns | Ns Sy off -Controls whether the access time for files is updated when they are read. -Turning this property off avoids producing write traffic when reading files and -can result in significant performance gains, though it might confuse mailers -and other similar utilities. -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy atime -and -.Sy noatime -mount options. -The default value is -.Sy on . -See also -.Sy relatime -below. -.It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto -If this property is set to -.Sy off , -the file system cannot be mounted, and is ignored by -.Nm zfs Cm mount Fl a . -Setting this property to -.Sy off -is similar to setting the -.Sy mountpoint -property to -.Sy none , -except that the dataset still has a normal -.Sy mountpoint -property, which can be inherited. -Setting this property to -.Sy off -allows datasets to be used solely as a mechanism to inherit properties. -One example of setting -.Sy canmount Ns = Ns Sy off -is to have two datasets with the same -.Sy mountpoint , -so that the children of both datasets appear in the same directory, but might -have different inherited characteristics. -.Pp -When set to -.Sy noauto , -a dataset can only be mounted and unmounted explicitly. -The dataset is not mounted automatically when the dataset is created or -imported, nor is it mounted by the -.Nm zfs Cm mount Fl a -command or unmounted by the -.Nm zfs Cm unmount Fl a -command. -.Pp -This property is not inherited. -.It Xo -.Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns -.Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns -.Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr -.Xc -Controls the checksum used to verify data integrity. -The default value is -.Sy on , -which automatically selects an appropriate algorithm -.Po currently, -.Sy fletcher4 , -but this may change in future releases -.Pc . -The value -.Sy off -disables integrity checking on user data. -The value -.Sy noparity -not only disables integrity but also disables maintaining parity for user data. -This setting is used internally by a dump device residing on a RAID-Z pool and -should not be used by any other dataset. -Disabling checksums is -.Em NOT -a recommended practice. -.Pp -The -.Sy sha512 , -.Sy skein , -and -.Sy edonr -checksum algorithms require enabling the appropriate features on the pool. -.Fx -does not support the -.Sy edonr -algorithm. -.Pp -Please see -.Xr zpool-features 5 -for more information on these algorithms. -.Pp -Changing this property affects only newly-written data. -.It Xo -.Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns -.Sy gzip- Ns Ar N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns -.Sy zstd- Ns Ar N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Ar N -.Xc -Controls the compression algorithm used for this dataset. -.Pp -Setting compression to -.Sy on -indicates that the current default compression algorithm should be used. -The default balances compression and decompression speed, with compression ratio -and is expected to work well on a wide variety of workloads. -Unlike all other settings for this property, -.Sy on -does not select a fixed compression type. -As new compression algorithms are added to ZFS and enabled on a pool, the -default compression algorithm may change. -The current default compression algorithm is either -.Sy lzjb -or, if the -.Sy lz4_compress -feature is enabled, -.Sy lz4 . -.Pp -The -.Sy lz4 -compression algorithm is a high-performance replacement for the -.Sy lzjb -algorithm. -It features significantly faster compression and decompression, as well as a -moderately higher compression ratio than -.Sy lzjb , -but can only be used on pools with the -.Sy lz4_compress -feature set to -.Sy enabled . -See -.Xr zpool-features 5 -for details on ZFS feature flags and the -.Sy lz4_compress -feature. -.Pp -The -.Sy lzjb -compression algorithm is optimized for performance while providing decent data -compression. -.Pp -The -.Sy gzip -compression algorithm uses the same compression as the -.Xr gzip 1 -command. -You can specify the -.Sy gzip -level by using the value -.Sy gzip- Ns Ar N , -where -.Ar N -is an integer from 1 -.Pq fastest -to 9 -.Pq best compression ratio . -Currently, -.Sy gzip -is equivalent to -.Sy gzip-6 -.Po which is also the default for -.Xr gzip 1 -.Pc . -.Pp -The -.Sy zstd -compression algorithm provides both high compression ratios and good performance. -You can specify the -.Sy zstd -level by using the value -.Sy zstd- Ns Ar N , -where -.Ar N -is an integer from 1 -.Pq fastest -to 19 -.Pq best compression ratio . -.Sy zstd -is equivalent to -.Sy zstd-3 . -.Pp -Faster speeds at the cost of the compression ratio can be requested by -setting a negative -.Sy zstd -level. -This is done using -.Sy zstd-fast- Ns Ar N , -where -.Ar N -is an integer in [1-9,10,20,30,...,100,500,1000] which maps to a negative -.Sy zstd -level. -The lower the level the faster the compression - -.Ar 1000 No provides the fastest compression and lowest compression ratio. -.Sy zstd-fast -is equivalent to -.Sy zstd-fast-1 . -.Pp -The -.Sy zle -compression algorithm compresses runs of zeros. -.Pp -This property can also be referred to by its shortened column name -.Sy compress . -Changing this property affects only newly-written data. -.Pp -When any setting except -.Sy off -is selected, compression will explicitly check for blocks consisting of only -zeroes (the NUL byte). -When a zero-filled block is detected, it is stored as -a hole and not compressed using the indicated compression algorithm. -.Pp -Any block being compressed must be no larger than 7/8 of its original size -after compression, otherwise the compression will not be considered worthwhile -and the block saved uncompressed. -Note that when the logical block is less than -8 times the disk sector size this effectively reduces the necessary compression -ratio; for example, 8kB blocks on disks with 4kB disk sectors must compress to 1/2 -or less of their original size. -.It Xo -.Sy context Ns = Ns Sy none Ns | Ns -.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level -.Xc -This flag sets the SELinux context for all files in the file system under -a mount point for that file system. -See -.Xr selinux 8 -for more information. -.It Xo -.Sy fscontext Ns = Ns Sy none Ns | Ns -.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level -.Xc -This flag sets the SELinux context for the file system file system being -mounted. -See -.Xr selinux 8 -for more information. -.It Xo -.Sy defcontext Ns = Ns Sy none Ns | Ns -.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level -.Xc -This flag sets the SELinux default context for unlabeled files. -See -.Xr selinux 8 -for more information. -.It Xo -.Sy rootcontext Ns = Ns Sy none Ns | Ns -.Ar SELinux-User : Ns Ar SElinux-Role : Ns Ar Selinux-Type : Ns Ar Sensitivity-Level -.Xc -This flag sets the SELinux context for the root inode of the file system. -See -.Xr selinux 8 -for more information. -.It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 -Controls the number of copies of data stored for this dataset. -These copies are in addition to any redundancy provided by the pool, for -example, mirroring or RAID-Z. -The copies are stored on different disks, if possible. -The space used by multiple copies is charged to the associated file and dataset, -changing the -.Sy used -property and counting against quotas and reservations. -.Pp -Changing this property only affects newly-written data. -Therefore, set this property at file system creation time by using the -.Fl o Sy copies Ns = Ns Ar N -option. -.Pp -Remember that ZFS will not import a pool with a missing top-level vdev. -Do -.Em NOT -create, for example a two-disk striped pool and set -.Sy copies Ns = Ns Ar 2 -on some datasets thinking you have setup redundancy for them. -When a disk fails you will not be able to import the pool -and will have lost all of your data. -.Pp -Encrypted datasets may not have -.Sy copies Ns = Ns Ar 3 -since the implementation stores some encryption metadata where the third copy -would normally be. -.It Sy devices Ns = Ns Sy on Ns | Ns Sy off -Controls whether device nodes can be opened on this file system. -The default value is -.Sy on . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy dev -and -.Sy nodev -mount options. -.It Xo -.Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns -.Sy sha256 Ns Oo , Ns Sy verify Oc Ns | Ns Sy sha512 Ns Oo , Ns Sy verify Oc Ns | Ns Sy skein Ns Oo , Ns Sy verify Oc Ns | Ns -.Sy edonr , Ns Sy verify -.Xc -Configures deduplication for a dataset. -The default value is -.Sy off . -The default deduplication checksum is -.Sy sha256 -(this may change in the future). -When -.Sy dedup -is enabled, the checksum defined here overrides the -.Sy checksum -property. -Setting the value to -.Sy verify -has the same effect as the setting -.Sy sha256 , Ns Sy verify . -.Pp -If set to -.Sy verify , -ZFS will do a byte-to-byte comparison in case of two blocks having the same -signature to make sure the block contents are identical. -Specifying -.Sy verify -is mandatory for the -.Sy edonr -algorithm. -.Pp -Unless necessary, deduplication should -.Em not -be enabled on a system. -See the -.Sx Deduplication -section of -.Xr zfsconcepts 8 . -.It Xo -.Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns -.Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k -.Xc -Specifies a compatibility mode or literal value for the size of dnodes in the -file system. -The default value is -.Sy legacy . -Setting this property to a value other than -.Sy legacy No requires the Sy large_dnode No pool feature to be enabled. -.Pp -Consider setting -.Sy dnodesize -to -.Sy auto -if the dataset uses the -.Sy xattr Ns = Ns Sy sa -property setting and the workload makes heavy use of extended attributes. -This -may be applicable to SELinux-enabled systems, Lustre servers, and Samba -servers, for example. -Literal values are supported for cases where the optimal -size is known in advance and for performance testing. -.Pp -Leave -.Sy dnodesize -set to -.Sy legacy -if you need to receive a send stream of this dataset on a pool that doesn't -enable the -.Sy large_dnode -feature, or if you need to import this pool on a system that doesn't support the -.Sy large_dnode No feature. -.Pp -This property can also be referred to by its shortened column name, -.Sy dnsize . -.It Xo -.Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns -.Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns -.Sy aes-192-gcm Ns | Ns Sy aes-256-gcm -.Xc -Controls the encryption cipher suite (block cipher, key length, and mode) used -for this dataset. -Requires the -.Sy encryption -feature to be enabled on the pool. -Requires a -.Sy keyformat -to be set at dataset creation time. -.Pp -Selecting -.Sy encryption Ns = Ns Sy on -when creating a dataset indicates that the default encryption suite will be -selected, which is currently -.Sy aes-256-gcm . -In order to provide consistent data protection, encryption must be specified at -dataset creation time and it cannot be changed afterwards. -.Pp -For more details and caveats about encryption see the -.Sx Encryption -section of -.Xr zfs-load-key 8 . -.It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase -Controls what format the user's encryption key will be provided as. -This property is only set when the dataset is encrypted. -.Pp -Raw keys and hex keys must be 32 bytes long (regardless of the chosen -encryption suite) and must be randomly generated. -A raw key can be generated with the following command: -.Dl # Nm dd Sy if=/dev/urandom bs=32 count=1 Sy of= Ns Pa /path/to/output/key -.Pp -Passphrases must be between 8 and 512 bytes long and will be processed through -PBKDF2 before being used (see the -.Sy pbkdf2iters -property). -Even though the encryption suite cannot be changed after dataset creation, -the keyformat can be with -.Nm zfs Cm change-key . -.It Xo -.Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Ar /absolute/file/path Ns | Ns Sy https:// Ns Ar address Ns | Ns Sy http:// Ns Ar address -.Xc -Controls where the user's encryption key will be loaded from by default for -commands such as -.Nm zfs Cm load-key -and -.Nm zfs Cm mount Fl l . -This property is only set for encrypted datasets which are encryption roots. -If unspecified, the default is -.Sy prompt . -.Pp -Even though the encryption suite cannot be changed after dataset creation, the -keylocation can be with either -.Nm zfs Cm set -or -.Nm zfs Cm change-key . -If -.Sy prompt -is selected ZFS will ask for the key at the command prompt when it is required -to access the encrypted data (see -.Nm zfs Cm load-key -for details). -This setting will also allow the key to be passed in via the standard input stream, -but users should be careful not to place keys which should be kept secret on -the command line. -If a file URI is selected, the key will be loaded from the -specified absolute file path. -If an HTTPS or HTTP URL is selected, it will be GETted using -.Xr fetch 3 , -libcurl, or nothing, depending on compile-time configuration and run-time availability. -The -.Sy SSL_CA_CERT_FILE -environment variable can be set to set the location -of the concatenated certificate store. -The -.Sy SSL_CA_CERT_PATH -environment variable can be set to override the location -of the directory containing the certificate authority bundle. -The -.Sy SSL_CLIENT_CERT_FILE -and -.Sy SSL_CLIENT_KEY_FILE -environment variables can be set to configure the path -to the client certificate and its key. -.It Sy pbkdf2iters Ns = Ns Ar iterations -Controls the number of PBKDF2 iterations that a -.Sy passphrase -encryption key should be run through when processing it into an encryption key. -This property is only defined when encryption is enabled and a keyformat of -.Sy passphrase -is selected. -The goal of PBKDF2 is to significantly increase the -computational difficulty needed to brute force a user's passphrase. -This is accomplished by forcing the attacker to run each passphrase through a -computationally expensive hashing function many times before they arrive at the -resulting key. -A user who actually knows the passphrase will only have to pay this cost once. -As CPUs become better at processing, this number should be -raised to ensure that a brute force attack is still not possible. -The current default is -.Sy 350000 -and the minimum is -.Sy 100000 . -This property may be changed with -.Nm zfs Cm change-key . -.It Sy exec Ns = Ns Sy on Ns | Ns Sy off -Controls whether processes can be executed from within this file system. -The default value is -.Sy on . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy exec -and -.Sy noexec -mount options. -.It Sy filesystem_limit Ns = Ns Ar count Ns | Ns Sy none -Limits the number of filesystems and volumes that can exist under this point in -the dataset tree. -The limit is not enforced if the user is allowed to change the limit. -Setting a -.Sy filesystem_limit -to -.Sy on -a descendent of a filesystem that already has a -.Sy filesystem_limit -does not override the ancestor's -.Sy filesystem_limit , -but rather imposes an additional limit. -This feature must be enabled to be used -.Po see -.Xr zpool-features 5 -.Pc . -.It Sy special_small_blocks Ns = Ns Ar size -This value represents the threshold block size for including small file -blocks into the special allocation class. -Blocks smaller than or equal to this -value will be assigned to the special allocation class while greater blocks -will be assigned to the regular class. -Valid values are zero or a power of two from 512B up to 1M. -The default size is 0 which means no small file blocks -will be allocated in the special class. -.Pp -Before setting this property, a special class vdev must be added to the -pool. -See -.Xr zpoolconcepts 8 -for more details on the special allocation class. -.It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy -Controls the mount point used for this file system. -See the -.Sx Mount Points -section of -.Xr zfsconcepts 8 -for more information on how this property is used. -.Pp -When the -.Sy mountpoint -property is changed for a file system, the file system and any children that -inherit the mount point are unmounted. -If the new value is -.Sy legacy , -then they remain unmounted. -Otherwise, they are automatically remounted in the new location if the property -was previously -.Sy legacy -or -.Sy none , -or if they were mounted before the property was changed. -In addition, any shared file systems are unshared and shared in the new -location. -.It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off -Controls whether the file system should be mounted with -.Sy nbmand -.Pq Non-blocking mandatory locks . -This is used for SMB clients. -Changes to this property only take effect when the file system is umounted and -remounted. -Support for these locks is scarce and not described by POSIX. -.It Sy overlay Ns = Ns Sy on Ns | Ns Sy off -Allow mounting on a busy directory or a directory which already contains -files or directories. -This is the default mount behavior for Linux and -.Fx -file systems. -On these platforms the property is -.Sy on -by default. -Set to -.Sy off -to disable overlay mounts for consistency with OpenZFS on other platforms. -.It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata -Controls what is cached in the primary cache -.Pq ARC . -If this property is set to -.Sy all , -then both user data and metadata is cached. -If this property is set to -.Sy none , -then neither user data nor metadata is cached. -If this property is set to -.Sy metadata , -then only metadata is cached. -The default value is -.Sy all . -.It Sy quota Ns = Ns Ar size Ns | Ns Sy none -Limits the amount of space a dataset and its descendents can consume. -This property enforces a hard limit on the amount of space used. -This includes all space consumed by descendents, including file systems and -snapshots. -Setting a quota on a descendent of a dataset that already has a quota does not -override the ancestor's quota, but rather imposes an additional limit. -.Pp -Quotas cannot be set on volumes, as the -.Sy volsize -property acts as an implicit quota. -.It Sy snapshot_limit Ns = Ns Ar count Ns | Ns Sy none -Limits the number of snapshots that can be created on a dataset and its -descendents. -Setting a -.Sy snapshot_limit -on a descendent of a dataset that already has a -.Sy snapshot_limit -does not override the ancestor's -.Sy snapshot_limit , -but rather imposes an additional limit. -The limit is not enforced if the user is allowed to change the limit. -For example, this means that recursive snapshots taken from the global zone are -counted against each delegated dataset within a zone. -This feature must be enabled to be used -.Po see -.Xr zpool-features 5 -.Pc . -.It Sy userquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none -Limits the amount of space consumed by the specified user. -User space consumption is identified by the -.Sy userspace@ Ns Ar user -property. -.Pp -Enforcement of user quotas may be delayed by several seconds. -This delay means that a user might exceed their quota before the system notices -that they are over quota and begins to refuse additional writes with the -.Er EDQUOT -error message. -See the -.Nm zfs Cm userspace -command for more information. -.Pp -Unprivileged users can only access their own groups' space usage. -The root user, or a user who has been granted the -.Sy userquota -privilege with -.Nm zfs Cm allow , -can get and set everyone's quota. -.Pp -This property is not available on volumes, on file systems before version 4, or -on pools before version 15. -The -.Sy userquota@ Ns Ar ... -properties are not displayed by -.Nm zfs Cm get Sy all . -The user's name must be appended after the -.Sy @ -symbol, using one of the following forms: -.Bl -bullet -compact -offset 4n -.It -POSIX name -.Pq Qq joe -.It -POSIX numeric ID -.Pq Qq 789 -.It -SID name -.Pq Qq joe.smith@mydomain -.It -SID numeric ID -.Pq Qq S-1-123-456-789 -.El -.Pp -Files created on Linux always have POSIX owners. -.It Sy userobjquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none -The -.Sy userobjquota -is similar to -.Sy userquota -but it limits the number of objects a user can create. -Please refer to -.Sy userobjused -for more information about how objects are counted. -.It Sy groupquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none -Limits the amount of space consumed by the specified group. -Group space consumption is identified by the -.Sy groupused@ Ns Ar group -property. -.Pp -Unprivileged users can access only their own groups' space usage. -The root user, or a user who has been granted the -.Sy groupquota -privilege with -.Nm zfs Cm allow , -can get and set all groups' quotas. -.It Sy groupobjquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none -The -.Sy groupobjquota -is similar to -.Sy groupquota -but it limits number of objects a group can consume. -Please refer to -.Sy userobjused -for more information about how objects are counted. -.It Sy projectquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none -Limits the amount of space consumed by the specified project. -Project space consumption is identified by the -.Sy projectused@ Ns Ar project -property. -Please refer to -.Sy projectused -for more information about how project is identified and set/changed. -.Pp -The root user, or a user who has been granted the -.Sy projectquota -privilege with -.Nm zfs allow , -can access all projects' quota. -.It Sy projectobjquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none -The -.Sy projectobjquota -is similar to -.Sy projectquota -but it limits number of objects a project can consume. -Please refer to -.Sy userobjused -for more information about how objects are counted. -.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off -Controls whether this dataset can be modified. -The default value is -.Sy off . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy ro -and -.Sy rw -mount options. -.Pp -This property can also be referred to by its shortened column name, -.Sy rdonly . -.It Sy recordsize Ns = Ns Ar size -Specifies a suggested block size for files in the file system. -This property is designed solely for use with database workloads that access -files in fixed-size records. -ZFS automatically tunes block sizes according to internal algorithms optimized -for typical access patterns. -.Pp -For databases that create very large files but access them in small random -chunks, these algorithms may be suboptimal. -Specifying a -.Sy recordsize -greater than or equal to the record size of the database can result in -significant performance gains. -Use of this property for general purpose file systems is strongly discouraged, -and may adversely affect performance. -.Pp -The size specified must be a power of two greater than or equal to -.Ar 512B -and less than or equal to -.Ar 128kB . -If the -.Sy large_blocks -feature is enabled on the pool, the size may be up to -.Ar 1MB . -See -.Xr zpool-features 5 -for details on ZFS feature flags. -.Pp -Changing the file system's -.Sy recordsize -affects only files created afterward; existing files are unaffected. -.Pp -This property can also be referred to by its shortened column name, -.Sy recsize . -.It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most -Controls what types of metadata are stored redundantly. -ZFS stores an extra copy of metadata, so that if a single block is corrupted, -the amount of user data lost is limited. -This extra copy is in addition to any redundancy provided at the pool level -.Pq e.g. by mirroring or RAID-Z , -and is in addition to an extra copy specified by the -.Sy copies -property -.Pq up to a total of 3 copies . -For example if the pool is mirrored, -.Sy copies Ns = Ns 2 , -and -.Sy redundant_metadata Ns = Ns Sy most , -then ZFS stores 6 copies of most metadata, and 4 copies of data and some -metadata. -.Pp -When set to -.Sy all , -ZFS stores an extra copy of all metadata. -If a single on-disk block is corrupt, at worst a single block of user data -.Po which is -.Sy recordsize -bytes long -.Pc -can be lost. -.Pp -When set to -.Sy most , -ZFS stores an extra copy of most types of metadata. -This can improve performance of random writes, because less metadata must be -written. -In practice, at worst about 100 blocks -.Po of -.Sy recordsize -bytes each -.Pc -of user data can be lost if a single on-disk block is corrupt. -The exact behavior of which metadata blocks are stored redundantly may change in -future releases. -.Pp -The default value is -.Sy all . -.It Sy refquota Ns = Ns Ar size Ns | Ns Sy none -Limits the amount of space a dataset can consume. -This property enforces a hard limit on the amount of space used. -This hard limit does not include space used by descendents, including file -systems and snapshots. -.It Sy refreservation Ns = Ns Ar size Ns | Ns Sy none Ns | Ns Sy auto -The minimum amount of space guaranteed to a dataset, not including its -descendents. -When the amount of space used is below this value, the dataset is treated as if -it were taking up the amount of space specified by -.Sy refreservation . -The -.Sy refreservation -reservation is accounted for in the parent datasets' space used, and counts -against the parent datasets' quotas and reservations. -.Pp -If -.Sy refreservation -is set, a snapshot is only allowed if there is enough free pool space outside of -this reservation to accommodate the current number of -.Qq referenced -bytes in the dataset. -.Pp -If -.Sy refreservation -is set to -.Sy auto , -a volume is thick provisioned -.Po or -.Qq not sparse -.Pc . -.Sy refreservation Ns = Ns Sy auto -is only supported on volumes. -See -.Sy volsize -in the -.Sx Native Properties -section for more information about sparse volumes. -.Pp -This property can also be referred to by its shortened column name, -.Sy refreserv . -.It Sy relatime Ns = Ns Sy on Ns | Ns Sy off -Controls the manner in which the access time is updated when -.Sy atime Ns = Ns Sy on -is set. -Turning this property on causes the access time to be updated relative -to the modify or change time. -Access time is only updated if the previous -access time was earlier than the current modify or change time or if the -existing access time hasn't been updated within the past 24 hours. -The default value is -.Sy off . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy relatime -and -.Sy norelatime -mount options. -.It Sy reservation Ns = Ns Ar size Ns | Ns Sy none -The minimum amount of space guaranteed to a dataset and its descendants. -When the amount of space used is below this value, the dataset is treated as if -it were taking up the amount of space specified by its reservation. -Reservations are accounted for in the parent datasets' space used, and count -against the parent datasets' quotas and reservations. -.Pp -This property can also be referred to by its shortened column name, -.Sy reserv . -.It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata -Controls what is cached in the secondary cache -.Pq L2ARC . -If this property is set to -.Sy all , -then both user data and metadata is cached. -If this property is set to -.Sy none , -then neither user data nor metadata is cached. -If this property is set to -.Sy metadata , -then only metadata is cached. -The default value is -.Sy all . -.It Sy setuid Ns = Ns Sy on Ns | Ns Sy off -Controls whether the setuid bit is respected for the file system. -The default value is -.Sy on . -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy suid -and -.Sy nosuid -mount options. -.It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts -Controls whether the file system is shared by using -.Sy Samba USERSHARES -and what options are to be used. -Otherwise, the file system is automatically shared and unshared with the -.Nm zfs Cm share -and -.Nm zfs Cm unshare -commands. -If the property is set to on, the -.Xr net 8 -command is invoked to create a -.Sy USERSHARE . -.Pp -Because SMB shares requires a resource name, a unique resource name is -constructed from the dataset name. -The constructed name is a copy of the -dataset name except that the characters in the dataset name, which would be -invalid in the resource name, are replaced with underscore (_) characters. -Linux does not currently support additional options which might be available -on Solaris. -.Pp -If the -.Sy sharesmb -property is set to -.Sy off , -the file systems are unshared. -.Pp -The share is created with the ACL (Access Control List) "Everyone:F" ("F" -stands for "full permissions", i.e. read and write permissions) and no guest -access (which means Samba must be able to authenticate a real user, system -passwd/shadow, LDAP or smbpasswd based) by default. -This means that any additional access control -(disallow specific user specific access etc) must be done on the underlying file system. -.It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts -Controls whether the file system is shared via NFS, and what options are to be -used. -A file system with a -.Sy sharenfs -property of -.Sy off -is managed with the -.Xr exportfs 8 -command and entries in the -.Pa /etc/exports -file. -Otherwise, the file system is automatically shared and unshared with the -.Nm zfs Cm share -and -.Nm zfs Cm unshare -commands. -If the property is set to -.Sy on , -the dataset is shared using the default options: -.Dl sec=sys,rw,crossmnt,no_subtree_check -.Pp -See -.Xr exports 5 -for the meaning of the default options. -Otherwise, the -.Xr exportfs 8 -command is invoked with options equivalent to the contents of this property. -.Pp -When the -.Sy sharenfs -property is changed for a dataset, the dataset and any children inheriting the -property are re-shared with the new options, only if the property was previously -.Sy off , -or if they were shared before the property was changed. -If the new property is -.Sy off , -the file systems are unshared. -.It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput -Provide a hint to ZFS about handling of synchronous requests in this dataset. -If -.Sy logbias -is set to -.Sy latency -.Pq the default , -ZFS will use pool log devices -.Pq if configured -to handle the requests at low latency. -If -.Sy logbias -is set to -.Sy throughput , -ZFS will not use configured pool log devices. -ZFS will instead optimize synchronous operations for global pool throughput and -efficient use of resources. -.It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible -Controls whether the volume snapshot devices under -.Pa /dev/zvol/ Ns Aq Ar pool -are hidden or visible. -The default value is -.Sy hidden . -.It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible -Controls whether the -.Pa .zfs -directory is hidden or visible in the root of the file system as discussed in -the -.Sx Snapshots -section of -.Xr zfsconcepts 8 . -The default value is -.Sy hidden . -.It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled -Controls the behavior of synchronous requests -.Pq e.g. fsync, O_DSYNC . -.Sy standard -is the POSIX-specified behavior of ensuring all synchronous requests -are written to stable storage and all devices are flushed to ensure -data is not cached by device controllers -.Pq this is the default . -.Sy always -causes every file system transaction to be written and flushed before its -system call returns. -This has a large performance penalty. -.Sy disabled -disables synchronous requests. -File system transactions are only committed to stable storage periodically. -This option will give the highest performance. -However, it is very dangerous as ZFS would be ignoring the synchronous -transaction demands of applications such as databases or NFS. -Administrators should only use this option when the risks are understood. -.It Sy version Ns = Ns Ar N Ns | Ns Sy current -The on-disk version of this file system, which is independent of the pool -version. -This property can only be set to later supported versions. -See the -.Nm zfs Cm upgrade -command. -.It Sy volsize Ns = Ns Ar size -For volumes, specifies the logical size of the volume. -By default, creating a volume establishes a reservation of equal size. -For storage pools with a version number of 9 or higher, a -.Sy refreservation -is set instead. -Any changes to -.Sy volsize -are reflected in an equivalent change to the reservation -.Pq or Sy refreservation . -The -.Sy volsize -can only be set to a multiple of -.Sy volblocksize , -and cannot be zero. -.Pp -The reservation is kept equal to the volume's logical size to prevent unexpected -behavior for consumers. -Without the reservation, the volume could run out of space, resulting in -undefined behavior or data corruption, depending on how the volume is used. -These effects can also occur when the volume size is changed while it is in use -.Pq particularly when shrinking the size . -Extreme care should be used when adjusting the volume size. -.Pp -Though not recommended, a -.Qq sparse volume -.Po also known as -.Qq thin provisioned -.Pc -can be created by specifying the -.Fl s -option to the -.Nm zfs Cm create Fl V -command, or by changing the value of the -.Sy refreservation -property -.Po or -.Sy reservation -property on pool version 8 or earlier -.Pc -after the volume has been created. -A -.Qq sparse volume -is a volume where the value of -.Sy refreservation -is less than the size of the volume plus the space required to store its -metadata. -Consequently, writes to a sparse volume can fail with -.Er ENOSPC -when the pool is low on space. -For a sparse volume, changes to -.Sy volsize -are not reflected in the -.Sy refreservation . -A volume that is not sparse is said to be -.Qq thick provisioned . -A sparse volume can become thick provisioned by setting -.Sy refreservation -to -.Sy auto . -.It Sy volmode Ns = Ns Sy default Ns | Ns Sy full Ns | Ns Sy geom Ns | Ns Sy dev Ns | Ns Sy none -This property specifies how volumes should be exposed to the OS. -Setting it to -.Sy full -exposes volumes as fully fledged block devices, providing maximal -functionality. -The value -.Sy geom -is just an alias for -.Sy full -and is kept for compatibility. -Setting it to -.Sy dev -hides its partitions. -Volumes with property set to -.Sy none -are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc, -that can be suitable for backup purposes. -Value -.Sy default -means that volumes exposition is controlled by system-wide tunable -.Sy zvol_volmode , -where -.Sy full , -.Sy dev -and -.Sy none -are encoded as 1, 2 and 3 respectively. -The default value is -.Sy full . -.It Sy vscan Ns = Ns Sy on Ns | Ns Sy off -Controls whether regular files should be scanned for viruses when a file is -opened and closed. -In addition to enabling this property, the virus scan service must also be -enabled for virus scanning to occur. -The default value is -.Sy off . -This property is not used by OpenZFS. -.It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa -Controls whether extended attributes are enabled for this file system. -Two styles of extended attributes are supported: either directory based -or system attribute based. -.Pp -The default value of -.Sy on -enables directory based extended attributes. -This style of extended attribute imposes no practical limit -on either the size or number of attributes which can be set on a file. -Although under Linux the -.Xr getxattr 2 -and -.Xr setxattr 2 -system calls limit the maximum size to 64K. -This is the most compatible -style of extended attribute and is supported by all ZFS implementations. -.Pp -System attribute based xattrs can be enabled by setting the value to -.Sy sa . -The key advantage of this type of xattr is improved performance. -Storing extended attributes as system attributes -significantly decreases the amount of disk IO required. -Up to 64K of data may be stored per-file in the space reserved for system attributes. -If there is not enough space available for an extended attribute -then it will be automatically written as a directory based xattr. -System attribute based extended attributes are not accessible -on platforms which do not support the -.Sy xattr Ns = Ns Sy sa -feature. -OpenZFS supports -.Sy xattr Ns = Ns Sy sa -on both -.Fx -and Linux. -.Pp -The use of system attribute based xattrs is strongly encouraged for users of -SELinux or POSIX ACLs. -Both of these features heavily rely on extended -attributes and benefit significantly from the reduced access time. -.Pp -The values -.Sy on -and -.Sy off -are equivalent to the -.Sy xattr -and -.Sy noxattr -mount options. -.It Sy jailed Ns = Ns Sy off Ns | Ns Sy on -Controls whether the dataset is managed from a jail. -See -.Xr zfs-jail 8 -for more information. -Jails are a -.Fx -feature and are not relevant on other platforms. -The default value is -.Sy off . -.It Sy zoned Ns = Ns Sy on Ns | Ns Sy off -Controls whether the dataset is managed from a non-global zone. -Zones are a Solaris feature and are not relevant on other platforms. -The default value is -.Sy off . -.El -.Pp -The following three properties cannot be changed after the file system is -created, and therefore, should be set when the file system is created. -If the properties are not set with the -.Nm zfs Cm create -or -.Nm zpool Cm create -commands, these properties are inherited from the parent dataset. -If the parent dataset lacks these properties due to having been created prior to -these features being supported, the new file system will have the default values -for these properties. -.Bl -tag -width "" -.It Xo -.Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns -.Sy insensitive Ns | Ns Sy mixed -.Xc -Indicates whether the file name matching algorithm used by the file system -should be case-sensitive, case-insensitive, or allow a combination of both -styles of matching. -The default value for the -.Sy casesensitivity -property is -.Sy sensitive . -Traditionally, -.Ux -and POSIX file systems have case-sensitive file names. -.Pp -The -.Sy mixed -value for the -.Sy casesensitivity -property indicates that the file system can support requests for both -case-sensitive and case-insensitive matching behavior. -Currently, case-insensitive matching behavior on a file system that supports -mixed behavior is limited to the SMB server product. -For more information about the -.Sy mixed -value behavior, see the "ZFS Administration Guide". -.It Xo -.Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns -.Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD -.Xc -Indicates whether the file system should perform a -.Sy unicode -normalization of file names whenever two file names are compared, and which -normalization algorithm should be used. -File names are always stored unmodified, names are normalized as part of any -comparison process. -If this property is set to a legal value other than -.Sy none , -and the -.Sy utf8only -property was left unspecified, the -.Sy utf8only -property is automatically set to -.Sy on . -The default value of the -.Sy normalization -property is -.Sy none . -This property cannot be changed after the file system is created. -.It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off -Indicates whether the file system should reject file names that include -characters that are not present in the -.Sy UTF-8 -character code set. -If this property is explicitly set to -.Sy off , -the normalization property must either not be explicitly set or be set to -.Sy none . -The default value for the -.Sy utf8only -property is -.Sy off . -This property cannot be changed after the file system is created. -.El -.Pp -The -.Sy casesensitivity , -.Sy normalization , -and -.Sy utf8only -properties are also new permissions that can be assigned to non-privileged users -by using the ZFS delegated administration feature. -. -.Ss Temporary Mount Point Properties -When a file system is mounted, either through -.Xr mount 8 -for legacy mounts or the -.Nm zfs Cm mount -command for normal file systems, its mount options are set according to its -properties. -The correlation between properties and mount options is as follows: -.Bl -tag -compact -offset Ds -width "rootcontext=" -.It Sy atime -atime/noatime -.It Sy canmount -auto/noauto -.It Sy devices -dev/nodev -.It Sy exec -exec/noexec -.It Sy readonly -ro/rw -.It Sy relatime -relatime/norelatime -.It Sy setuid -suid/nosuid -.It Sy xattr -xattr/noxattr -.It Sy nbmand -mand/nomand -.It Sy context Ns = -context= -.It Sy fscontext Ns = -fscontext= -.It Sy defcontext Ns = -defcontext= -.It Sy rootcontext Ns = -rootcontext= -.El -.Pp -In addition, these options can be set on a per-mount basis using the -.Fl o -option, without affecting the property that is stored on disk. -The values specified on the command line override the values stored in the -dataset. -The -.Sy nosuid -option is an alias for -.Sy nodevices , Ns Sy nosetuid . -These properties are reported as -.Qq temporary -by the -.Nm zfs Cm get -command. -If the properties are changed while the dataset is mounted, the new setting -overrides any temporary settings. -. -.Ss 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 datasets -.Pq file systems, volumes, and snapshots . -.Pp -User property names must contain a colon -.Pq Qq Sy \&: -character to distinguish them from native properties. -They may contain lowercase letters, numbers, and the following punctuation -characters: colon -.Pq Qq Sy \&: , -dash -.Pq Qq Sy - , -period -.Pq Qq Sy \&. , -and underscore -.Pq Qq Sy _ . -The expected convention is that the property name is divided into two portions -such as -.Ar module : Ns Ar property , -but this namespace is not enforced by ZFS. -User property names can be at most 256 characters, and cannot begin with a dash -.Pq Qq Sy - . -.Pp -When making programmatic use of user properties, it is strongly suggested to use -a reversed DNS domain name for the -.Ar module -component of property names to reduce the chance that two -independently-developed packages use the same property name for different -purposes. -.Pp -The values of user properties are arbitrary strings, are always inherited, and -are never validated. -All of the commands that operate on properties -.Po Nm zfs Cm list , -.Nm zfs Cm get , -.Nm zfs Cm set , -and so forth -.Pc -can be used to manipulate both native properties and user properties. -Use the -.Nm zfs Cm inherit -command to clear a user property. -If the property is not defined in any parent dataset, it is removed entirely. -Property values are limited to 8192 bytes. diff --git a/man/man8/zgenhostid.8 b/man/man8/zgenhostid.8 index 4f926f473..3eff55b6d 100644 --- a/man/man8/zgenhostid.8 +++ b/man/man8/zgenhostid.8 @@ -83,7 +83,7 @@ digits long, optionally prefixed by .Xr genhostid 1 , .Xr hostid 1 , .Xr sethostid 3 , -.Xr spl-module-parameters 5 +.Xr spl 4 .Sh HISTORY .Nm emulates the diff --git a/man/man8/zpool-add.8 b/man/man8/zpool-add.8 index a0f15076f..26cf33c55 100644 --- a/man/man8/zpool-add.8 +++ b/man/man8/zpool-add.8 @@ -46,7 +46,7 @@ The specification is described in the .Em Virtual Devices section of -.Xr zpoolconcepts 8 . +.Xr zpoolconcepts 7 . The behavior of the .Fl f option, and the device checks performed are described in the @@ -87,7 +87,7 @@ flag. .It Fl o Ar property Ns = Ns Ar value Sets the given pool properties. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for a list of valid properties that can be set. The only property supported at the moment is .Sy ashift . diff --git a/man/man8/zpool-attach.8 b/man/man8/zpool-attach.8 index 04c0fca21..19d8f6ac0 100644 --- a/man/man8/zpool-attach.8 +++ b/man/man8/zpool-attach.8 @@ -71,7 +71,7 @@ Not all devices can be overridden in this manner. .It Fl o Ar property Ns = Ns Ar value Sets the given pool properties. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for a list of valid properties that can be set. The only property supported at the moment is .Sy ashift . diff --git a/man/man8/zpool-create.8 b/man/man8/zpool-create.8 index 91e6f427d..e902c7700 100644 --- a/man/man8/zpool-create.8 +++ b/man/man8/zpool-create.8 @@ -80,7 +80,7 @@ The specification is described in the .Sx Virtual Devices section of -.Xr zpoolconcepts 8 . +.Xr zpoolconcepts 7 . .Pp The command attempts to verify that each device specified is accessible and not currently in use by another subsystem. @@ -139,7 +139,7 @@ Individual features can be enabled by setting their corresponding properties to with .Fl o . See -.Xr zpool-features 5 +.Xr zpool-features 7 for details about feature properties. .It Fl f Forces use of @@ -160,7 +160,7 @@ The mount point must be an absolute path, or .Sy none . For more information on dataset mount points, see -.Xr zfsprops 8 . +.Xr zfsprops 7 . .It Fl n Displays the configuration that would be used without actually creating the pool. @@ -169,23 +169,23 @@ device sharing. .It Fl o Ar property Ns = Ns Ar value Sets the given pool properties. See -.Xr zpoolprops 8 +.Xr zpoolprops 7 for a list of valid properties that can be set. .It Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns … Specifies compatibility feature sets. See -.Xr zpool-features 5 +.Xr zpool-features 7 for more information about compatibility feature sets. .It Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value Sets the given pool feature. See the -.Xr zpool-features 5 +.Xr zpool-features 7 section for a list of valid features that can be set. Value can be either disabled or enabled. .It Fl O Ar file-system-property Ns = Ns Ar value Sets the given file system properties in the root file system of the pool. See -.Xr zfsprops 8 +.Xr zfsprops 7 for a list of valid properties that can be set. .It Fl R Ar root Equivalent to diff --git a/man/man8/zpool-events.8 b/man/man8/zpool-events.8 index a95ce48d9..ab1d6ea56 100644 --- a/man/man8/zpool-events.8 +++ b/man/man8/zpool-events.8 @@ -49,10 +49,11 @@ These events are consumed by the and used to automate administrative tasks such as replacing a failed device with a hot spare. For more information about the subclasses and event payloads -that can be generated see the -.Xr zfs-events 5 -man page. -.Pp +that can be generated see +.Sx EVENTS +and the following sections. +. +.Sh OPTIONS .Bl -tag -compact -width Ds .It Fl c Clear all previous events. @@ -66,8 +67,417 @@ single tab instead of arbitrary space. Print the entire payload for each event. .El . +.Sh EVENTS +Theese are the different event subclasses. +The full event name would be +.Sy ereport.fs.zfs.\& Ns Em SUBCLASS , +but only the last part is listed here. +.Pp +.Bl -tag -compact -width "vdev.bad_guid_sum" +.It Sy checksum +Issued when a checksum error has been detected. +.It Sy io +Issued when there is an I/O error in a vdev in the pool. +.It Sy data +Issued when there have been data errors in the pool. +.It Sy deadman +Issued when an I/O request is determined to be "hung", this can be caused +by lost completion events due to flaky hardware or drivers. +See +.Sy zfs_deadman_failmode +in +.Xr zfs 4 +for additional information regarding "hung" I/O detection and configuration. +.It Sy delay +Issued when a completed I/O request exceeds the maximum allowed time +specified by the +.Sy zio_slow_io_ms +module parameter. +This can be an indicator of problems with the underlying storage device. +The number of delay events is ratelimited by the +.Sy zfs_slow_io_events_per_second +module parameter. +.It Sy config +Issued every time a vdev change have been done to the pool. +.It Sy zpool +Issued when a pool cannot be imported. +.It Sy zpool.destroy +Issued when a pool is destroyed. +.It Sy zpool.export +Issued when a pool is exported. +.It Sy zpool.import +Issued when a pool is imported. +.It Sy zpool.reguid +Issued when a REGUID (new unique identifier for the pool have been regenerated) have been detected. +.It Sy vdev.unknown +Issued when the vdev is unknown. +Such as trying to clear device errors on a vdev that have failed/been kicked +from the system/pool and is no longer available. +.It Sy vdev.open_failed +Issued when a vdev could not be opened (because it didn't exist for example). +.It Sy vdev.corrupt_data +Issued when corrupt data have been detected on a vdev. +.It Sy vdev.no_replicas +Issued when there are no more replicas to sustain the pool. +This would lead to the pool being +.Em DEGRADED . +.It Sy vdev.bad_guid_sum +Issued when a missing device in the pool have been detected. +.It Sy vdev.too_small +Issued when the system (kernel) have removed a device, and ZFS +notices that the device isn't there any more. +This is usually followed by a +.Sy probe_failure +event. +.It Sy vdev.bad_label +Issued when the label is OK but invalid. +.It Sy vdev.bad_ashift +Issued when the ashift alignment requirement has increased. +.It Sy vdev.remove +Issued when a vdev is detached from a mirror (or a spare detached from a +vdev where it have been used to replace a failed drive - only works if +the original drive have been readded). +.It Sy vdev.clear +Issued when clearing device errors in a pool. +Such as running +.Nm zpool Cm clear +on a device in the pool. +.It Sy vdev.check +Issued when a check to see if a given vdev could be opened is started. +.It Sy vdev.spare +Issued when a spare have kicked in to replace a failed device. +.It Sy vdev.autoexpand +Issued when a vdev can be automatically expanded. +.It Sy io_failure +Issued when there is an I/O failure in a vdev in the pool. +.It Sy probe_failure +Issued when a probe fails on a vdev. +This would occur if a vdev +have been kicked from the system outside of ZFS (such as the kernel +have removed the device). +.It Sy log_replay +Issued when the intent log cannot be replayed. +The can occur in the case of a missing or damaged log device. +.It Sy resilver.start +Issued when a resilver is started. +.It Sy resilver.finish +Issued when the running resilver have finished. +.It Sy scrub.start +Issued when a scrub is started on a pool. +.It Sy scrub.finish +Issued when a pool has finished scrubbing. +.It Sy scrub.abort +Issued when a scrub is aborted on a pool. +.It Sy scrub.resume +Issued when a scrub is resumed on a pool. +.It Sy scrub.paused +Issued when a scrub is paused on a pool. +.It Sy bootfs.vdev.attach +.El +. +.Sh PAYLOADS +This is the payload (data, information) that accompanies an +event. +.Pp +For +.Xr zed 8 , +these are set to uppercase and prefixed with +.Sy ZEVENT_ . +.Pp +.Bl -tag -compact -width "vdev_cksum_errors" +.It Sy pool +Pool name. +.It Sy pool_failmode +Failmode - +.Sy wait , +.Sy continue , +or +.Sy panic . +See the +.Sy failmode +property in +.Xr zpoolprops 7 +for more information. +.It Sy pool_guid +The GUID of the pool. +.It Sy pool_context +The load state for the pool (0=none, 1=open, 2=import, 3=tryimport, 4=recover +5=error). +.It Sy vdev_guid +The GUID of the vdev in question (the vdev failing or operated upon with +.Nm zpool Cm clear , +etc.). +.It Sy vdev_type +Type of vdev - +.Sy disk , +.Sy file , +.Sy mirror , +etc. +See the +.Sy Virtual Devices +section of +.Xr zpoolconcepts 7 +for more information on possible values. +.It Sy vdev_path +Full path of the vdev, including any +.Em -partX . +.It Sy vdev_devid +ID of vdev (if any). +.It Sy vdev_fru +Physical FRU location. +.It Sy vdev_state +State of vdev (0=uninitialized, 1=closed, 2=offline, 3=removed, 4=failed to open, 5=faulted, 6=degraded, 7=healthy). +.It Sy vdev_ashift +The ashift value of the vdev. +.It Sy vdev_complete_ts +The time the last I/O request completed for the specified vdev. +.It Sy vdev_delta_ts +The time since the last I/O request completed for the specified vdev. +.It Sy vdev_spare_paths +List of spares, including full path and any +.Em -partX . +.It Sy vdev_spare_guids +GUID(s) of spares. +.It Sy vdev_read_errors +How many read errors that have been detected on the vdev. +.It Sy vdev_write_errors +How many write errors that have been detected on the vdev. +.It Sy vdev_cksum_errors +How many checksum errors that have been detected on the vdev. +.It Sy parent_guid +GUID of the vdev parent. +.It Sy parent_type +Type of parent. +See +.Sy vdev_type . +.It Sy parent_path +Path of the vdev parent (if any). +.It Sy parent_devid +ID of the vdev parent (if any). +.It Sy zio_objset +The object set number for a given I/O request. +.It Sy zio_object +The object number for a given I/O request. +.It Sy zio_level +The indirect level for the block. +Level 0 is the lowest level and includes data blocks. +Values > 0 indicate metadata blocks at the appropriate level. +.It Sy zio_blkid +The block ID for a given I/O request. +.It Sy zio_err +The error number for a failure when handling a given I/O request, +compatible with +.Xr errno 3 +with the value of +.Sy EBADE +used to indicate a ZFS checksum error. +.It Sy zio_offset +The offset in bytes of where to write the I/O request for the specified vdev. +.It Sy zio_size +The size in bytes of the I/O request. +.It Sy zio_flags +The current flags describing how the I/O request should be handled. +See the +.Sy I/O FLAGS +section for the full list of I/O flags. +.It Sy zio_stage +The current stage of the I/O in the pipeline. +See the +.Sy I/O STAGES +section for a full list of all the I/O stages. +.It Sy zio_pipeline +The valid pipeline stages for the I/O. +See the +.Sy I/O STAGES +section for a full list of all the I/O stages. +.It Sy zio_delay +The time elapsed (in nanoseconds) waiting for the block layer to complete the +I/O request. +Unlike +.Sy zio_delta , +this does not include any vdev queuing time and is +therefore solely a measure of the block layer performance. +.It Sy zio_timestamp +The time when a given I/O request was submitted. +.It Sy zio_delta +The time required to service a given I/O request. +.It Sy prev_state +The previous state of the vdev. +.It Sy cksum_expected +The expected checksum value for the block. +.It Sy cksum_actual +The actual checksum value for an errant block. +.It Sy cksum_algorithm +Checksum algorithm used. +See +.Xr zfsprops 7 +for more information on the available checksum algorithms. +.It Sy cksum_byteswap +Whether or not the data is byteswapped. +.It Sy bad_ranges +.No [\& Ns Ar start , end ) +pairs of corruption offsets. +Offsets are always aligned on a 64-bit boundary, +and can include some gaps of non-corruption. +(See +.Sy bad_ranges_min_gap ) +.It Sy bad_ranges_min_gap +In order to bound the size of the +.Sy bad_ranges +array, gaps of non-corruption +less than or equal to +.Sy bad_ranges_min_gap +bytes have been merged with +adjacent corruption. +Always at least 8 bytes, since corruption is detected on a 64-bit word basis. +.It Sy bad_range_sets +This array has one element per range in +.Sy bad_ranges . +Each element contains +the count of bits in that range which were clear in the good data and set +in the bad data. +.It Sy bad_range_clears +This array has one element per range in +.Sy bad_ranges . +Each element contains +the count of bits for that range which were set in the good data and clear in +the bad data. +.It Sy bad_set_bits +If this field exists, it is an array of +.Pq Ar bad data No & ~( Ns Ar good data ) ; +that is, the bits set in the bad data which are cleared in the good data. +Each element corresponds a byte whose offset is in a range in +.Sy bad_ranges , +and the array is ordered by offset. +Thus, the first element is the first byte in the first +.Sy bad_ranges +range, and the last element is the last byte in the last +.Sy bad_ranges +range. +.It Sy bad_cleared_bits +Like +.Sy bad_set_bits , +but contains +.Pq Ar good data No & ~( Ns Ar bad data ) ; +that is, the bits set in the good data which are cleared in the bad data. +.It Sy bad_set_histogram +If this field exists, it is an array of counters. +Each entry counts bits set in a particular bit of a big-endian uint64 type. +The first entry counts bits +set in the high-order bit of the first byte, the 9th byte, etc, and the last +entry counts bits set of the low-order bit of the 8th byte, the 16th byte, etc. +This information is useful for observing a stuck bit in a parallel data path, +such as IDE or parallel SCSI. +.It Sy bad_cleared_histogram +If this field exists, it is an array of counters. +Each entry counts bit clears in a particular bit of a big-endian uint64 type. +The first entry counts bits +clears of the high-order bit of the first byte, the 9th byte, etc, and the +last entry counts clears of the low-order bit of the 8th byte, the 16th byte, etc. +This information is useful for observing a stuck bit in a parallel data +path, such as IDE or parallel SCSI. +.El +. +.Sh I/O STAGES +The ZFS I/O pipeline is comprised of various stages which are defined below. +The individual stages are used to construct these basic I/O +operations: Read, Write, Free, Claim, and Ioctl. +These stages may be +set on an event to describe the life cycle of a given I/O request. +.Pp +.TS +tab(:); +l l l . +Stage:Bit Mask:Operations +_:_:_ +ZIO_STAGE_OPEN:0x00000001:RWFCI + +ZIO_STAGE_READ_BP_INIT:0x00000002:R---- +ZIO_STAGE_WRITE_BP_INIT:0x00000004:-W--- +ZIO_STAGE_FREE_BP_INIT:0x00000008:--F-- +ZIO_STAGE_ISSUE_ASYNC:0x00000010:RWF-- +ZIO_STAGE_WRITE_COMPRESS:0x00000020:-W--- + +ZIO_STAGE_ENCRYPT:0x00000040:-W--- +ZIO_STAGE_CHECKSUM_GENERATE:0x00000080:-W--- + +ZIO_STAGE_NOP_WRITE:0x00000100:-W--- + +ZIO_STAGE_DDT_READ_START:0x00000200:R---- +ZIO_STAGE_DDT_READ_DONE:0x00000400:R---- +ZIO_STAGE_DDT_WRITE:0x00000800:-W--- +ZIO_STAGE_DDT_FREE:0x00001000:--F-- + +ZIO_STAGE_GANG_ASSEMBLE:0x00002000:RWFC- +ZIO_STAGE_GANG_ISSUE:0x00004000:RWFC- + +ZIO_STAGE_DVA_THROTTLE:0x00008000:-W--- +ZIO_STAGE_DVA_ALLOCATE:0x00010000:-W--- +ZIO_STAGE_DVA_FREE:0x00020000:--F-- +ZIO_STAGE_DVA_CLAIM:0x00040000:---C- + +ZIO_STAGE_READY:0x00080000:RWFCI + +ZIO_STAGE_VDEV_IO_START:0x00100000:RW--I +ZIO_STAGE_VDEV_IO_DONE:0x00200000:RW--I +ZIO_STAGE_VDEV_IO_ASSESS:0x00400000:RW--I + +ZIO_STAGE_CHECKSUM_VERIFY:0x00800000:R---- + +ZIO_STAGE_DONE:0x01000000:RWFCI +.TE +. +.Sh I/O FLAGS +Every I/O request in the pipeline contains a set of flags which describe its +function and are used to govern its behavior. +These flags will be set in an event as a +.Sy zio_flags +payload entry. +.Pp +.TS +tab(:); +l l . +Flag:Bit Mask +_:_ +ZIO_FLAG_DONT_AGGREGATE:0x00000001 +ZIO_FLAG_IO_REPAIR:0x00000002 +ZIO_FLAG_SELF_HEAL:0x00000004 +ZIO_FLAG_RESILVER:0x00000008 +ZIO_FLAG_SCRUB:0x00000010 +ZIO_FLAG_SCAN_THREAD:0x00000020 +ZIO_FLAG_PHYSICAL:0x00000040 + +ZIO_FLAG_CANFAIL:0x00000080 +ZIO_FLAG_SPECULATIVE:0x00000100 +ZIO_FLAG_CONFIG_WRITER:0x00000200 +ZIO_FLAG_DONT_RETRY:0x00000400 +ZIO_FLAG_DONT_CACHE:0x00000800 +ZIO_FLAG_NODATA:0x00001000 +ZIO_FLAG_INDUCE_DAMAGE:0x00002000 + +ZIO_FLAG_IO_ALLOCATING:0x00004000 +ZIO_FLAG_IO_RETRY:0x00008000 +ZIO_FLAG_PROBE:0x00010000 +ZIO_FLAG_TRYHARD:0x00020000 +ZIO_FLAG_OPTIONAL:0x00040000 + +ZIO_FLAG_DONT_QUEUE:0x00080000 +ZIO_FLAG_DONT_PROPAGATE:0x00100000 +ZIO_FLAG_IO_BYPASS:0x00200000 +ZIO_FLAG_IO_REWRITE:0x00400000 +ZIO_FLAG_RAW_COMPRESS:0x00800000 +ZIO_FLAG_RAW_ENCRYPT:0x01000000 + +ZIO_FLAG_GANG_CHILD:0x02000000 +ZIO_FLAG_DDT_CHILD:0x04000000 +ZIO_FLAG_GODFATHER:0x08000000 +ZIO_FLAG_NOPWRITE:0x10000000 +ZIO_FLAG_REEXECUTED:0x20000000 +ZIO_FLAG_DELEGATED:0x40000000 +ZIO_FLAG_FASTWRITE:0x80000000 +.TE +. .Sh SEE ALSO -.Xr zfs-events 5 , -.Xr zfs-module-parameters 5 , +.Xr zfs 4 , .Xr zed 8 , .Xr zpool-wait 8 diff --git a/man/man8/zpool-get.8 b/man/man8/zpool-get.8 index 069082389..55904f169 100644 --- a/man/man8/zpool-get.8 +++ b/man/man8/zpool-get.8 @@ -76,7 +76,7 @@ Property source, either .El .Pp See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for more information on the available pool properties. .Bl -tag -compact -offset Ds -width "-o field" .It Fl H @@ -97,12 +97,12 @@ Display numbers in parsable (exact) values. .Xc Sets the given property on the specified pool. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for more information on what properties can be set and acceptable values. .El . .Sh SEE ALSO -.Xr zpool-features 5 , -.Xr zpool-list 8 , -.Xr zpoolprops 8 +.Xr zpool-features 7 , +.Xr zpoolprops 7 , +.Xr zpool-list 8 diff --git a/man/man8/zpool-import.8 b/man/man8/zpool-import.8 index 1b1f3c5ae..518e3cf1d 100644 --- a/man/man8/zpool-import.8 +++ b/man/man8/zpool-import.8 @@ -201,7 +201,7 @@ for a description of dataset properties and mount options. .It Fl o Ar property Ns = Ns Ar value Sets the specified property on the imported pool. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for more information on the available pool properties. .It Fl R Ar root Sets the @@ -347,7 +347,7 @@ for a description of dataset properties and mount options. .It Fl o Ar property Ns = Ns Ar value Sets the specified property on the imported pool. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for more information on the available pool properties. .It Fl R Ar root Sets the diff --git a/man/man8/zpool-list.8 b/man/man8/zpool-list.8 index 3dec7370c..dd4e13c16 100644 --- a/man/man8/zpool-list.8 +++ b/man/man8/zpool-list.8 @@ -69,7 +69,7 @@ space. .It Fl o Ar property Comma-separated list of properties to display. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for a list of valid properties. The default list is .Sy name , size , allocated , free , checkpoint, expandsize , fragmentation , diff --git a/man/man8/zpool-remove.8 b/man/man8/zpool-remove.8 index 5d866cb50..142918038 100644 --- a/man/man8/zpool-remove.8 +++ b/man/man8/zpool-remove.8 @@ -70,7 +70,7 @@ If an IO error is encountered during the removal process it will be cancelled. The .Sy device_removal feature flag must be enabled to remove a top-level vdev, see -.Xr zpool-features 5 . +.Xr zpool-features 7 . .Pp A mirrored top-level device (log or data) can be removed by specifying the top-level mirror for the same. diff --git a/man/man8/zpool-replace.8 b/man/man8/zpool-replace.8 index eadb56818..2b2875ed4 100644 --- a/man/man8/zpool-replace.8 +++ b/man/man8/zpool-replace.8 @@ -77,7 +77,7 @@ Not all devices can be overridden in this manner. .It Fl o Ar property Ns = Ns Ar value Sets the given pool properties. See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for a list of valid properties that can be set. The only property supported at the moment is .Sy ashift . diff --git a/man/man8/zpool-split.8 b/man/man8/zpool-split.8 index 7a1a13d5d..c3b05c236 100644 --- a/man/man8/zpool-split.8 +++ b/man/man8/zpool-split.8 @@ -98,7 +98,7 @@ flag. Sets the specified property for .Ar newpool . See the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page for more information on the available pool properties. .It Fl R Ar root Set diff --git a/man/man8/zpool-status.8 b/man/man8/zpool-status.8 index da5f95e29..7c825f69d 100644 --- a/man/man8/zpool-status.8 +++ b/man/man8/zpool-status.8 @@ -50,7 +50,7 @@ is specified, then the status of each pool in the system is displayed. For more information on pool and device health, see the .Sx Device Failure and Recovery section of -.Xr zpoolconcepts 8 . +.Xr zpoolconcepts 7 . .Pp If a scrub or resilver is in progress, this command reports the percentage done and the estimated time to completion. diff --git a/man/man8/zpool-sync.8 b/man/man8/zpool-sync.8 index 6d4aa2c29..aa68a5729 100644 --- a/man/man8/zpool-sync.8 +++ b/man/man8/zpool-sync.8 @@ -48,6 +48,6 @@ will sync all pools on the system. Otherwise, it will sync only the specified pools. . .Sh SEE ALSO +.Xr zpoolconcepts 7 , .Xr zpool-export 8 , -.Xr zpool-iostat 8 , -.Xr zpoolconcepts 8 +.Xr zpool-iostat 8 diff --git a/man/man8/zpool-trim.8 b/man/man8/zpool-trim.8 index f709dd854..d9a7b4400 100644 --- a/man/man8/zpool-trim.8 +++ b/man/man8/zpool-trim.8 @@ -86,6 +86,6 @@ Wait until the devices are done being trimmed before returning. .El . .Sh SEE ALSO +.Xr zpoolprops 7 , .Xr zpool-initialize 8 , -.Xr zpool-wait 8 , -.Xr zpoolprops 8 +.Xr zpool-wait 8 diff --git a/man/man8/zpool-upgrade.8 b/man/man8/zpool-upgrade.8 index 0e67e7884..1b13bad89 100644 --- a/man/man8/zpool-upgrade.8 +++ b/man/man8/zpool-upgrade.8 @@ -66,7 +66,7 @@ property). .Xc Displays legacy ZFS versions supported by the this version of ZFS. See -.Xr zpool-features 5 +.Xr zpool-features 7 for a description of feature flags features supported by this version of ZFS. .It Xo .Nm zpool @@ -87,7 +87,7 @@ then no upgrade will take place. Once this is done, the pool will no longer be accessible on systems that do not support feature flags. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool. .Bl -tag -width Ds @@ -103,7 +103,7 @@ supported legacy version number. .El . .Sh SEE ALSO -.Xr zpool-features 5 , -.Xr zpool-history 8 , -.Xr zpoolconcepts 8 , -.Xr zpoolprops 8 +.Xr zpool-features 7 , +.Xr zpoolconcepts 7 , +.Xr zpoolprops 7 , +.Xr zpool-history 8 diff --git a/man/man8/zpool.8 b/man/man8/zpool.8 index dac35eee7..192a8e2ea 100644 --- a/man/man8/zpool.8 +++ b/man/man8/zpool.8 @@ -54,7 +54,7 @@ See for information on managing datasets. .Pp For an overview of creating and managing ZFS storage pools see the -.Xr zpoolconcepts 8 +.Xr zpoolconcepts 7 manual page. . .Sh SUBCOMMANDS @@ -126,7 +126,7 @@ Creates a new pool by splitting all mirrors in an existing pool (which decreases . .Ss Properties Available pool properties listed in the -.Xr zpoolprops 8 +.Xr zpoolprops 7 manual page. .Bl -tag -width Ds .It Xr zpool-list 8 @@ -157,10 +157,8 @@ These events are consumed by the .Xr zed 8 and used to automate administrative tasks such as replacing a failed device with a hot spare. -For more information about the subclasses and event payloads -that can be generated see the -.Xr zfs-events 5 -man page. +That manual page also describes the subclasses and event payloads +that can be generated. .It Xr zpool-history 8 Displays the command history of the specified pool(s) or all pools if no pool is specified. @@ -523,9 +521,10 @@ is not set, it is assumed that the user is allowed to run .Sy Evolving . .Sh SEE ALSO -.Xr zfs-events 5 , -.Xr zfs-module-parameters 5 , -.Xr zpool-features 5 , +.Xr zfs 4 , +.Xr zpool-features 7 , +.Xr zpoolconcepts 7 , +.Xr zpoolprops 7 , .Xr zed 8 , .Xr zfs 8 , .Xr zpool-add 8 , @@ -558,6 +557,4 @@ is not set, it is assumed that the user is allowed to run .Xr zpool-sync 8 , .Xr zpool-trim 8 , .Xr zpool-upgrade 8 , -.Xr zpool-wait 8 , -.Xr zpoolconcepts 8 , -.Xr zpoolprops 8 +.Xr zpool-wait 8 diff --git a/man/man8/zpoolconcepts.8 b/man/man8/zpoolconcepts.8 deleted file mode 100644 index 80a1885fb..000000000 --- a/man/man8/zpoolconcepts.8 +++ /dev/null @@ -1,512 +0,0 @@ -.\" -.\" CDDL HEADER START -.\" -.\" The contents of this file are subject to the terms of the -.\" Common Development and Distribution License (the "License"). -.\" You may not use this file except in compliance with the License. -.\" -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE -.\" or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions -.\" and limitations under the License. -.\" -.\" When distributing Covered Code, include this CDDL HEADER in each -.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. -.\" If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] -.\" -.\" CDDL HEADER END -.\" -.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved. -.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved. -.\" Copyright (c) 2017 Datto Inc. -.\" Copyright (c) 2018 George Melikov. All Rights Reserved. -.\" Copyright 2017 Nexenta Systems, Inc. -.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved. -.\" -.Dd June 2, 2021 -.Dt ZPOOLCONCEPTS 8 -.Os -. -.Sh NAME -.Nm zpoolconcepts -.Nd overview of ZFS storage pools -. -.Sh DESCRIPTION -.Ss Virtual Devices (vdevs) -A "virtual device" describes a single device or a collection of devices -organized according to certain performance and fault characteristics. -The following virtual devices are supported: -.Bl -tag -width "special" -.It Sy disk -A block device, typically located under -.Pa /dev . -ZFS can use individual slices or partitions, though the recommended mode of -operation is to use whole disks. -A disk can be specified by a full path, or it can be a shorthand name -.Po the relative portion of the path under -.Pa /dev -.Pc . -A whole disk can be specified by omitting the slice or partition designation. -For example, -.Pa sda -is equivalent to -.Pa /dev/sda . -When given a whole disk, ZFS automatically labels the disk, if necessary. -.It Sy file -A regular file. -The use of files as a backing store is strongly discouraged. -It is designed primarily for experimental purposes, as the fault tolerance of a -file is only as good as the file system on which it resides. -A file must be specified by a full path. -.It Sy mirror -A mirror of two or more devices. -Data is replicated in an identical fashion across all components of a mirror. -A mirror with -.Em N No disks of size Em X No can hold Em X No bytes and can withstand Em N-1 -devices failing without losing data. -.It Sy raidz , raidz1 , raidz2 , raidz3 -A variation on RAID-5 that allows for better distribution of parity and -eliminates the RAID-5 -.Qq write hole -.Pq in which data and parity become inconsistent after a power loss . -Data and parity is striped across all disks within a raidz group. -.Pp -A raidz group can have single, double, or triple parity, meaning that the -raidz group can sustain one, two, or three failures, respectively, without -losing any data. -The -.Sy raidz1 -vdev type specifies a single-parity raidz group; the -.Sy raidz2 -vdev type specifies a double-parity raidz group; and the -.Sy raidz3 -vdev type specifies a triple-parity raidz group. -The -.Sy raidz -vdev type is an alias for -.Sy raidz1 . -.Pp -A raidz group with -.Em N No disks of size Em X No with Em P No parity disks can hold approximately -.Em (N-P)*X No bytes and can withstand Em P No devices failing without losing data. -The minimum number of devices in a raidz group is one more than the number of -parity disks. -The recommended number is between 3 and 9 to help increase performance. -.It Sy draid , draid1 , draid2 , draid3 -A variant of raidz that provides integrated distributed hot spares which -allows for faster resilvering while retaining the benefits of raidz. -A dRAID vdev is constructed from multiple internal raidz groups, each with -.Em D No data devices and Em P No parity devices. -These groups are distributed over all of the children in order to fully -utilize the available disk performance. -.Pp -Unlike raidz, dRAID uses a fixed stripe width (padding as necessary with -zeros) to allow fully sequential resilvering. -This fixed stripe width significantly effects both usable capacity and IOPS. -For example, with the default -.Em D=8 No and Em 4kB No disk sectors the minimum allocation size is Em 32kB . -If using compression, this relatively large allocation size can reduce the -effective compression ratio. -When using ZFS volumes and dRAID, the default of the -.Sy volblocksize -property is increased to account for the allocation size. -If a dRAID pool will hold a significant amount of small blocks, it is -recommended to also add a mirrored -.Sy special -vdev to store those blocks. -.Pp -In regards to I/O, performance is similar to raidz since for any read all -.Em D No data disks must be accessed. -Delivered random IOPS can be reasonably approximated as -.Sy floor((N-S)/(D+P))*single_drive_IOPS . -.Pp -Like raidzm a dRAID can have single-, double-, or triple-parity. -The -.Sy draid1 , -.Sy draid2 , -and -.Sy draid3 -types can be used to specify the parity level. -The -.Sy draid -vdev type is an alias for -.Sy draid1 . -.Pp -A dRAID with -.Em N No disks of size Em X , D No data disks per redundancy group, Em P -.No parity level, and Em S No distributed hot spares can hold approximately -.Em (N-S)*(D/(D+P))*X No bytes and can withstand Em P -devices failing without losing data. -.It Sy draid Ns Oo Ar parity Oc Ns Oo Sy \&: Ns Ar data Ns Sy d Oc Ns Oo Sy \&: Ns Ar children Ns Sy c Oc Ns Oo Sy \&: Ns Ar spares Ns Sy s Oc -A non-default dRAID configuration can be specified by appending one or more -of the following optional arguments to the -.Sy draid -keyword: -.Bl -tag -compact -width "children" -.It Ar parity -The parity level (1-3). -.It Ar data -The number of data devices per redundancy group. -In general, a smaller value of -.Em D No will increase IOPS, improve the compression ratio, -and speed up resilvering at the expense of total usable capacity. -Defaults to -.Em 8 , No unless Em N-P-S No is less than Em 8 . -.It Ar children -The expected number of children. -Useful as a cross-check when listing a large number of devices. -An error is returned when the provided number of children differs. -.It Ar spares -The number of distributed hot spares. -Defaults to zero. -.El -.It Sy spare -A pseudo-vdev which keeps track of available hot spares for a pool. -For more information, see the -.Sx Hot Spares -section. -.It Sy log -A separate intent log device. -If more than one log device is specified, then writes are load-balanced between -devices. -Log devices can be mirrored. -However, raidz vdev types are not supported for the intent log. -For more information, see the -.Sx Intent Log -section. -.It Sy dedup -A device dedicated solely for deduplication tables. -The redundancy of this device should match the redundancy of the other normal -devices in the pool. -If more than one dedup device is specified, then -allocations are load-balanced between those devices. -.It Sy special -A device dedicated solely for allocating various kinds of internal metadata, -and optionally small file blocks. -The redundancy of this device should match the redundancy of the other normal -devices in the pool. -If more than one special device is specified, then -allocations are load-balanced between those devices. -.Pp -For more information on special allocations, see the -.Sx Special Allocation Class -section. -.It Sy cache -A device used to cache storage pool data. -A cache device cannot be configured as a mirror or raidz group. -For more information, see the -.Sx Cache Devices -section. -.El -.Pp -Virtual devices cannot be nested, so a mirror or raidz virtual device can only -contain files or disks. -Mirrors of mirrors -.Pq or other combinations -are not allowed. -.Pp -A pool can have any number of virtual devices at the top of the configuration -.Po known as -.Qq root vdevs -.Pc . -Data is dynamically distributed across all top-level devices to balance data -among devices. -As new virtual devices are added, ZFS automatically places data on the newly -available devices. -.Pp -Virtual devices are specified one at a time on the command line, -separated by whitespace. -Keywords like -.Sy mirror No and Sy raidz -are used to distinguish where a group ends and another begins. -For example, the following creates a pool with two root vdevs, -each a mirror of two disks: -.Dl # Nm zpool Cm create Ar mypool Sy mirror Ar sda sdb Sy mirror Ar sdc sdd -. -.Ss Device Failure and Recovery -ZFS supports a rich set of mechanisms for handling device failure and data -corruption. -All metadata and data is checksummed, and ZFS automatically repairs bad data -from a good copy when corruption is detected. -.Pp -In order to take advantage of these features, a pool must make use of some form -of redundancy, using either mirrored or raidz groups. -While ZFS supports running in a non-redundant configuration, where each root -vdev is simply a disk or file, this is strongly discouraged. -A single case of bit corruption can render some or all of your data unavailable. -.Pp -A pool's health status is described by one of three states: -.Sy online , degraded , No or Sy faulted . -An online pool has all devices operating normally. -A degraded pool is one in which one or more devices have failed, but the data is -still available due to a redundant configuration. -A faulted pool has corrupted metadata, or one or more faulted devices, and -insufficient replicas to continue functioning. -.Pp -The health of the top-level vdev, such as a mirror or raidz device, -is potentially impacted by the state of its associated vdevs, -or component devices. -A top-level vdev or component device is in one of the following states: -.Bl -tag -width "DEGRADED" -.It Sy DEGRADED -One or more top-level vdevs is in the degraded state because one or more -component devices are offline. -Sufficient replicas exist to continue functioning. -.Pp -One or more component devices is in the degraded or faulted state, but -sufficient replicas exist to continue functioning. -The underlying conditions are as follows: -.Bl -bullet -compact -.It -The number of checksum errors exceeds acceptable levels and the device is -degraded as an indication that something may be wrong. -ZFS continues to use the device as necessary. -.It -The number of I/O errors exceeds acceptable levels. -The device could not be marked as faulted because there are insufficient -replicas to continue functioning. -.El -.It Sy FAULTED -One or more top-level vdevs is in the faulted state because one or more -component devices are offline. -Insufficient replicas exist to continue functioning. -.Pp -One or more component devices is in the faulted state, and insufficient -replicas exist to continue functioning. -The underlying conditions are as follows: -.Bl -bullet -compact -.It -The device could be opened, but the contents did not match expected values. -.It -The number of I/O errors exceeds acceptable levels and the device is faulted to -prevent further use of the device. -.El -.It Sy OFFLINE -The device was explicitly taken offline by the -.Nm zpool Cm offline -command. -.It Sy ONLINE -The device is online and functioning. -.It Sy REMOVED -The device was physically removed while the system was running. -Device removal detection is hardware-dependent and may not be supported on all -platforms. -.It Sy UNAVAIL -The device could not be opened. -If a pool is imported when a device was unavailable, then the device will be -identified by a unique identifier instead of its path since the path was never -correct in the first place. -.El -.Pp -Checksum errors represent events where a disk returned data that was expected -to be correct, but was not. -In other words, these are instances of silent data corruption. -The checksum errors are reported in -.Nm zpool Cm status -and -.Nm zpool Cm events . -When a block is stored redundantly, a damaged block may be reconstructed -(e.g. from raidz parity or a mirrored copy). -In this case, ZFS reports the checksum error against the disks that contained -damaged data. -If a block is unable to be reconstructed (e.g. due to 3 disks being damaged -in a raidz2 group), it is not possible to determine which disks were silently -corrupted. -In this case, checksum errors are reported for all disks on which the block -is stored. -.Pp -If a device is removed and later re-attached to the system, -ZFS attempts online the device automatically. -Device attachment detection is hardware-dependent -and might not be supported on all platforms. -. -.Ss Hot Spares -ZFS allows devices to be associated with pools as -.Qq hot spares . -These devices are not actively used in the pool, but when an active device -fails, it is automatically replaced by a hot spare. -To create a pool with hot spares, specify a -.Sy spare -vdev with any number of devices. -For example, -.Dl # Nm zpool Cm create Ar pool Sy mirror Ar sda sdb Sy spare Ar sdc sdd -.Pp -Spares can be shared across multiple pools, and can be added with the -.Nm zpool Cm add -command and removed with the -.Nm zpool Cm remove -command. -Once a spare replacement is initiated, a new -.Sy spare -vdev is created within the configuration that will remain there until the -original device is replaced. -At this point, the hot spare becomes available again if another device fails. -.Pp -If a pool has a shared spare that is currently being used, the pool can not be -exported since other pools may use this shared spare, which may lead to -potential data corruption. -.Pp -Shared spares add some risk. -If the pools are imported on different hosts, -and both pools suffer a device failure at the same time, -both could attempt to use the spare at the same time. -This may not be detected, resulting in data corruption. -.Pp -An in-progress spare replacement can be cancelled by detaching the hot spare. -If the original faulted device is detached, then the hot spare assumes its -place in the configuration, and is removed from the spare list of all active -pools. -.Pp -The -.Sy draid -vdev type provides distributed hot spares. -These hot spares are named after the dRAID vdev they're a part of -.Po Sy draid1 Ns - Ns Ar 2 Ns - Ns Ar 3 No specifies spare Ar 3 No of vdev Ar 2 , -.No which is a single parity dRAID Pc -and may only be used by that dRAID vdev. -Otherwise, they behave the same as normal hot spares. -.Pp -Spares cannot replace log devices. -. -.Ss Intent Log -The ZFS Intent Log (ZIL) satisfies POSIX requirements for synchronous -transactions. -For instance, databases often require their transactions to be on stable storage -devices when returning from a system call. -NFS and other applications can also use -.Xr fsync 2 -to ensure data stability. -By default, the intent log is allocated from blocks within the main pool. -However, it might be possible to get better performance using separate intent -log devices such as NVRAM or a dedicated disk. -For example: -.Dl # Nm zpool Cm create Ar pool sda sdb Sy log Ar sdc -.Pp -Multiple log devices can also be specified, and they can be mirrored. -See the -.Sx EXAMPLES -section for an example of mirroring multiple log devices. -.Pp -Log devices can be added, replaced, attached, detached and removed. -In addition, log devices are imported and exported as part of the pool -that contains them. -Mirrored devices can be removed by specifying the top-level mirror vdev. -. -.Ss Cache Devices -Devices can be added to a storage pool as -.Qq cache devices . -These devices provide an additional layer of caching between main memory and -disk. -For read-heavy workloads, where the working set size is much larger than what -can be cached in main memory, using cache devices allows much more of this -working set to be served from low latency media. -Using cache devices provides the greatest performance improvement for random -read-workloads of mostly static content. -.Pp -To create a pool with cache devices, specify a -.Sy cache -vdev with any number of devices. -For example: -.Dl # Nm zpool Cm create Ar pool sda sdb Sy cache Ar sdc sdd -.Pp -Cache devices cannot be mirrored or part of a raidz configuration. -If a read error is encountered on a cache device, that read I/O is reissued to -the original storage pool device, which might be part of a mirrored or raidz -configuration. -.Pp -The content of the cache devices is persistent across reboots and restored -asynchronously when importing the pool in L2ARC (persistent L2ARC). -This can be disabled by setting -.Sy l2arc_rebuild_enabled Ns = Ns Sy 0 . -For cache devices smaller than -.Em 1GB , -we do not write the metadata structures -required for rebuilding the L2ARC in order not to waste space. -This can be changed with -.Sy l2arc_rebuild_blocks_min_l2size . -The cache device header -.Pq Em 512B -is updated even if no metadata structures are written. -Setting -.Sy l2arc_headroom Ns = Ns Sy 0 -will result in scanning the full-length ARC lists for cacheable content to be -written in L2ARC (persistent ARC). -If a cache device is added with -.Nm zpool Cm add -its label and header will be overwritten and its contents are not going to be -restored in L2ARC, even if the device was previously part of the pool. -If a cache device is onlined with -.Nm zpool Cm online -its contents will be restored in L2ARC. -This is useful in case of memory pressure -where the contents of the cache device are not fully restored in L2ARC. -The user can off- and online the cache device when there is less memory pressure -in order to fully restore its contents to L2ARC. -. -.Ss Pool checkpoint -Before starting critical procedures that include destructive actions -.Pq like Nm zfs Cm destroy , -an administrator can checkpoint the pool's state and in the case of a -mistake or failure, rewind the entire pool back to the checkpoint. -Otherwise, the checkpoint can be discarded when the procedure has completed -successfully. -.Pp -A pool checkpoint can be thought of as a pool-wide snapshot and should be used -with care as it contains every part of the pool's state, from properties to vdev -configuration. -Thus, certain operations are not allowed while a pool has a checkpoint. -Specifically, vdev removal/attach/detach, mirror splitting, and -changing the pool's GUID. -Adding a new vdev is supported, but in the case of a rewind it will have to be -added again. -Finally, users of this feature should keep in mind that scrubs in a pool that -has a checkpoint do not repair checkpointed data. -.Pp -To create a checkpoint for a pool: -.Dl # Nm zpool Cm checkpoint Ar pool -.Pp -To later rewind to its checkpointed state, you need to first export it and -then rewind it during import: -.Dl # Nm zpool Cm export Ar pool -.Dl # Nm zpool Cm import Fl -rewind-to-checkpoint Ar pool -.Pp -To discard the checkpoint from a pool: -.Dl # Nm zpool Cm checkpoint Fl d Ar pool -.Pp -Dataset reservations (controlled by the -.Sy reservation No and Sy refreservation -properties) may be unenforceable while a checkpoint exists, because the -checkpoint is allowed to consume the dataset's reservation. -Finally, data that is part of the checkpoint but has been freed in the -current state of the pool won't be scanned during a scrub. -. -.Ss Special Allocation Class -Allocations in the special class are dedicated to specific block types. -By default this includes all metadata, the indirect blocks of user data, and -any deduplication tables. -The class can also be provisioned to accept small file blocks. -.Pp -A pool must always have at least one normal -.Pq non- Ns Sy dedup Ns /- Ns Sy special -vdev before -other devices can be assigned to the special class. -If the -.Sy special -class becomes full, then allocations intended for it -will spill back into the normal class. -.Pp -Deduplication tables can be excluded from the special class by unsetting the -.Sy zfs_ddt_data_is_special -ZFS module parameter. -.Pp -Inclusion of small file blocks in the special class is opt-in. -Each dataset can control the size of small file blocks allowed -in the special class by setting the -.Sy special_small_blocks -property to nonzero. -See -.Xr zfsprops 8 -for more info on this property. diff --git a/man/man8/zpoolprops.8 b/man/man8/zpoolprops.8 deleted file mode 100644 index 050a05072..000000000 --- a/man/man8/zpoolprops.8 +++ /dev/null @@ -1,412 +0,0 @@ -.\" -.\" CDDL HEADER START -.\" -.\" The contents of this file are subject to the terms of the -.\" Common Development and Distribution License (the "License"). -.\" You may not use this file except in compliance with the License. -.\" -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE -.\" or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions -.\" and limitations under the License. -.\" -.\" When distributing Covered Code, include this CDDL HEADER in each -.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. -.\" If applicable, add the following below this CDDL HEADER, with the -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] -.\" -.\" CDDL HEADER END -.\" -.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. -.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved. -.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved. -.\" Copyright (c) 2017 Datto Inc. -.\" Copyright (c) 2018 George Melikov. All Rights Reserved. -.\" Copyright 2017 Nexenta Systems, Inc. -.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved. -.\" Copyright (c) 2021, Colm Buckley <[email protected]> -.\" -.Dd May 27, 2021 -.Dt ZPOOLPROPS 8 -.Os -. -.Sh NAME -.Nm zpoolprops -.Nd properties of ZFS storage pools -. -.Sh 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. -.Pp -The following are read-only properties: -.Bl -tag -width "unsupported@guid" -.It Cm allocated -Amount of storage used within the pool. -See -.Sy fragmentation -and -.Sy free -for more information. -.It Sy capacity -Percentage of pool space used. -This property can also be referred to by its shortened column name, -.Sy cap . -.It Sy 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 -.Sy autoexpand=on -or using -.Nm zpool Cm online Fl e . -.It Sy fragmentation -The amount of fragmentation in the pool. -As the amount of space -.Sy allocated -increases, it becomes more difficult to locate -.Sy free -space. -This may result in lower write performance compared to pools with more -unfragmented free space. -.It Sy free -The amount of free space available in the pool. -By contrast, the -.Xr zfs 8 -.Sy available -property describes how much new data can be written to ZFS filesystems/volumes. -The zpool -.Sy free -property is not generally useful for this purpose, and can be substantially more than the zfs -.Sy available -space. -This discrepancy is due to several factors, including raidz parity; -zfs reservation, quota, refreservation, and refquota properties; and space set aside by -.Sy spa_slop_shift -(see -.Xr zfs-module-parameters 5 -for more information). -.It Sy freeing -After a file system or snapshot is destroyed, the space it was using is -returned to the pool asynchronously. -.Sy freeing -is the amount of space remaining to be reclaimed. -Over time -.Sy freeing -will decrease while -.Sy free -increases. -.It Sy health -The current health of the pool. -Health can be one of -.Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL . -.It Sy guid -A unique identifier for the pool. -.It Sy load_guid -A unique identifier for the pool. -Unlike the -.Sy guid -property, this identifier is generated every time we load the pool (i.e. does -not persist across imports/exports) and never changes while the pool is loaded -(even if a -.Sy reguid -operation takes place). -.It Sy size -Total size of the storage pool. -.It Sy unsupported@ Ns Em guid -Information about unsupported features that are enabled on the pool. -See -.Xr zpool-features 5 -for details. -.El -.Pp -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 characteristics -of the data being written. -In addition, ZFS reserves some space for internal accounting that the -.Xr zfs 8 -command takes into account, but the -.Nm -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. -.Pp -The following property can be set at creation time and import time: -.Bl -tag -width Ds -.It Sy altroot -Alternate root directory. -If set, this directory is prepended to any mount points within the pool. -This can be used when examining an unknown pool where the mount points cannot be -trusted, or in an alternate boot environment, where the typical paths are not -valid. -.Sy altroot -is not a persistent property. -It is valid only while the system is up. -Setting -.Sy altroot -defaults to using -.Sy cachefile Ns = Ns Sy none , -though this may be overridden using an explicit setting. -.El -.Pp -The following property can be set only at import time: -.Bl -tag -width Ds -.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off -If set to -.Sy on , -the pool will be imported in read-only mode. -This property can also be referred to by its shortened column name, -.Sy rdonly . -.El -.Pp -The following properties can be set at creation time and import time, and later -changed with the -.Nm zpool Cm set -command: -.Bl -tag -width Ds -.It Sy ashift Ns = Ns Sy ashift -Pool sector size exponent, to the power of -.Sy 2 -(internally referred to as -.Sy ashift ) . -Values from 9 to 16, inclusive, are valid; also, the -value 0 (the default) means to auto-detect using the kernel's block -layer and a ZFS internal exception list. -I/O operations will be aligned to the specified size boundaries. -Additionally, the minimum (disk) -write size will be set to the specified size, so this represents a -space vs. performance trade-off. -For optimal performance, the pool sector size should be greater than -or equal to the sector size of the underlying 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 -.Sy ashift Ns = Ns Sy 12 -(which is -.Sy 1<<12 No = Sy 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. -.It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off -Controls automatic pool expansion when the underlying LUN is grown. -If set to -.Sy 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 -.Sy off . -This property can also be referred to by its shortened column name, -.Sy expand . -.It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off -Controls automatic device replacement. -If set to -.Sy off , -device replacement must be initiated by the administrator by using the -.Nm zpool Cm replace -command. -If set to -.Sy 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 default behavior is -.Sy off . -This property can also be referred to by its shortened column name, -.Sy 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 -.Xr vdev_id 8 -manual page for more details. -Autoreplace and autoonline require the ZFS Event Daemon be configured and -running. -See the -.Xr zed 8 -manual page for more details. -.It Sy autotrim Ns = Ns Sy on Ns | Ns Sy off -When set to -.Sy 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 -supports hole-punching, to reclaim unused blocks. -The default value for this property is -.Sy off . -.Pp -Automatic TRIM does not immediately reclaim blocks after a free. -Instead, it will optimistically delay allowing smaller ranges to be aggregated -into a few larger ones. -These can then be issued more efficiently to the storage. -TRIM on L2ARC devices is enabled by setting -.Sy l2arc_trim_ahead > 0 . -.Pp -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 handles these commands. -For lower-end devices it is often possible to achieve most of the benefits -of automatic trimming by running an on-demand (manual) TRIM periodically -using the -.Nm zpool Cm trim -command. -.It Sy bootfs Ns = Ns Sy (unset) Ns | Ns Ar pool Ns Op / Ns Ar 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. -.It Sy cachefile Ns = Ns Ar path Ns | Ns Sy 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 install and clustering, need to cache this -information in a different location so that pools are not automatically -imported. -Setting this property caches the pool configuration in a different location that -can later be imported with -.Nm zpool Cm import Fl c . -Setting it to the value -.Sy none -creates a temporary pool that is never cached, and the -.Qq -.Pq empty string -uses the default location. -.Pp -Multiple pools can share the same cache file. -Because the kernel 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 -.Sy cachefile -is exported or destroyed, the file will be empty. -.It Sy comment Ns = Ns Ar text -A text string consisting of 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 -property. -.It Sy compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns … -Specifies that the pool maintain compatibility with specific feature sets. -When set to -.Sy off -(or unset) compatibility is disabled (all features may be enabled); when set to -.Sy legacy Ns -no features may be enabled. -When set to a comma-separated list of filenames -(each filename may either be an absolute path, or relative to -.Pa /etc/zfs/compatibility.d -or -.Pa /usr/share/zfs/compatibility.d ) -the lists of requested features are read from those files, separated by -whitespace and/or commas. -Only features present in all files may be enabled. -.Pp -See -.Xr zpool-features 5 , -.Xr zpool-create 8 -and -.Xr zpool-upgrade 8 -for more information on the operation of compatibility feature sets. -.It Sy dedupditto Ns = Ns Ar number -This property is deprecated and no longer has any effect. -.It Sy delegation Ns = Ns Sy on Ns | Ns Sy off -Controls whether a non-privileged user is granted access based on the dataset -permissions defined on the dataset. -See -.Xr zfs 8 -for more information on ZFS delegated administration. -.It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy 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: -.Bl -tag -width "continue" -.It Sy wait -Blocks all I/O access until the device connectivity is recovered and the errors -are cleared. -This is the default behavior. -.It Sy continue -Returns -.Er 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. -.It Sy panic -Prints out a message to the console and generates a system crash dump. -.El -.It Sy feature@ Ns Ar feature_name Ns = Ns Sy enabled -The value of this property is the current state of -.Ar feature_name . -The only valid value when setting this property is -.Sy enabled -which moves -.Ar feature_name -to the enabled state. -See -.Xr zpool-features 5 -for details on feature states. -.It Sy listsnapshots Ns = Ns Sy on Ns | Ns Sy off -Controls whether information about snapshots associated with this pool is -output when -.Nm zfs Cm list -is run without the -.Fl t -option. -The default value is -.Sy off . -This property can also be referred to by its shortened name, -.Sy listsnaps . -.It Sy multihost Ns = Ns Sy on Ns | Ns Sy off -Controls whether a pool activity check should be performed during -.Nm zpool Cm import . -When a pool is determined to be active it cannot be imported, even with the -.Fl f -option. -This property is intended to be used in failover configurations -where multiple hosts have access to a pool on shared storage. -.Pp -Multihost provides protection on import only. -It does not protect against an -individual device being used in multiple pools, regardless of the type of vdev. -See the discussion under -.Nm zpool Cm create . -.Pp -When this property is on, periodic writes to storage occur to show the pool is -in use. -See -.Sy zfs_multihost_interval -in the -.Xr zfs-module-parameters 5 -manual page. -In order to enable this property each host must set a unique hostid. -See -.Xr genhostid 1 -.Xr zgenhostid 8 -.Xr spl-module-parameters 5 -for additional details. -The default value is -.Sy off . -.It Sy version Ns = Ns Ar version -The current on-disk version of the pool. -This can be increased, but never decreased. -The preferred method of updating pools is with the -.Nm zpool Cm 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. -.El |