diff --git a/man/man1/zvol_wait.1 b/man/man1/zvol_wait.1 index 839e1f144752..0fb47ce73481 100644 --- a/man/man1/zvol_wait.1 +++ b/man/man1/zvol_wait.1 @@ -1,21 +1,32 @@ -.Dd July 5, 2019 -.Dt ZVOL_WAIT 1 SMM +.\" +.\" This file and its contents are supplied under the terms of the +.\" Common Development and Distribution License ("CDDL"), version 1.0. +.\" You may only use this file in accordance with the terms of version +.\" 1.0 of the CDDL. +.\" +.\" A full copy of the text of the CDDL should have accompanied this +.\" source. A copy of the CDDL is also available via the Internet at +.\" http://www.illumos.org/license/CDDL. +.\" +.Dd May 27, 2021 +.Dt ZVOL_WAIT 1 .Os +. .Sh NAME .Nm zvol_wait -.Nd Wait for ZFS volume links in -.Em /dev -to be created. +.Nd wait for ZFS volume links to appear in /dev .Sh SYNOPSIS .Nm +. .Sh DESCRIPTION -When a ZFS pool is imported, ZFS will register each ZFS volume -(zvol) as a disk device with the system. As the disks are registered, -.Xr \fBudev 7\fR -will asynchronously create symlinks under -.Em /dev/zvol -using the zvol's name. +When a ZFS pool is imported, the volumes within it will appear as block devices. +As they're registered, +.Xr udev 7 +asynchronously creates symlinks under +.Pa /dev/zvol +using the volumes' names. .Nm -will wait for all those symlinks to be created before returning. +will wait for all those symlinks to be created before exiting. +. .Sh SEE ALSO -.Xr \fBudev 7\fR +.Xr udev 7 diff --git a/man/man8/mount.zfs.8 b/man/man8/mount.zfs.8 index dd04b3109bfc..5d36dbdb1692 100644 --- a/man/man8/mount.zfs.8 +++ b/man/man8/mount.zfs.8 @@ -1,92 +1,92 @@ .\" .\" 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 2013 Darik Horn . All rights reserved. .\" .Dd May 24, 2021 .Dt MOUNT.ZFS 8 .Os . .Sh NAME .Nm mount.zfs -.Nd mount a ZFS filesystem +.Nd mount ZFS filesystem .Sh SYNOPSIS .Nm .Op Fl sfnvh .Op Fl o Ar options .Ar dataset .Ar mountpoint . .Sh DESCRIPTION The .Nm helper is used by .Xr mount 8 to mount filesystem snapshots and .Sy mountpoint= Ns Ar legacy ZFS filesystems, as well as by .Xr zfs 8 when the -.Ev Em $ZFS_MOUNT_HELPER +.Sy ZFS_MOUNT_HELPER environment variable is not set. Users should should invoke either .Xr mount 8 or .Xr zfs 8 in most cases. .Pp .Ar options are handled according to the .Em Temporary Mount Point Properties section in .Xr zfsprops 8 , except for those described below. .Pp If .Pa /etc/mtab is a regular file and .Fl n was not specified, it will be updated via libmount. . .Sh OPTIONS .Bl -tag -width "-o xa" .It Fl s Ignore unknown (sloppy) mount options. .It Fl f Do everything except actually executing the system call. .It Fl n Never update .Pa /etc/mtab . .It Fl v Print resolved mount options and parser state. .It Fl h Print the usage message. .It Fl o Ar zfsutil This private flag indicates that .Xr mount 8 is being called by the .Xr zfs 8 command. .El . .Sh SEE ALSO .Xr fstab 5 , .Xr mount 8 , .Xr zfs-mount 8 diff --git a/man/man8/zdb.8 b/man/man8/zdb.8 index 36fe6de547b3..a8a944219071 100644 --- a/man/man8/zdb.8 +++ b/man/man8/zdb.8 @@ -1,494 +1,506 @@ .\" .\" This file and its contents are supplied under the terms of the .\" Common Development and Distribution License ("CDDL"), version 1.0. .\" You may only use this file in accordance with the terms of version .\" 1.0 of the CDDL. .\" .\" A full copy of the text of the CDDL should have accompanied this .\" source. A copy of the CDDL is also available via the Internet at .\" http://www.illumos.org/license/CDDL. .\" -.\" .\" Copyright 2012, Richard Lowe. .\" Copyright (c) 2012, 2019 by Delphix. All rights reserved. .\" Copyright 2017 Nexenta Systems, Inc. .\" Copyright (c) 2017 Lawrence Livermore National Security, LLC. .\" Copyright (c) 2017 Intel Corporation. .\" .Dd October 7, 2020 -.Dt ZDB 8 SMM +.Dt ZDB 8 .Os +. .Sh NAME .Nm zdb -.Nd display zpool debugging and consistency information +.Nd display ZFS storage pool debugging and consistency information .Sh SYNOPSIS .Nm .Op Fl AbcdDFGhikLMPsvXYy -.Op Fl e Oo Fl V Oc Op Fl p Ar path ... +.Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … .Op Fl I Ar inflight I/Os -.Oo Fl o Ar var Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar var Ns = Ns Ar value Oc Ns … .Op Fl t Ar txg .Op Fl U Ar cache .Op Fl x Ar dumpdir -.Op Ar poolname[/dataset | objset ID] -.Op Ar object | range ... +.Op Ar poolname Ns Op / Ns Ar dataset | objset ID +.Op Ar object Ns | Ns Ar range Ns … .Nm .Op Fl AdiPv -.Op Fl e Oo Fl V Oc Op Fl p Ar path ... +.Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … .Op Fl U Ar cache -.Ar poolname[/dataset | objset ID] Op Ar object | range ... +.Ar poolname Ns Op Ar / Ns Ar dataset | objset ID +.Op Ar object Ns | Ns Ar range Ns … .Nm .Fl C .Op Fl A .Op Fl U Ar cache .Nm .Fl E .Op Fl A -.Ar word0 Ns \&: Ns Ar word1 Ns :...: Ns Ar word15 +.Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15 .Nm .Fl l .Op Fl Aqu .Ar device .Nm .Fl m .Op Fl AFLPXY -.Op Fl e Oo Fl V Oc Op Fl p Ar path ... +.Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … .Op Fl t Ar txg .Op Fl U Ar cache -.Ar poolname Op Ar vdev Op Ar metaslab ... +.Ar poolname Op Ar vdev Oo Ar metaslab Oc Ns … .Nm .Fl O .Ar dataset path .Nm .Fl r .Ar dataset path destination .Nm .Fl R .Op Fl A -.Op Fl e Oo Fl V Oc Op Fl p Ar path ... +.Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … .Op Fl U Ar cache -.Ar poolname vdev Ns \&: Ns Ar offset Ns \&: Ns Ar [/] Ns Op : Ns Ar flags +.Ar poolname vdev : Ns Ar offset : Ns Oo Ar lsize Ns / Oc Ns Ar psize Ns Op : Ns Ar flags .Nm .Fl S .Op Fl AP -.Op Fl e Oo Fl V Oc Op Fl p Ar path ... +.Op Fl e Oo Fl V Oc Oo Fl p Ar path Oc Ns … .Op Fl U Ar cache .Ar poolname +. .Sh DESCRIPTION The .Nm utility displays information about a ZFS pool useful for debugging and performs some amount of consistency checking. It is a not a general purpose tool and options .Pq and facilities may change. This is not a .Xr fsck 8 utility. .Pp The output of this command in general reflects the on-disk structure of a ZFS pool, and is inherently unstable. The precise output of most invocations is not documented, a knowledge of ZFS internals is assumed. .Pp If the .Ar dataset argument does not contain any .Qq Sy / or .Qq Sy @ characters, it is interpreted as a pool name. The root dataset can be specified as -.Ar pool Ns / -.Pq pool name followed by a slash . +.Qq Ar pool Ns / . .Pp When operating on an imported and active pool it is possible, though unlikely, that zdb may interpret inconsistent pool data and behave erratically. +. .Sh OPTIONS Display options: .Bl -tag -width Ds .It Fl b Display statistics regarding the number, size .Pq logical, physical and allocated and deduplication of blocks. .It Fl c Verify the checksum of all metadata blocks while printing block statistics .Po see .Fl b .Pc . .Pp If specified multiple times, verify the checksums of all blocks. .It Fl C Display information about the configuration. If specified with no other options, instead display information about the cache file .Pq Pa /etc/zfs/zpool.cache . To specify the cache file to display, see .Fl U . .Pp If specified multiple times, and a pool name is also specified display both the cached configuration and the on-disk configuration. If specified multiple times with .Fl e also display the configuration that would be used were the pool to be imported. .It Fl d Display information about datasets. Specified once, displays basic dataset information: ID, create transaction, size, and object count. .Pp If specified multiple times provides greater and greater verbosity. .Pp If object IDs or object ID ranges are specified, display information about those specific objects or ranges only. .Pp An object ID range is specified in terms of a colon-separated tuple of the form -.Ao start Ac Ns : Ns Ao end Ac Ns Op Ns : Ns Ao flags Ac Ns . +.Ao start Ac : Ns Ao end Ac Ns Op : Ns Ao flags Ac . The fields .Ar start and .Ar end are integer object identifiers that denote the upper and lower bounds -of the range. An +of the range. +An .Ar end -value of -1 specifies a range with no upper bound. The +value of -1 specifies a range with no upper bound. +The .Ar flags field optionally specifies a set of flags, described below, that control -which object types are dumped. By default, all object types are dumped. A minus -sign +which object types are dumped. +By default, all object types are dumped. +A minus sign .Pq - negates the effect of the flag that follows it and has no effect unless preceded by the .Ar A -flag. For example, the range 0:-1:A-d will dump all object types except -for directories. +flag. +For example, the range 0:-1:A-d will dump all object types except for directories. .Pp -.Bl -tag -compact +.Bl -tag -compact -width Ds .It Sy A Dump all objects (this is the default) .It Sy d Dump ZFS directory objects .It Sy f Dump ZFS plain file objects .It Sy m Dump SPA space map objects .It Sy z Dump ZAP objects .It Sy - Negate the effect of next flag .El .It Fl D Display deduplication statistics, including the deduplication ratio .Pq Sy dedup , compression ratio .Pq Sy compress , inflation due to the zfs copies property .Pq Sy copies , and an overall effective ratio .Pq Sy dedup No * Sy compress No / Sy copies . .It Fl DD Display a histogram of deduplication statistics, showing the allocated .Pq physically present on disk and referenced .Pq logically referenced in the pool block counts and sizes by reference count. .It Fl DDD Display the statistics independently for each deduplication table. .It Fl DDDD Dump the contents of the deduplication tables describing duplicate blocks. .It Fl DDDDD Also dump the contents of the deduplication tables describing unique blocks. -.It Fl E Ar word0 Ns \&: Ns Ar word1 Ns :...: Ns Ar word15 +.It Fl E Ar word0 : Ns Ar word1 Ns :…: Ns Ar word15 Decode and display block from an embedded block pointer specified by the .Ar word arguments. .It Fl h Display pool history similar to .Nm zpool Cm history , but include internal changes, transaction, and dataset information. .It Fl i Display information about intent log .Pq ZIL entries relating to each dataset. If specified multiple times, display counts of each intent log transaction type. .It Fl k Examine the checkpointed state of the pool. Note, the on disk format of the pool is not reverted to the checkpointed state. .It Fl l Ar device Read the vdev labels and L2ARC header from the specified device. .Nm Fl l will return 0 if valid label was found, 1 if error occurred, and 2 if no valid -labels were found. The presence of L2ARC header is indicated by a specific -sequence (L2ARC_DEV_HDR_MAGIC). If there is an accounting error in the size -or the number of L2ARC log blocks +labels were found. +The presence of L2ARC header is indicated by a specific +sequence (L2ARC_DEV_HDR_MAGIC). +If there is an accounting error in the size or the number of L2ARC log blocks .Nm Fl l -will return 1. Each unique configuration is displayed only -once. +will return 1. +Each unique configuration is displayed only once. .It Fl ll Ar device -In addition display label space usage stats. If a valid L2ARC header was found +In addition display label space usage stats. +If a valid L2ARC header was found also display the properties of log blocks used for restoring L2ARC contents (persistent L2ARC). .It Fl lll Ar device -Display every configuration, unique or not. If a valid L2ARC header was found +Display every configuration, unique or not. +If a valid L2ARC header was found also display the properties of log entries in log blocks used for restoring L2ARC contents (persistent L2ARC). .Pp If the .Fl q option is also specified, don't print the labels or the L2ARC header. .Pp If the .Fl u -option is also specified, also display the uberblocks on this device. Specify -multiple times to increase verbosity. +option is also specified, also display the uberblocks on this device. +Specify multiple times to increase verbosity. .It Fl L Disable leak detection and the loading of space maps. By default, .Nm verifies that all non-free blocks are referenced, which can be very expensive. .It Fl m Display the offset, spacemap, free space of each metaslab, all the log spacemaps and their obsolete entry statistics. .It Fl mm Also display information about the on-disk free space histogram associated with each metaslab. .It Fl mmm Display the maximum contiguous free space, the in-core free space histogram, and the percentage of free space in each space map. .It Fl mmmm Display every spacemap record. .It Fl M Display the offset, spacemap, and free space of each metaslab. .It Fl MM Also display information about the maximum contiguous free space and the percentage of free space in each space map. .It Fl MMM Display every spacemap record. .It Fl O Ar dataset path Look up the specified .Ar path inside of the .Ar dataset and display its metadata and indirect blocks. Specified .Ar path must be relative to the root of .Ar dataset . This option can be combined with .Fl v for increasing verbosity. .It Fl r Ar dataset path destination Copy the specified .Ar path inside of the .Ar dataset to the specified destination. Specified .Ar path must be relative to the root of .Ar dataset . This option can be combined with .Fl v for increasing verbosity. .It Xo -.Fl R Ar poolname vdev Ns \&: Ns Ar offset Ns \&: Ns Ar [/] Ns Op : Ns Ar flags +.Fl R Ar poolname vdev : Ns Ar offset : Ns Oo Ar lsize Ns / Oc Ns Ar psize Ns Op : Ns Ar flags .Xc Read and display a block from the specified device. By default the block is displayed as a hex dump, but see the description of the .Sy r flag, below. .Pp The block is specified in terms of a colon-separated tuple .Ar vdev .Pq an integer vdev identifier .Ar offset .Pq the offset within the vdev .Ar size .Pq the physical size, or logical size / physical size of the block to read and, optionally, .Ar flags .Pq a set of flags, described below . .Pp .Bl -tag -compact -width "b offset" .It Sy b Ar offset Print block pointer at hex offset .It Sy c Calculate and display checksums .It Sy d -Decompress the block. Set environment variable +Decompress the block. +Set environment variable .Nm ZDB_NO_ZLE to skip zle when guessing. .It Sy e Byte swap the block .It Sy g Dump gang block header .It Sy i Dump indirect block .It Sy r Dump raw uninterpreted block data .It Sy v Verbose output for guessing compression algorithm .El .It Fl s Report statistics on .Nm zdb I/O. Display operation counts, bandwidth, and error counts of I/O to the pool from .Nm . .It Fl S Simulate the effects of deduplication, constructing a DDT and then display that DDT as with .Fl DD . .It Fl u Display the current uberblock. .El .Pp Other options: .Bl -tag -width Ds .It Fl A Do not abort should any assertion fail. .It Fl AA Enable panic recovery, certain errors which would otherwise be fatal are demoted to warnings. .It Fl AAA Do not abort if asserts fail and also enable panic recovery. -.It Fl e Op Fl p Ar path ... +.It Fl e Oo Fl p Ar path Oc Ns … Operate on an exported pool, not present in .Pa /etc/zfs/zpool.cache . The .Fl p flag specifies the path under which devices are to be searched. .It Fl x Ar dumpdir All blocks accessed will be copied to files in the specified directory. The blocks will be placed in sparse files whose name is the same as that of the file or device read. .Nm can be then run on the generated files. Note that the .Fl bbc flags are sufficient to access .Pq and thus copy all metadata on the pool. .It Fl F Attempt to make an unreadable pool readable by trying progressively older transactions. .It Fl G Dump the contents of the zfs_dbgmsg buffer before exiting .Nm . zfs_dbgmsg is a buffer used by ZFS to dump advanced debug information. .It Fl I Ar inflight I/Os Limit the number of outstanding checksum I/Os to the specified value. The default value is 200. This option affects the performance of the .Fl c option. -.It Fl o Ar var Ns = Ns Ar value ... +.It Fl o Ar var Ns = Ns Ar value … Set the given global libzpool variable to the provided value. The value must be an unsigned 32-bit integer. Currently only little-endian systems are supported to avoid accidentally setting the high 32 bits of 64-bit variables. .It Fl P -Print numbers in an unscaled form more amenable to parsing, eg. 1000000 rather -than 1M. +Print numbers in an unscaled form more amenable to parsing, e.g.\& +.Sy 1000000 +rather than +.Sy 1M . .It Fl t Ar transaction Specify the highest transaction to use when searching for uberblocks. See also the .Fl u and .Fl l options for a means to see the available uberblocks and their associated transaction numbers. .It Fl U Ar cachefile Use a cache file other than .Pa /etc/zfs/zpool.cache . .It Fl v Enable verbosity. Specify multiple times for increased verbosity. .It Fl V Attempt verbatim import. This mimics the behavior of the kernel when loading a pool from a cachefile. Only usable with .Fl e . .It Fl X Attempt .Qq extreme transaction rewind, that is attempt the same recovery as .Fl F but read transactions otherwise deemed too old. .It Fl Y Attempt all possible combinations when reconstructing indirect split blocks. This flag disables the individual I/O deadman timer in order to allow as much time as required for the attempted reconstruction. .It Fl y Perform validation for livelists that are being deleted. Scans through the livelist and metaslabs, checking for duplicate entries and compares the two, checking for potential double frees. If it encounters issues, warnings will be printed, but the command will not necessarily fail. .El .Pp Specifying a display option more than once enables verbosity for only that option, with more occurrences enabling more verbosity. .Pp If no options are specified, all information about the named pool will be displayed at default verbosity. +. .Sh EXAMPLES .Bl -tag -width Ds .It Xo -.Sy Example 1 +.Sy Example 1 : Display the configuration of imported pool -.Pa rpool +.Ar rpool .Xc .Bd -literal -# zdb -C rpool - +.No # Nm zdb Fl C Ar rpool MOS Configuration: version: 28 name: 'rpool' - ... + … .Ed .It Xo -.Sy Example 2 +.Sy Example 2 : Display basic dataset information about -.Pa rpool +.Ar rpool .Xc .Bd -literal -# zdb -d rpool +.No # Nm zdb Fl d Ar rpool Dataset mos [META], ID 0, cr_txg 4, 26.9M, 1051 objects Dataset rpool/swap [ZVOL], ID 59, cr_txg 356, 486M, 2 objects - ... + … .Ed .It Xo -.Sy Example 3 +.Sy Example 3 : Display basic information about object 0 in -.Pa rpool/export/home +.Ar rpool/export/home .Xc .Bd -literal -# zdb -d rpool/export/home 0 +.No # Nm zdb Fl d Ar rpool/export/home 0 Dataset rpool/export/home [ZPL], ID 137, cr_txg 1546, 32K, 8 objects Object lvl iblk dblk dsize lsize %full type 0 7 16K 16K 15.0K 16K 25.00 DMU dnode .Ed .It Xo -.Sy Example 4 +.Sy Example 4 : Display the predicted effect of enabling deduplication on -.Pa rpool +.Ar rpool .Xc .Bd -literal -# zdb -S rpool +.No # Nm zdb Fl S Ar rpool Simulated DDT histogram: bucket allocated referenced ______ ______________________________ ______________________________ refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE ------ ------ ----- ----- ----- ------ ----- ----- ----- 1 694K 27.1G 15.0G 15.0G 694K 27.1G 15.0G 15.0G 2 35.0K 1.33G 699M 699M 74.7K 2.79G 1.45G 1.45G - ... + … dedup = 1.11, compress = 1.80, copies = 1.00, dedup * compress / copies = 2.00 .Ed .El +. .Sh SEE ALSO .Xr zfs 8 , .Xr zpool 8 diff --git a/man/man8/zfs-allow.8 b/man/man8/zfs-allow.8 index 2c0a2ca36d54..070161be5413 100644 --- a/man/man8/zfs-allow.8 +++ b/man/man8/zfs-allow.8 @@ -1,376 +1,362 @@ .\" .\" 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 .\" 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 +.Dd May 27, 2021 .Dt ZFS-ALLOW 8 .Os +. .Sh NAME .Nm zfs-allow -.Nd Delegates ZFS administration permission for the file systems to non-privileged users. +.Nd delegate ZFS administration permissions to unprivileged users .Sh SYNOPSIS .Nm zfs .Cm allow .Op Fl dglu -.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns … .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm allow .Op Fl dl .Fl e Ns | Ns Sy everyone .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm allow .Fl c .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm allow .Fl s No @ Ns Ar setname .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm unallow .Op Fl dglru -.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns … .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm unallow .Op Fl dlr .Fl e Ns | Ns Sy everyone .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm unallow .Op Fl r .Fl c .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm unallow .Op Fl r .Fl s No @ Ns Ar setname .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm allow .Ar filesystem Ns | Ns Ar volume .Xc Displays permissions that have been delegated on the specified filesystem or volume. See the other forms of .Nm zfs Cm allow for more information. .Pp Delegations are supported under Linux with the exception of .Sy mount , .Sy unmount , .Sy mountpoint , .Sy canmount , .Sy rename , and .Sy share . These permissions cannot be delegated because the Linux .Xr mount 8 command restricts modifications of the global namespace to the root user. .It Xo .Nm zfs .Cm allow .Op Fl dglu -.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns … .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Xc .It Xo .Nm zfs .Cm allow .Op Fl dl .Fl e Ns | Ns Sy everyone .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Xc Delegates ZFS administration permission for the file systems to non-privileged users. .Bl -tag -width "-d" .It Fl d Allow only for the descendent file systems. .It Fl e Ns | Ns Sy everyone Specifies that the permissions be delegated to everyone. -.It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ... +.It Fl g Ar group Ns Oo , Ns Ar group Oc Ns … Explicitly specify that permissions are delegated to the group. .It Fl l Allow .Qq locally only for the specified file system. -.It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... +.It Fl u Ar user Ns Oo , Ns Ar user Oc Ns … Explicitly specify that permissions are delegated to the user. -.It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns … Specifies to whom the permissions are delegated. Multiple entities can be specified as a comma-separated list. If neither of the .Fl gu options are specified, then the argument is interpreted preferentially as the keyword .Sy everyone , then as a user name, and lastly as a group name. To specify a user or group named .Qq everyone , use the .Fl g or .Fl u options. To specify a group with the same name as a user, use the .Fl g options. .It Xo .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Xc The permissions to delegate. Multiple permissions may be specified as a comma-separated list. Permission names are the same as ZFS subcommand and property names. See the property list below. Property set names, which begin with .Sy @ , may be specified. See the .Fl s form below for details. .El .Pp If neither of the .Fl dl options are specified, or both are, then the permissions are allowed for the file system or volume, and all of its descendents. .Pp Permissions are generally the ability to use a ZFS subcommand or change a ZFS property. The following permissions are available: -.Bd -literal -NAME TYPE NOTES -allow subcommand Must also have the permission that is - being allowed -bookmark subcommand -clone subcommand Must also have the 'create' ability and - 'mount' ability in the origin file system -create subcommand Must also have the 'mount' ability. - Must also have the 'refreservation' ability to - create a non-sparse volume. -destroy subcommand Must also have the 'mount' ability -diff subcommand Allows lookup of paths within a dataset - given an object number, and the ability - to create snapshots necessary to - 'zfs diff'. -hold subcommand Allows adding a user hold to a snapshot -load-key subcommand Allows loading and unloading of encryption key - (see 'zfs load-key' and 'zfs unload-key'). -change-key subcommand Allows changing an encryption key via - 'zfs change-key'. -mount subcommand Allows mount/umount of ZFS datasets -promote subcommand Must also have the 'mount' and 'promote' - ability in the origin file system -receive subcommand Must also have the 'mount' and 'create' - ability -release subcommand Allows releasing a user hold which might - destroy the snapshot -rename subcommand Must also have the 'mount' and 'create' - ability in the new parent -rollback subcommand Must also have the 'mount' ability -send subcommand -share subcommand Allows sharing file systems over NFS - or SMB protocols -snapshot subcommand Must also have the 'mount' ability +.TS +l l l . +NAME TYPE NOTES +_ _ _ +allow subcommand Must also have the permission that is being allowed +bookmark subcommand +clone subcommand Must also have the \fBcreate\fR ability and \fBmount\fR ability in the origin file system +create subcommand Must also have the \fBmount\fR ability. Must also have the \fBrefreservation\fR ability to create a non-sparse volume. +destroy subcommand Must also have the \fBmount\fR ability +diff subcommand Allows lookup of paths within a dataset given an object number, and the ability to create snapshots necessary to \fBzfs diff\fR. +hold subcommand Allows adding a user hold to a snapshot +load subcommand Allows loading and unloading of encryption key (see \fBzfs load-key\fR and \fBzfs unload-key\fR). +change subcommand Allows changing an encryption key via \fBzfs change-key\fR. +mount subcommand Allows mounting/umounting ZFS datasets +promote subcommand Must also have the \fBmount\fR and \fBpromote\fR ability in the origin file system +receive subcommand Must also have the \fBmount\fR and \fBcreate\fR ability +release subcommand Allows releasing a user hold which might destroy the snapshot +rename subcommand Must also have the \fBmount\fR and \fBcreate\fR ability in the new parent +rollback subcommand Must also have the \fBmount\fR ability +send subcommand +share subcommand Allows sharing file systems over NFS or SMB protocols +snapshot subcommand Must also have the \fBmount\fR ability -groupquota other Allows accessing any groupquota@... - property -groupused other Allows reading any groupused@... property -userprop other Allows changing any user property -userquota other Allows accessing any userquota@... - property -userused other Allows reading any userused@... property -projectobjquota other Allows accessing any projectobjquota@... - property -projectquota other Allows accessing any projectquota@... property -projectobjused other Allows reading any projectobjused@... property -projectused other Allows reading any projectused@... property +groupquota other Allows accessing any \fBgroupquota@\fI...\fR property +groupused other Allows reading any \fBgroupused@\fI...\fR property +userprop other Allows changing any user property +userquota other Allows accessing any \fBuserquota@\fI...\fR property +userused other Allows reading any \fBuserused@\fI...\fR property +projectobjquota other Allows accessing any \fBprojectobjquota@\fI...\fR property +projectquota other Allows accessing any \fBprojectquota@\fI...\fR property +projectobjused other Allows reading any \fBprojectobjused@\fI...\fR property +projectused other Allows reading any \fBprojectused@\fI...\fR property -aclinherit property -acltype property -atime property -canmount property -casesensitivity property -checksum property -compression property -copies property -devices property -exec property -filesystem_limit property -mountpoint property -nbmand property -normalization property -primarycache property -quota property -readonly property -recordsize property -refquota property -refreservation property -reservation property -secondarycache property -setuid property -sharenfs property -sharesmb property -snapdir property -snapshot_limit property -utf8only property -version property -volblocksize property -volsize property -vscan property -xattr property -zoned property -.Ed +aclinherit property +acltype property +atime property +canmount property +casesensitivity property +checksum property +compression property +copies property +devices property +exec property +filesystem_limit property +mountpoint property +nbmand property +normalization property +primarycache property +quota property +readonly property +recordsize property +refquota property +refreservation property +reservation property +secondarycache property +setuid property +sharenfs property +sharesmb property +snapdir property +snapshot_limit property +utf8only property +version property +volblocksize property +volsize property +vscan property +xattr property +zoned property +.TE .It Xo .Nm zfs .Cm allow .Fl c .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Xc Sets .Qq create time permissions. These permissions are granted .Pq locally to the creator of any newly-created descendent file system. .It Xo .Nm zfs .Cm allow .Fl s No @ Ns Ar setname .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... +.Ar setname Oc Ns … .Ar filesystem Ns | Ns Ar volume .Xc Defines or adds permissions to a permission set. The set can be used by other .Nm zfs Cm allow commands for the specified file system and its descendents. Sets are evaluated dynamically, so changes to a set are immediately reflected. Permission sets follow the same naming restrictions as ZFS file systems, but the name must begin with .Sy @ , and can be no more than 64 characters long. .It Xo .Nm zfs .Cm unallow .Op Fl dglru -.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... +.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns … .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Xc .It Xo .Nm zfs .Cm unallow .Op Fl dlr .Fl e Ns | Ns Sy everyone .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Xc .It Xo .Nm zfs .Cm unallow .Op Fl r .Fl c .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Xc Removes permissions that were granted with the .Nm zfs Cm allow command. No permissions are explicitly denied, so other permissions granted are still in effect. For example, if the permission is granted by an ancestor. If no permissions are specified, then all permissions for the specified .Ar user , .Ar group , or .Sy everyone are removed. Specifying .Sy everyone .Po or using the .Fl e option .Pc only removes the permissions that were granted to everyone, not all permissions for every user and group. See the .Nm zfs Cm allow command for a description of the .Fl ldugec options. .Bl -tag -width "-r" .It Fl r Recursively remove the permissions from this file system and all descendents. .El .It Xo .Nm zfs .Cm unallow .Op Fl r .Fl s No @ Ns Ar setname .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns -.Ar setname Oc Ns ... Oc +.Ar setname Oc Ns … Oc .Ar filesystem Ns | Ns Ar volume .Xc Removes permissions from a permission set. If no permissions are specified, then all permissions are removed, thus removing the set entirely. .El diff --git a/man/man8/zfs-bookmark.8 b/man/man8/zfs-bookmark.8 index 042ddf504435..d8833c3fbc7d 100644 --- a/man/man8/zfs-bookmark.8 +++ b/man/man8/zfs-bookmark.8 @@ -1,69 +1,67 @@ .\" .\" 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 .\" 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. .\" Copyright (c) 2019, 2020 by Christian Schwarz. All Rights Reserved. .\" -.Dd June 30, 2019 -.Dt ZFS-BOOKMARK 8 SMM +.Dd May 27, 2021 +.Dt ZFS-BOOKMARK 8 .Os +. .Sh NAME .Nm zfs-bookmark -.Nd Creates a bookmark of the given snapshot. +.Nd create bookmark of ZFS snapshot .Sh SYNOPSIS -.Sh DESCRIPTION -.Bl -tag -width "" -.It Xo .Nm zfs .Cm bookmark -.Ar snapshot Ns | Ns Ar bookmark newbookmark -.Xc +.Ar snapshot Ns | Ns Ar bookmark +.Ar newbookmark +. +.Sh DESCRIPTION Creates a new bookmark of the given snapshot or bookmark. Bookmarks mark the point in time when the snapshot was created, and can be used as the incremental source for a -.Xr zfs-send 8 -command. +.Nm zfs Cm send . .Pp When creating a bookmark from an existing redaction bookmark, the resulting bookmark is -.Sy not +.Em not a redaction bookmark. .Pp This feature must be enabled to be used. See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy bookmarks feature. -.El +. .Sh SEE ALSO .Xr zfs-destroy 8 , .Xr zfs-send 8 , .Xr zfs-snapshot 8 diff --git a/man/man8/zfs-clone.8 b/man/man8/zfs-clone.8 index 9cb84d3c56d6..24784ecb9aa1 100644 --- a/man/man8/zfs-clone.8 +++ b/man/man8/zfs-clone.8 @@ -1,77 +1,70 @@ .\" .\" 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 .\" 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 +.Dd May 27, 2021 .Dt ZFS-CLONE 8 .Os +. .Sh NAME .Nm zfs-clone -.Nd Creates a clone of the given snapshot. +.Nd clone snapshot of ZFS dataset .Sh SYNOPSIS .Nm zfs .Cm clone .Op Fl p -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Ar snapshot Ar filesystem Ns | Ns Ar volume +. .Sh DESCRIPTION -.Bl -tag -width "" -.It Xo -.Nm zfs -.Cm clone -.Op Fl p -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar snapshot Ar filesystem Ns | Ns Ar volume -.Xc See the -.Em Clones +.Sx Clones section of .Xr zfsconcepts 8 for details. -The target dataset can be located anywhere in the ZFS hierarchy, and is created -as the same type as the original. -.Bl -tag -width "-o" +The target dataset can be located anywhere in the ZFS hierarchy, +and is created as the same type as the original. +.Bl -tag -width Ds .It Fl o Ar property Ns = Ns Ar value Sets the specified property; see .Nm zfs Cm create for details. .It Fl p Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according to the .Sy mountpoint property inherited from their parent. If the target filesystem or volume already exists, the operation completes successfully. .El -.El +. .Sh SEE ALSO .Xr zfs-promote 8 , .Xr zfs-snapshot 8 diff --git a/man/man8/zfs-create.8 b/man/man8/zfs-create.8 index 5a4f9a32afa5..100a6deeda53 100644 --- a/man/man8/zfs-create.8 +++ b/man/man8/zfs-create.8 @@ -1,248 +1,249 @@ .\" .\" 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 .\" 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 December 1, 2020 .Dt ZFS-CREATE 8 .Os +. .Sh NAME .Nm zfs-create -.Nd Creates a new ZFS file system. +.Nd create ZFS dataset .Sh SYNOPSIS .Nm zfs .Cm create .Op Fl Pnpuv -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Ar filesystem .Nm zfs .Cm create .Op Fl ps .Op Fl b Ar blocksize -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Fl V Ar size Ar volume +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm create .Op Fl Pnpuv -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Ar filesystem .Xc Creates a new ZFS file system. The file system is automatically mounted according to the .Sy mountpoint property inherited from the parent, unless the .Fl u option is used. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value Sets the specified property as if the command .Nm zfs Cm set Ar property Ns = Ns Ar value was invoked at the same time the dataset was created. Any editable ZFS property can also be set at creation time. Multiple .Fl o options can be specified. An error results if the same property is specified in multiple .Fl o options. .It Fl p Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according to the .Sy mountpoint property inherited from their parent. Any property specified on the command line using the .Fl o option is ignored. If the target filesystem already exists, the operation completes successfully. .It Fl n Do a dry-run .Pq Qq No-op creation. No datasets will be created. This is useful in conjunction with the .Fl v or .Fl P flags to validate properties that are passed via .Fl o options and those implied by other options. The actual dataset creation can still fail due to insufficient privileges or available capacity. .It Fl P Print machine-parsable verbose information about the created dataset. Each line of output contains a key and one or two values, all separated by tabs. The .Sy create_ancestors and .Sy create keys have .Em filesystem as their only value. The .Sy create_ancestors key only appears if the .Fl p option is used. The .Sy property key has two values, a property name that property's value. The .Sy property key may appear zero or more times, once for each property that will be set local to .Em filesystem due to the use of the .Fl o option. .It Fl u Do not mount the newly created file system. .It Fl v Print verbose information about the created dataset. .El .It Xo .Nm zfs .Cm create .Op Fl ps .Op Fl b Ar blocksize -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Fl V Ar size Ar volume .Xc Creates a volume of the given size. The volume is exported as a block device in .Pa /dev/zvol/path , where .Em path is the name of the volume in the ZFS namespace. The size represents the logical size as exported by the device. By default, a reservation of equal size is created. .Pp .Ar size is automatically rounded up to the nearest multiple of the .Sy blocksize . .Bl -tag -width "-b" .It Fl b Ar blocksize Equivalent to .Fl o Sy volblocksize Ns = Ns Ar blocksize . If this option is specified in conjunction with .Fl o Sy volblocksize , the resulting behavior is undefined. .It Fl o Ar property Ns = Ns Ar value Sets the specified property as if the .Nm zfs Cm set Ar property Ns = Ns Ar value command was invoked at the same time the dataset was created. Any editable ZFS property can also be set at creation time. Multiple .Fl o options can be specified. An error results if the same property is specified in multiple .Fl o options. .It Fl p Creates all the non-existing parent datasets. Datasets created in this manner are automatically mounted according to the .Sy mountpoint property inherited from their parent. Any property specified on the command line using the .Fl o option is ignored. If the target filesystem already exists, the operation completes successfully. .It Fl s Creates a sparse volume with no reservation. See .Sy volsize in the .Em Native Properties section of .Xr zfsprops 8 for more information about sparse volumes. .It Fl n Do a dry-run .Pq Qq No-op creation. No datasets will be created. This is useful in conjunction with the .Fl v or .Fl P flags to validate properties that are passed via .Fl o options and those implied by other options. The actual dataset creation can still fail due to insufficient privileges or available capacity. .It Fl P Print machine-parsable verbose information about the created dataset. Each line of output contains a key and one or two values, all separated by tabs. The .Sy create_ancestors and .Sy create keys have .Em volume as their only value. The .Sy create_ancestors key only appears if the .Fl p option is used. The .Sy property key has two values, a property name that property's value. The .Sy property key may appear zero or more times, once for each property that will be set local to .Em volume due to the use of the .Fl b or .Fl o options, as well as .Sy refreservation if the volume is not sparse. .It Fl v Print verbose information about the created dataset. .El .El .Ss ZFS Volumes as Swap -ZFS volumes may be used as swap devices. After creating the volume with the +ZFS volumes may be used as swap devices. +After creating the volume with the .Nm zfs Cm create Fl V -command set up and enable the swap area using the -.Xr mkswap 8 -and +enable the swap area using the .Xr swapon 8 -commands. Do not swap to a file on a ZFS file system. A ZFS swap file -configuration is not supported. +command. +Swapping to files on ZFS filesystems is not supported. +. .Sh SEE ALSO .Xr zfs-destroy 8 , .Xr zfs-list 8 , .Xr zpool-create 8 diff --git a/man/man8/zfs-destroy.8 b/man/man8/zfs-destroy.8 index b0365cc82a91..51d9b7ab8e7d 100644 --- a/man/man8/zfs-destroy.8 +++ b/man/man8/zfs-destroy.8 @@ -1,178 +1,178 @@ .\" .\" 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 .\" 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 ZFS-DESTROY 8 .Os +. .Sh NAME .Nm zfs-destroy -.Nd Destroys the given dataset(s), snapshot(s), or bookmark. +.Nd destroy ZFS dataset, snapshots, or bookmark .Sh SYNOPSIS .Nm zfs .Cm destroy .Op Fl Rfnprv .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm destroy .Op Fl Rdnprv .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns -.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... +.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns … .Nm zfs .Cm destroy .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm destroy .Op Fl Rfnprv .Ar filesystem Ns | Ns Ar volume .Xc Destroys the given dataset. By default, the command unshares any file systems that are currently shared, unmounts any file systems that are currently mounted, and refuses to destroy a dataset that has active dependents .Pq children or clones . .Bl -tag -width "-R" .It Fl R Recursively destroy all dependents, including cloned file systems outside the target hierarchy. .It Fl f -Force an unmount of any file systems using the -.Nm unmount Fl f -command. +Forcibly unmount file systems. This option has no effect on non-file systems or unmounted file systems. .It Fl n Do a dry-run .Pq Qq No-op deletion. No data will be deleted. This is useful in conjunction with the .Fl v or .Fl p flags to determine what data would be deleted. .It Fl p Print machine-parsable verbose information about the deleted data. .It Fl r Recursively destroy all children. .It Fl v Print verbose information about the deleted data. .El .Pp Extreme care should be taken when applying either the .Fl r or the .Fl R options, as they can destroy large portions of a pool and cause unexpected behavior for mounted file systems in use. .It Xo .Nm zfs .Cm destroy .Op Fl Rdnprv .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns -.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... +.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns … .Xc The given snapshots are destroyed immediately if and only if the -.Ql zfs destroy +.Nm zfs Cm destroy command without the .Fl d option would have destroyed it. Such immediate destruction would occur, for example, if the snapshot had no clones and the user-initiated reference count were zero. .Pp If a snapshot does not qualify for immediate destruction, it is marked for deferred deletion. In this state, it exists as a usable, visible snapshot until both of the preconditions listed above are met, at which point it is destroyed. .Pp An inclusive range of snapshots may be specified by separating the first and last snapshots with a percent sign. The first and/or last snapshots may be left blank, in which case the filesystem's oldest or newest snapshot will be implied. .Pp Multiple snapshots .Pq or ranges of snapshots of the same filesystem or volume may be specified in a comma-separated list of snapshots. Only the snapshot's short name .Po the part after the .Sy @ .Pc should be specified when using a range or comma-separated list to identify multiple snapshots. .Bl -tag -width "-R" .It Fl R Recursively destroy all clones of these snapshots, including the clones, snapshots, and children. If this flag is specified, the .Fl d flag will have no effect. .It Fl d -Destroy immediately. If a snapshot cannot be destroyed now, mark it for -deferred destruction. +Destroy immediately. +If a snapshot cannot be destroyed now, mark it for deferred destruction. .It Fl n Do a dry-run .Pq Qq No-op deletion. No data will be deleted. This is useful in conjunction with the .Fl p or .Fl v flags to determine what data would be deleted. .It Fl p Print machine-parsable verbose information about the deleted data. .It Fl r Destroy .Pq or mark for deferred deletion all snapshots with this name in descendent file systems. .It Fl v Print verbose information about the deleted data. .Pp Extreme care should be taken when applying either the .Fl r or the .Fl R options, as they can destroy large portions of a pool and cause unexpected behavior for mounted file systems in use. .El .It Xo .Nm zfs .Cm destroy .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark .Xc The given bookmark is destroyed. .El +. .Sh SEE ALSO .Xr zfs-create 8 , .Xr zfs-hold 8 diff --git a/man/man8/zfs-diff.8 b/man/man8/zfs-diff.8 index c7b9e138d849..49443bf47d17 100644 --- a/man/man8/zfs-diff.8 +++ b/man/man8/zfs-diff.8 @@ -1,91 +1,98 @@ .\" .\" 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 .\" 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 +.Dd May 29, 2021 .Dt ZFS-DIFF 8 .Os +. .Sh NAME .Nm zfs-diff -.Nd Display the difference between two snapshots of a given filesystem. +.Nd show difference between ZFS snapshots .Sh SYNOPSIS .Nm zfs .Cm diff .Op Fl FHt .Ar snapshot Ar snapshot Ns | Ns Ar filesystem +. .Sh DESCRIPTION -.Bl -tag -width "" -.It Xo -.Nm zfs -.Cm diff -.Op Fl FHt -.Ar snapshot Ar snapshot Ns | Ns Ar filesystem -.Xc Display the difference between a snapshot of a given filesystem and another snapshot of that filesystem from a later time or the current contents of the filesystem. The first column is a character indicating the type of change, the other columns indicate pathname, new pathname .Pq in case of rename , change in link count, and optionally file type and/or change time. The types of change are: -.Bd -literal -- The path has been removed -+ The path has been created -M The path has been modified -R The path has been renamed -.Ed +.Bl -tag -compact -offset Ds -width "M" +.It Sy - +The path has been removed +.It Sy + +The path has been created +.It Sy M +The path has been modified +.It Sy R +The path has been renamed +.El .Bl -tag -width "-F" .It Fl F Display an indication of the type of file, in a manner similar to the .Fl F option of .Xr ls 1 . -.Bd -literal -B Block device -C Character device -/ Directory -> Door -| Named pipe -@ Symbolic link -P Event port -= Socket -F Regular file -.Ed +.Bl -tag -compact -offset 2n -width "B" +.It Sy B +Block device +.It Sy C +Character device +.It Sy / +Directory +.It Sy > +Door +.It Sy |\& +Named pipe +.It Sy @ +Symbolic link +.It Sy P +Event port +.It Sy = +Socket +.It Sy F +Regular file +.El .It Fl H Give more parsable tab-separated output, without header lines and without arrows. .It Fl t Display the path's inode change time as the first column of output. .El -.El +. .Sh SEE ALSO .Xr zfs-snapshot 8 diff --git a/man/man8/zfs-hold.8 b/man/man8/zfs-hold.8 index ac56fc4a434a..5e4652092e80 100644 --- a/man/man8/zfs-hold.8 +++ b/man/man8/zfs-hold.8 @@ -1,110 +1,112 @@ .\" .\" 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 .\" 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 ZFS-HOLD 8 .Os +. .Sh NAME .Nm zfs-hold -.Nd Hold a snapshot to prevent it being removed with the zfs destroy command. +.Nd hold ZFS snapshots to prevent their removal .Sh SYNOPSIS .Nm zfs .Cm hold .Op Fl r -.Ar tag Ar snapshot Ns ... +.Ar tag Ar snapshot Ns … .Nm zfs .Cm holds .Op Fl rH -.Ar snapshot Ns ... +.Ar snapshot Ns … .Nm zfs .Cm release .Op Fl r -.Ar tag Ar snapshot Ns ... +.Ar tag Ar snapshot Ns … +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm hold .Op Fl r -.Ar tag Ar snapshot Ns ... +.Ar tag Ar snapshot Ns … .Xc Adds a single reference, named with the .Ar tag -argument, to the specified snapshot or snapshots. +argument, to the specified snapshots. Each snapshot has its own tag namespace, and tags must be unique within that space. .Pp If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy command return -.Er EBUSY . +.Sy EBUSY . .Bl -tag -width "-r" .It Fl r Specifies that a hold with the given tag is applied recursively to the snapshots of all descendent file systems. .El .It Xo .Nm zfs .Cm holds .Op Fl rH -.Ar snapshot Ns ... +.Ar snapshot Ns … .Xc Lists all existing user references for the given snapshot or snapshots. .Bl -tag -width "-r" .It Fl r Lists the holds that are set on the named descendent snapshots, in addition to listing the holds on the named snapshot. .It Fl H Do not print headers, use tab-delimited output. .El .It Xo .Nm zfs .Cm release .Op Fl r -.Ar tag Ar snapshot Ns ... +.Ar tag Ar snapshot Ns … .Xc Removes a single reference, named with the .Ar tag argument, from the specified snapshot or snapshots. The tag must already exist for each snapshot. If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy command return -.Er EBUSY . +.Sy EBUSY . .Bl -tag -width "-r" .It Fl r Recursively releases a hold with the given tag on the snapshots of all descendent file systems. .El .El +. .Sh SEE ALSO .Xr zfs-destroy 8 diff --git a/man/man8/zfs-jail.8 b/man/man8/zfs-jail.8 index ef621185e6a8..d4a04073edbc 100644 --- a/man/man8/zfs-jail.8 +++ b/man/man8/zfs-jail.8 @@ -1,119 +1,123 @@ .\" .\" 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 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. .\" Copyright (c) 2011, Pawel Jakub Dawidek .\" Copyright (c) 2012, Glen Barber .\" Copyright (c) 2012, Bryan Drewery .\" Copyright (c) 2013, Steven Hartland .\" 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) 2014, Xin LI .\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved. .\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved. .\" Copyright 2019 Richard Laager. All rights reserved. .\" Copyright 2018 Nexenta Systems, Inc. .\" Copyright 2019 Joyent, Inc. .\" -.Dd December 9, 2019 +.Dd May 27, 2021 .Dt ZFS-JAIL 8 -.Os FreeBSD +.Os +. .Sh NAME .Nm zfs-jail -.Nd Attaches and detaches ZFS filesystems from FreeBSD jails. -.No A Tn ZFS -dataset can be attached to a jail by using the -.Qq Nm zfs jail -subcommand. You cannot attach a dataset to one jail and the children of the -same dataset to another jail. You can also not attach the root file system -of the jail or any dataset which needs to be mounted before the zfs rc script -is run inside the jail, as it would be attached unmounted until it is -mounted from the rc script inside the jail. To allow management of the -dataset from within a jail, the -.Sy jailed -property has to be set and the jail needs access to the -.Pa /dev/zfs -device. The -.Sy quota -property cannot be changed from within a jail. See -.Xr jail 8 -for information on how to allow mounting -.Tn ZFS -datasets from within a jail. -.Pp -.No A Tn ZFS -dataset can be detached from a jail using the -.Qq Nm zfs unjail -subcommand. -.Pp -After a dataset is attached to a jail and the jailed property is set, a jailed -file system cannot be mounted outside the jail, since the jail administrator -might have set the mount point to an unacceptable value. +.Nd attach or detach ZFS filesystem from FreeBSD jail .Sh SYNOPSIS -.Nm zfs -.Cm jail -.Ar jailid Ns | Ns Ar jailname filesystem -.Nm zfs -.Cm unjail -.Ar jailid Ns | Ns Ar jailname filesystem +.Nm zfs Cm jail +.Ar jailid Ns | Ns Ar jailname +.Ar filesystem +.Nm zfs Cm unjail +.Ar jailid Ns | Ns Ar jailname +.Ar filesystem +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm jail -.Ar jailid filesystem +.Ar jailid Ns | Ns Ar jailname +.Ar filesystem .Xc -.Pp -Attaches the specified +Attach the specified .Ar filesystem to the jail identified by JID -.Ar jailid . +.Ar jailid +or name +.Ar jailname . From now on this file system tree can be managed from within a jail if the .Sy jailed -property has been set. To use this functuinality, the jail needs the -.Va allow.mount +property has been set. +To use this functionality, the jail needs the +.Sy allow.mount and -.Va allow.mount.zfs -parameters set to 1 and the -.Va enforce_statfs -parameter set to a value lower than 2. +.Sy allow.mount.zfs +parameters set to +.Sy 1 +and the +.Sy enforce_statfs +parameter set to a value lower than +.Sy 2 . +.Pp +You cannot attach a jailed dataset's children to another jail. +You can also not attach the root file system +of the jail or any dataset which needs to be mounted before the zfs rc script +is run inside the jail, as it would be attached unmounted until it is +mounted from the rc script inside the jail. +.Pp +To allow management of the dataset from within a jail, the +.Sy jailed +property has to be set and the jail needs access to the +.Pa /dev/zfs +device. +The +.Sy quota +property cannot be changed from within a jail. +.Pp +After a dataset is attached to a jail and the +.Sy jailed +property is set, a jailed file system cannot be mounted outside the jail, +since the jail administrator might have set the mount point to an unacceptable value. .Pp See .Xr jail 8 -for more information on managing jails and configuring the parameters above. +for more information on managing jails. +Jails are a +.Fx +feature and are not relevant on other platforms. .It Xo .Nm zfs .Cm unjail -.Ar jailid filesystem +.Ar jailid Ns | Ns Ar jailname +.Ar filesystem .Xc -.Pp Detaches the specified .Ar filesystem from the jail identified by JID -.Ar jailid . +.Ar jailid +or name +.Ar jailname . .El .Sh SEE ALSO .Xr jail 8 , .Xr zfsprops 8 diff --git a/man/man8/zfs-list.8 b/man/man8/zfs-list.8 index 3ed74955e942..0313b3a14ecb 100644 --- a/man/man8/zfs-list.8 +++ b/man/man8/zfs-list.8 @@ -1,174 +1,162 @@ .\" .\" 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 .\" 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 +.Dd May 27, 2021 .Dt ZFS-LIST 8 .Os +. .Sh NAME .Nm zfs-list -.Nd Lists the property information for the given datasets in tabular form. +.Nd list properties of ZFS datasets .Sh SYNOPSIS .Nm zfs .Cm list .Op Fl r Ns | Ns Fl d Ar depth .Op Fl Hp -.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc -.Oo Fl s Ar property Oc Ns ... -.Oo Fl S Ar property Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc -.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... +.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns … Oc +.Oo Fl s Ar property Oc Ns … +.Oo Fl S Ar property Oc Ns … +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc +.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width "" -.It Xo -.Nm zfs -.Cm list -.Op Fl r Ns | Ns Fl d Ar depth -.Op Fl Hp -.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc -.Oo Fl s Ar property Oc Ns ... -.Oo Fl S Ar property Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc -.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... -.Xc If specified, you can list property information by the absolute pathname or the relative pathname. By default, all file systems and volumes are displayed. Snapshots are displayed if the .Sy listsnapshots pool property is .Sy on .Po the default is .Sy off .Pc , or if the .Fl t Sy snapshot or .Fl t Sy all options are specified. The following fields are displayed: -.Sy name Ns \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns . +.Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint . .Bl -tag -width "-H" .It Fl H Used for scripting mode. Do not print headers and separate fields by a single tab instead of arbitrary white space. .It Fl S Ar property Same as the .Fl s option, but sorts by property in descending order. .It Fl d Ar depth Recursively display any children of the dataset, limiting the recursion to .Ar depth . A .Ar depth of .Sy 1 will display only the dataset and its direct children. .It Fl o Ar property A comma-separated list of properties to display. The property must be: -.Bl -bullet +.Bl -bullet -compact .It One of the properties described in the -.Em Native Properties +.Sx Native Properties section of .Xr zfsprops 8 .It A user property .It The value .Sy name to display the dataset name .It The value .Sy space to display space usage properties on file systems and volumes. This is a shortcut for specifying -.Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns -.Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t -.Sy filesystem Ns \&, Ns Sy volume -syntax. +.Fl o Ns \ \& Ns Sy name , Ns Sy avail , Ns Sy used , Ns Sy usedsnap , Ns +.Sy usedds , Ns Sy usedrefreserv , Ns Sy usedchild +.Fl t Sy filesystem , Ns Sy volume . .El .It Fl p Display numbers in parsable .Pq exact values. .It Fl r Recursively display any children of the dataset on the command line. .It Fl s Ar property A property for sorting the output by column in ascending order based on the value of the property. The property must be one of the properties described in the -.Em Properties +.Sx Properties section of .Xr zfsprops 8 or the value .Sy name to sort by the dataset name. Multiple properties can be specified at one time using multiple .Fl s property options. Multiple .Fl s options are evaluated from left to right in decreasing order of importance. The following is a list of sorting criteria: -.Bl -bullet +.Bl -bullet -compact .It Numeric types sort in numeric order. .It String types sort in alphabetical order. .It Types inappropriate for a row sort that row to the literal bottom, regardless of the specified ordering. .El .Pp If no sorting options are specified the existing behavior of .Nm zfs Cm list is preserved. .It Fl t Ar type A comma-separated list of types to display, where .Ar type is one of .Sy filesystem , .Sy snapshot , .Sy volume , .Sy bookmark , or .Sy all . For example, specifying .Fl t Sy snapshot displays only snapshots. .El -.El +. .Sh SEE ALSO .Xr zfs-get 8 , .Xr zfsprops 8 diff --git a/man/man8/zfs-load-key.8 b/man/man8/zfs-load-key.8 index 35294d105cd8..f29d3df824fd 100644 --- a/man/man8/zfs-load-key.8 +++ b/man/man8/zfs-load-key.8 @@ -1,295 +1,301 @@ .\" .\" 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 .\" 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 January 13, 2020 .Dt ZFS-LOAD-KEY 8 .Os +. .Sh NAME .Nm zfs-load-key -.Nd Load, unload, or change the encryption key used to access a dataset. +.Nd load, unload, or change encryption key of ZFS dataset .Sh SYNOPSIS .Nm zfs .Cm load-key .Op Fl nr .Op Fl L Ar keylocation -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Nm zfs .Cm unload-key .Op Fl r -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Nm zfs .Cm change-key .Op Fl l .Op Fl o Ar keylocation Ns = Ns Ar value .Op Fl o Ar keyformat Ns = Ns Ar value .Op Fl o Ar pbkdf2iters Ns = Ns Ar value .Ar filesystem .Nm zfs .Cm change-key .Fl i .Op Fl l .Ar filesystem +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm load-key .Op Fl nr .Op Fl L Ar keylocation -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Xc Load the key for .Ar filesystem , allowing it and all children that inherit the .Sy keylocation -property to be accessed. The key will be expected in the format specified by the +property to be accessed. +The key will be expected in the format specified by the .Sy keyformat and location specified by the .Sy keylocation -property. Note that if the +property. +Note that if the .Sy keylocation is set to .Sy prompt -the terminal will interactively wait for the key to be entered. Loading a key -will not automatically mount the dataset. If that functionality is desired, +the terminal will interactively wait for the key to be entered. +Loading a key will not automatically mount the dataset. +If that functionality is desired, .Nm zfs Cm mount Fl l will ask for the key and mount the dataset .Po see .Xr zfs-mount 8 .Pc . Once the key is loaded the .Sy keystatus property will become .Sy available . .Bl -tag -width "-r" .It Fl r Recursively loads the keys for the specified filesystem and all descendent encryption roots. .It Fl a Loads the keys for all encryption roots in all imported pools. .It Fl n Do a dry-run .Pq Qq No-op -load-key. This will cause zfs to simply check that the -provided key is correct. This command may be run even if the key is already -loaded. +.Cm load-key . +This will cause +.Nm zfs +to simply check that the provided key is correct. +This command may be run even if the key is already loaded. .It Fl L Ar keylocation Use .Ar keylocation instead of the .Sy keylocation -property. This will not change the value of the property on the dataset. Note -that if used with either +property. +This will not change the value of the property on the dataset. +Note that if used with either .Fl r or .Fl a , .Ar keylocation may only be given as .Sy prompt . .El .It Xo .Nm zfs .Cm unload-key .Op Fl r -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Xc Unloads a key from ZFS, removing the ability to access the dataset and all of its children that inherit the .Sy keylocation -property. This requires that the dataset is not currently open or mounted. Once -the key is unloaded the +property. +This requires that the dataset is not currently open or mounted. +Once the key is unloaded the .Sy keystatus property will become .Sy unavailable . .Bl -tag -width "-r" .It Fl r Recursively unloads the keys for the specified filesystem and all descendent encryption roots. .It Fl a Unloads the keys for all encryption roots in all imported pools. .El .It Xo .Nm zfs .Cm change-key .Op Fl l .Op Fl o Ar keylocation Ns = Ns Ar value .Op Fl o Ar keyformat Ns = Ns Ar value .Op Fl o Ar pbkdf2iters Ns = Ns Ar value .Ar filesystem .Xc .It Xo .Nm zfs .Cm change-key .Fl i .Op Fl l .Ar filesystem .Xc -Changes the user's key (e.g. a passphrase) used to access a dataset. This -command requires that the existing key for the dataset is already loaded into -ZFS. This command may also be used to change the +Changes the user's key (e.g. a passphrase) used to access a dataset. +This command requires that the existing key for the dataset is already loaded. +This command may also be used to change the .Sy keylocation , .Sy keyformat , and .Sy pbkdf2iters -properties as needed. If the dataset was not previously an encryption root it -will become one. Alternatively, the +properties as needed. +If the dataset was not previously an encryption root it will become one. +Alternatively, the .Fl i flag may be provided to cause an encryption root to inherit the parent's key instead. .Pp If the user's key is compromised, .Nm zfs Cm change-key does not necessarily protect existing or newly-written data from attack. Newly-written data will continue to be encrypted with the same master key as -the existing data. The master key is compromised if an attacker obtains a -user key and the corresponding wrapped master key. Currently, +the existing data. +The master key is compromised if an attacker obtains a +user key and the corresponding wrapped master key. +Currently, .Nm zfs Cm change-key does not overwrite the previous wrapped master key on disk, so it is accessible via forensic analysis for an indeterminate length of time. .Pp In the event of a master key compromise, ideally the drives should be securely erased to remove all the old data (which is readable using the compromised -master key), a new pool created, and the data copied back. This can be -approximated in place by creating new datasets, copying the data -(e.g. using -.Nm zfs Cm send -| -.Nm zfs Cm recv Ns -), and then clearing the free space with -.Nm zpool Cm trim --secure +master key), a new pool created, and the data copied back. +This can be approximated in place by creating new datasets, copying the data +.Pq e.g. using Nm zfs Cm send | Nm zfs Cm recv , +and then clearing the free space with +.Nm zpool Cm trim Fl -secure if supported by your hardware, otherwise -.Nm zpool Cm initialize Ns . +.Nm zpool Cm initialize . .Bl -tag -width "-r" .It Fl l -Ensures the key is loaded before attempting to change the key. This is -effectively equivalent to -.Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem +Ensures the key is loaded before attempting to change the key. +This is effectively equivalent to runnin +.Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem .It Fl o Ar property Ns = Ns Ar value -Allows the user to set encryption key properties ( -.Sy keyformat , -.Sy keylocation , -and -.Sy pbkdf2iters -) while changing the key. This is the only way to alter +Allows the user to set encryption key properties +.Pq Sy keyformat , keylocation , No and Sy pbkdf2iters +while changing the key. +This is the only way to alter .Sy keyformat and .Sy pbkdf2iters after the dataset has been created. .It Fl i Indicates that zfs should make .Ar filesystem -inherit the key of its parent. Note that this command can only be run on an -encryption root that has an encrypted parent. +inherit the key of its parent. +Note that this command can only be run on an encryption root +that has an encrypted parent. .El .El .Ss Encryption Enabling the .Sy encryption -feature allows for the creation of encrypted filesystems and volumes. ZFS -will encrypt file and zvol data, file attributes, ACLs, permission bits, +feature allows for the creation of encrypted filesystems and volumes. +ZFS will encrypt file and volume data, file attributes, ACLs, permission bits, directory listings, FUID mappings, and -.Sy userused -/ -.Sy groupused -data. ZFS will not encrypt metadata related to the pool structure, including +.Sy userused Ns / Ns Sy groupused +data. +ZFS will not encrypt metadata related to the pool structure, including dataset and snapshot names, dataset hierarchy, properties, file size, file holes, and deduplication tables (though the deduplicated data itself is encrypted). .Pp -Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase) -does not require re-encrypting the entire dataset. Datasets can be scrubbed, +Key rotation is managed by ZFS. +Changing the user's key (e.g. a passphrase) +does not require re-encrypting the entire dataset. +Datasets can be scrubbed, resilvered, renamed, and deleted without the encryption keys being loaded (see the -.Nm zfs Cm load-key +.Cm load-key subcommand for more info on key loading). .Pp Creating an encrypted dataset requires specifying the -.Sy encryption -and -.Sy keyformat +.Sy encryption No and Sy keyformat properties at creation time, along with an optional -.Sy keylocation -and -.Sy pbkdf2iters . +.Sy keylocation No and Sy pbkdf2iters . After entering an encryption key, the -created dataset will become an encryption root. Any descendant datasets will +created dataset will become an encryption root. +Any descendant datasets will inherit their encryption key from the encryption root by default, meaning that loading, unloading, or changing the key for the encryption root will implicitly -do the same for all inheriting datasets. If this inheritance is not desired, -simply supply a +do the same for all inheriting datasets. +If this inheritance is not desired, simply supply a .Sy keyformat when creating the child dataset or use .Nm zfs Cm change-key to break an existing relationship, creating a new encryption root on the child. Note that the child's .Sy keyformat may match that of the parent while still creating a new encryption root, and that changing the .Sy encryption property alone does not create a new encryption root; this would simply use a -different cipher suite with the same key as its encryption root. The one -exception is that clones will always use their origin's encryption key. -As a result of this exception, some encryption-related properties (namely -.Sy keystatus , -.Sy keyformat , -.Sy keylocation , -and -.Sy pbkdf2iters ) +different cipher suite with the same key as its encryption root. +The one exception is that clones will always use their origin's encryption key. +As a result of this exception, some encryption-related properties +.Pq namely Sy keystatus , keyformat , keylocation , No and Sy pbkdf2iters do not inherit like other ZFS properties and instead use the value determined -by their encryption root. Encryption root inheritance can be tracked via the -read-only +by their encryption root. +Encryption root inheritance can be tracked via the read-only .Sy encryptionroot property. .Pp Encryption changes the behavior of a few ZFS -operations. Encryption is applied after compression so compression ratios are -preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data +operations. +Encryption is applied after compression so compression ratios are preserved. +Normally checksums in ZFS are 256 bits long, but for encrypted data the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from the encryption suite, which provides additional protection against maliciously -altered data. Deduplication is still possible with encryption enabled but for -security, datasets will only dedup against themselves, their snapshots, and -their clones. +altered data. +Deduplication is still possible with encryption enabled but for security, +datasets will only deduplicate against themselves, their snapshots, +and their clones. .Pp -There are a few limitations on encrypted datasets. Encrypted data cannot be -embedded via the +There are a few limitations on encrypted datasets. +Encrypted data cannot be embedded via the .Sy embedded_data -feature. Encrypted datasets may not have +feature. +Encrypted datasets may not have .Sy copies Ns = Ns Em 3 since the implementation stores some encryption metadata where the third copy -would normally be. Since compression is applied before encryption datasets may -be vulnerable to a CRIME-like attack if applications accessing the data allow -for it. Deduplication with encryption will leak information about which blocks -are equivalent in a dataset and will incur an extra CPU cost per block written. +would normally be. +Since compression is applied before encryption, datasets may +be vulnerable to a CRIME-like attack if applications accessing the data allow for it. +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 zfs-create 8 , .Xr zfs-set 8 , .Xr zfsprops 8 diff --git a/man/man8/zfs-mount.8 b/man/man8/zfs-mount.8 index 00fb37c786e1..62275242c9f9 100644 --- a/man/man8/zfs-mount.8 +++ b/man/man8/zfs-mount.8 @@ -1,128 +1,130 @@ .\" .\" 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 .\" 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 February 16, 2019 .Dt ZFS-MOUNT 8 .Os +. .Sh NAME .Nm zfs-mount -.Nd Manage mount state of ZFS file systems. +.Nd manage mount state of ZFS filesystems .Sh SYNOPSIS .Nm zfs .Cm mount .Nm zfs .Cm mount .Op Fl Oflv .Op Fl o Ar options -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Nm zfs .Cm unmount .Op Fl fu -.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Fl a Ns | Ns Ar filesystem Ns | Ns Ar mountpoint +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm mount .Xc Displays all ZFS file systems currently mounted. .It Xo .Nm zfs .Cm mount .Op Fl Oflv .Op Fl o Ar options -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Xc Mount ZFS filesystem on a path described by its .Sy mountpoint -property, if the path exists and is empty. If +property, if the path exists and is empty. +If .Sy mountpoint is set to .Em legacy , the filesystem should be instead mounted using .Xr mount 8 . .Bl -tag -width "-O" .It Fl O -Perform an overlay mount. Allows mounting in non-empty +Perform an overlay mount. +Allows mounting in non-empty .Sy mountpoint . See .Xr mount 8 for more information. .It Fl a Mount all available ZFS file systems. Invoked automatically as part of the boot process if configured. .It Ar filesystem Mount the specified filesystem. .It Fl o Ar options An optional, comma-separated list of mount options to use temporarily for the duration of the mount. See the .Em Temporary Mount Point Properties section of .Xr zfsprops 8 for details. .It Fl l -Load keys for encrypted filesystems as they are being mounted. This is -equivalent to executing +Load keys for encrypted filesystems as they are being mounted. +This is equivalent to executing .Nm zfs Cm load-key -on each encryption root before mounting it. Note that if a filesystem has a -.Sy keylocation -of -.Sy prompt +on each encryption root before mounting it. +Note that if a filesystem has +.Sy keylocation Ns = Ns Sy prompt , this will cause the terminal to interactively block after asking for the key. .It Fl v Report mount progress. .It Fl f Attempt to force mounting of all filesystems, even those that couldn't normally be mounted (e.g. redacted datasets). .El .It Xo .Nm zfs .Cm unmount .Op Fl fu -.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Fl a Ns | Ns Ar filesystem Ns | Ns Ar mountpoint .Xc Unmounts currently mounted ZFS file systems. .Bl -tag -width "-a" .It Fl a Unmount all available ZFS file systems. Invoked automatically as part of the shutdown process. .It Fl f Forcefully unmount the file system, even if it is currently in use. This option is not supported on Linux. .It Fl u Unload keys for any encryption roots unmounted by this command. .It Ar filesystem Ns | Ns Ar mountpoint Unmount the specified filesystem. The command can also be given a path to a ZFS file system mount point on the system. .El .El diff --git a/man/man8/zfs-program.8 b/man/man8/zfs-program.8 index 02251ae7cbad..4a9718cdcfcb 100644 --- a/man/man8/zfs-program.8 +++ b/man/man8/zfs-program.8 @@ -1,636 +1,630 @@ +.\" .\" This file and its contents are supplied under the terms of the .\" Common Development and Distribution License ("CDDL"), version 1.0. .\" You may only use this file in accordance with the terms of version .\" 1.0 of the CDDL. .\" .\" A full copy of the text of the CDDL should have accompanied this .\" source. A copy of the CDDL is also available via the Internet at .\" http://www.illumos.org/license/CDDL. .\" -.\" .\" Copyright (c) 2016, 2019 by Delphix. All Rights Reserved. .\" Copyright (c) 2019, 2020 by Christian Schwarz. All Rights Reserved. .\" Copyright 2020 Joyent, Inc. .\" -.Dd January 26, 2021 +.Dd May 27, 2021 .Dt ZFS-PROGRAM 8 .Os +. .Sh NAME .Nm zfs-program -.Nd executes ZFS channel programs +.Nd execute ZFS channel programs .Sh SYNOPSIS .Nm zfs .Cm program .Op Fl jn .Op Fl t Ar instruction-limit .Op Fl m Ar memory-limit .Ar pool .Ar script -.\".Op Ar optional arguments to channel program +.Op Ar script arguments +. .Sh DESCRIPTION The ZFS channel program interface allows ZFS administrative operations to be run programmatically as a Lua script. The entire script is executed atomically, with no other administrative operations taking effect concurrently. A library of ZFS calls is made available to channel program scripts. Channel programs may only be run with root privileges. .Pp A modified version of the Lua 5.2 interpreter is used to run channel program scripts. -The Lua 5.2 manual can be found at: -.Bd -centered -offset indent +The Lua 5.2 manual can be found at .Lk http://www.lua.org/manual/5.2/ -.Ed .Pp The channel program given by .Ar script will be run on .Ar pool , and any attempts to access or modify other pools will cause an error. +. .Sh OPTIONS .Bl -tag -width "-t" .It Fl j -Display channel program output in JSON format. When this flag is specified and -standard output is empty - channel program encountered an error. The details of -such an error will be printed to standard error in plain text. +Display channel program output in JSON format. +When this flag is specified and standard output is empty - +channel program encountered an error. +The details of such an error will be printed to standard error in plain text. .It Fl n Executes a read-only channel program, which runs faster. The program cannot change on-disk state by calling functions from the zfs.sync submodule. The program can be used to gather information such as properties and determining if changes would succeed (zfs.check.*). Without this flag, all pending changes must be synced to disk before a channel program can complete. .It Fl t Ar instruction-limit Limit the number of Lua instructions to execute. If a channel program executes more than the specified number of instructions, it will be stopped and an error will be returned. The default limit is 10 million instructions, and it can be set to a maximum of 100 million instructions. .It Fl m Ar memory-limit Memory limit, in bytes. If a channel program attempts to allocate more memory than the given limit, it will be stopped and an error returned. The default memory limit is 10 MB, and can be set to a maximum of 100 MB. .El .Pp All remaining argument strings will be passed directly to the Lua script as described in the .Sx LUA INTERFACE section below. +. .Sh LUA INTERFACE A channel program can be invoked either from the command line, or via a library call to .Fn lzc_channel_program . +. .Ss Arguments Arguments passed to the channel program are converted to a Lua table. If invoked from the command line, extra arguments to the Lua script will be accessible as an array stored in the argument table with the key 'argv': -.Bd -literal -offset indent +.Bd -literal -compact -offset indent args = ... argv = args["argv"] -- argv == {1="arg1", 2="arg2", ...} .Ed .Pp If invoked from the libZFS interface, an arbitrary argument list can be passed to the channel program, which is accessible via the same "..." syntax in Lua: -.Bd -literal -offset indent +.Bd -literal -compact -offset indent args = ... -- args == {"foo"="bar", "baz"={...}, ...} .Ed .Pp Note that because Lua arrays are 1-indexed, arrays passed to Lua from the libZFS interface will have their indices incremented by 1. That is, the element in .Va arr[0] in a C array passed to a channel program will be stored in .Va arr[1] when accessed from Lua. +. .Ss Return Values Lua return statements take the form: -.Bd -literal -offset indent -return ret0, ret1, ret2, ... -.Ed +.Dl return ret0, ret1, ret2, ... .Pp Return statements returning multiple values are permitted internally in a channel program script, but attempting to return more than one value from the top level of the channel program is not permitted and will throw an error. However, tables containing multiple values can still be returned. If invoked from the command line, a return statement: -.Bd -literal -offset indent +.Bd -literal -compact -offset indent a = {foo="bar", baz=2} return a .Ed .Pp Will be output formatted as: -.Bd -literal -offset indent +.Bd -literal -compact -offset indent Channel program fully executed with return value: return: baz: 2 foo: 'bar' .Ed +. .Ss Fatal Errors If the channel program encounters a fatal error while running, a non-zero exit status will be returned. If more information about the error is available, a singleton list will be returned detailing the error: -.Bd -literal -offset indent -error: "error string, including Lua stack trace" -.Ed +.Dl error: \&"error string, including Lua stack trace" .Pp If a fatal error is returned, the channel program may have not executed at all, may have partially executed, or may have fully executed but failed to pass a return value back to userland. .Pp If the channel program exhausts an instruction or memory limit, a fatal error will be generated and the program will be stopped, leaving the program partially executed. No attempt is made to reverse or undo any operations already performed. Note that because both the instruction count and amount of memory used by a channel program are deterministic when run against the same inputs and filesystem state, as long as a channel program has run successfully once, you can guarantee that it will finish successfully against a similar size system. .Pp If a channel program attempts to return too large a value, the program will fully execute but exit with a nonzero status code and no return value. .Pp .Em Note : ZFS API functions do not generate Fatal Errors when correctly invoked, they return an error code and the channel program continues executing. See the .Sx ZFS API section below for function-specific details on error return codes. +. .Ss Lua to C Value Conversion When invoking a channel program via the libZFS interface, it is necessary to translate arguments and return values from Lua values to their C equivalents, and vice-versa. .Pp There is a correspondence between nvlist values in C and Lua tables. A Lua table which is returned from the channel program will be recursively converted to an nvlist, with table values converted to their natural equivalents: -.Bd -literal -offset indent -string -> string -number -> int64 -boolean -> boolean_value -nil -> boolean (no value) -table -> nvlist -.Ed +.TS +cw3 l c l . + string -> string + number -> int64 + boolean -> boolean_value + nil -> boolean (no value) + table -> nvlist +.TE .Pp Likewise, table keys are replaced by string equivalents as follows: -.Bd -literal -offset indent -string -> no change -number -> signed decimal string ("%lld") -boolean -> "true" | "false" -.Ed +.TS +cw3 l c l . + string -> no change + number -> signed decimal string ("%lld") + boolean -> "true" | "false" +.TE .Pp Any collision of table key strings (for example, the string "true" and a true boolean value) will cause a fatal error. .Pp Lua numbers are represented internally as signed 64-bit integers. +. .Sh LUA STANDARD LIBRARY The following Lua built-in base library functions are available: -.Bd -literal -offset indent -assert rawlen -collectgarbage rawget -error rawset -getmetatable select -ipairs setmetatable -next tonumber -pairs tostring -rawequal type -.Ed +.TS +cw3 l l l l . + assert rawlen collectgarbage rawget + error rawset getmetatable select + ipairs setmetatable next tonumber + pairs tostring rawequal type +.TE .Pp All functions in the .Em coroutine , .Em string , and .Em table built-in submodules are also available. A complete list and documentation of these modules is available in the Lua manual. .Pp The following functions base library functions have been disabled and are not available for use in channel programs: -.Bd -literal -offset indent -dofile -loadfile -load -pcall -print -xpcall -.Ed +.TS +cw3 l l l l l l . + dofile loadfile load pcall print xpcall +.TE +. .Sh ZFS API +. .Ss Function Arguments Each API function takes a fixed set of required positional arguments and optional keyword arguments. For example, the destroy function takes a single positional string argument (the name of the dataset to destroy) and an optional "defer" keyword boolean argument. When using parentheses to specify the arguments to a Lua function, only positional arguments can be used: -.Bd -literal -offset indent -zfs.sync.destroy("rpool@snap") -.Ed +.Dl Sy zfs.sync.destroy Ns Pq \&"rpool@snap" .Pp To use keyword arguments, functions must be called with a single argument that is a Lua table containing entries mapping integers to positional arguments and strings to keyword arguments: -.Bd -literal -offset indent -zfs.sync.destroy({1="rpool@snap", defer=true}) -.Ed +.Dl Sy zfs.sync.destroy Ns Pq {1="rpool@snap", defer=true} .Pp The Lua language allows curly braces to be used in place of parenthesis as syntactic sugar for this calling convention: -.Bd -literal -offset indent -zfs.sync.snapshot{"rpool@snap", defer=true} -.Ed +.Dl Sy zfs.sync.snapshot Ns {"rpool@snap", defer=true} +. .Ss Function Return Values If an API function succeeds, it returns 0. If it fails, it returns an error code and the channel program continues executing. API functions do not generate Fatal Errors except in the case of an unrecoverable internal file system error. .Pp In addition to returning an error code, some functions also return extra details describing what caused the error. This extra description is given as a second return value, and will always be a Lua table, or Nil if no error details were returned. Different keys will exist in the error details table depending on the function and error case. Any such function may be called expecting a single return value: -.Bd -literal -offset indent -errno = zfs.sync.promote(dataset) -.Ed +.Dl errno = Sy zfs.sync.promote Ns Pq dataset .Pp Or, the error details can be retrieved: -.Bd -literal -offset indent -errno, details = zfs.sync.promote(dataset) +.Bd -literal -compact -offset indent +.No errno, details = Sy zfs.sync.promote Ns Pq dataset if (errno == EEXIST) then assert(details ~= Nil) list_of_conflicting_snapshots = details end .Ed .Pp The following global aliases for API function error return codes are defined for use in channel programs: -.Bd -literal -offset indent -EPERM ECHILD ENODEV ENOSPC -ENOENT EAGAIN ENOTDIR ESPIPE -ESRCH ENOMEM EISDIR EROFS -EINTR EACCES EINVAL EMLINK -EIO EFAULT ENFILE EPIPE -ENXIO ENOTBLK EMFILE EDOM -E2BIG EBUSY ENOTTY ERANGE -ENOEXEC EEXIST ETXTBSY EDQUOT -EBADF EXDEV EFBIG -.Ed +.TS +cw3 l l l l l l l . + EPERM ECHILD ENODEV ENOSPC ENOENT EAGAIN ENOTDIR + ESPIPE ESRCH ENOMEM EISDIR EROFS EINTR EACCES + EINVAL EMLINK EIO EFAULT ENFILE EPIPE ENXIO + ENOTBLK EMFILE EDOM E2BIG EBUSY ENOTTY ERANGE + ENOEXEC EEXIST ETXTBSY EDQUOT EBADF EXDEV EFBIG +.TE +. .Ss API Functions -For detailed descriptions of the exact behavior of any zfs administrative +For detailed descriptions of the exact behavior of any ZFS administrative operations, see the main .Xr zfs 8 manual page. .Bl -tag -width "xx" -.It Em zfs.debug(msg) +.It Fn zfs.debug msg Record a debug message in the zfs_dbgmsg log. A log of these messages can be printed via mdb's "::zfs_dbgmsg" command, or -can be monitored live by running: -.Bd -literal -offset indent - dtrace -n 'zfs-dbgmsg{trace(stringof(arg0))}' -.Ed +can be monitored live by running +.Dl dtrace -n 'zfs-dbgmsg{trace(stringof(arg0))}' .Pp -msg (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "property (string)" +.It Ar msg Pq string Debug message to be printed. -.Ed -.It Em zfs.exists(dataset) +.El +.It Fn zfs.exists dataset Returns true if the given dataset exists, or false if it doesn't. A fatal error will be thrown if the dataset is not in the target pool. That is, in a channel program running on rpool, -zfs.exists("rpool/nonexistent_fs") returns false, but -zfs.exists("somepool/fs_that_may_exist") will error. +.Sy zfs.exists Ns Pq \&"rpool/nonexistent_fs" +returns false, but +.Sy zfs.exists Ns Pq \&"somepool/fs_that_may_exist" +will error. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "property (string)" +.It Ar dataset Pq string Dataset to check for existence. Must be in the target pool. -.Ed -.It Em zfs.get_prop(dataset, property) +.El +.It Fn zfs.get_prop dataset property Returns two values. First, a string, number or table containing the property value for the given dataset. Second, a string containing the source of the property (i.e. the name of the dataset in which it was set or nil if it is readonly). Throws a Lua error if the dataset is invalid or the property doesn't exist. Note that Lua only supports int64 number types whereas ZFS number properties are uint64. -This means very large values (like guid) may wrap around and appear negative. +This means very large values (like GUIDs) may wrap around and appear negative. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "property (string)" +.It Ar dataset Pq string Filesystem or snapshot path to retrieve properties from. -.Ed -.Pp -property (string) -.Bd -ragged -compact -offset "xxxx" +.It Ar property Pq string Name of property to retrieve. -All filesystem, snapshot and volume properties are supported except -for 'mounted' and 'iscsioptions.' -Also supports the 'written@snap' and 'written#bookmark' properties and -the '@id' properties, though the id must be in numeric -form. -.Ed +All filesystem, snapshot and volume properties are supported except for +.Sy mounted +and +.Sy iscsioptions . +Also supports the +.Sy written@ Ns Ar snap +and +.Sy written# Ns Ar bookmark +properties and the +.Ao Sy user Ns | Ns Sy group Ac Ns Ao Sy quota Ns | Ns Sy used Ac Ns Sy @ Ns Ar id +properties, though the id must be in numeric form. +.El .El .Bl -tag -width "xx" .It Sy zfs.sync submodule The sync submodule contains functions that modify the on-disk state. They are executed in "syncing context". .Pp The available sync submodule functions are as follows: .Bl -tag -width "xx" -.It Em zfs.sync.destroy(dataset, [defer=true|false]) +.It Sy zfs.sync.destroy Ns Pq Ar dataset , Op Ar defer Ns = Ns Sy true Ns | Ns Sy false Destroy the given dataset. Returns 0 on successful destroy, or a nonzero error code if the dataset could not be destroyed (for example, if the dataset has any active children or clones). .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar dataset Pq string Filesystem or snapshot to be destroyed. -.Ed -.Pp -[optional] defer (boolean) -.Bd -ragged -compact -offset "xxxx" +.It Op Ar defer Pq boolean Valid only for destroying snapshots. If set to true, and the snapshot has holds or clones, allows the snapshot to be marked for deferred deletion rather than failing. -.Ed -.It Em zfs.sync.inherit(dataset, property) +.El +.It Fn zfs.sync.inherit dataset property Clears the specified property in the given dataset, causing it to be inherited from an ancestor, or restored to the default if no ancestor property is set. The -.Ql zfs inherit -S +.Nm zfs Cm inherit Fl S option has not been implemented. Returns 0 on success, or a nonzero error code if the property could not be cleared. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar dataset Pq string Filesystem or snapshot containing the property to clear. -.Ed -.Pp -property (string) -.Bd -ragged -compact -offset "xxxx" +.It Ar property Pq string The property to clear. Allowed properties are the same as those for the .Nm zfs Cm inherit command. -.Ed -.It Em zfs.sync.promote(dataset) +.El +.It Fn zfs.sync.promote dataset Promote the given clone to a filesystem. Returns 0 on successful promotion, or a nonzero error code otherwise. If EEXIST is returned, the second return value will be an array of the clone's snapshots whose names collide with snapshots of the parent filesystem. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar dataset Pq string Clone to be promoted. -.Ed -.It Em zfs.sync.rollback(filesystem) +.El +.It Fn zfs.sync.rollback filesystem Rollback to the previous snapshot for a dataset. Returns 0 on successful rollback, or a nonzero error code otherwise. Rollbacks can be performed on filesystems or zvols, but not on snapshots or mounted datasets. EBUSY is returned in the case where the filesystem is mounted. .Pp -filesystem (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar filesystem Pq string Filesystem to rollback. -.Ed -.It Em zfs.sync.set_prop(dataset, property, value) +.El +.It Fn zfs.sync.set_prop dataset property value Sets the given property on a dataset. Currently only user properties are supported. Returns 0 if the property was set, or a nonzero error code otherwise. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar dataset Pq string The dataset where the property will be set. -.Ed -.Pp -property (string) -.Bd -ragged -compact -offset "xxxx" +.It Ar property Pq string The property to set. -Only user properties are supported. -.Ed -.Pp -value (string) -.Bd -ragged -compact -offset "xxxx" +.It Ar value Pq string The value of the property to be set. -.Ed -.It Em zfs.sync.snapshot(dataset) +.El +.It Fn zfs.sync.snapshot dataset Create a snapshot of a filesystem. Returns 0 if the snapshot was successfully created, and a nonzero error code otherwise. .Pp Note: Taking a snapshot will fail on any pool older than legacy version 27. To enable taking snapshots from ZCP scripts, the pool must be upgraded. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar dataset Pq string Name of snapshot to create. -.Ed -.It Em zfs.sync.bookmark(source, newbookmark) +.El +.It Fn zfs.sync.bookmark source newbookmark Create a bookmark of an existing source snapshot or bookmark. Returns 0 if the new bookmark was successfully created, and a nonzero error code otherwise. .Pp Note: Bookmarking requires the corresponding pool feature to be enabled. .Pp -source (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "newbookmark (string)" +.It Ar source Pq string Full name of the existing snapshot or bookmark. -.Ed -.Pp -newbookmark (string) -.Bd -ragged -compact -offset "xxxx" +.It Ar newbookmark Pq string Full name of the new bookmark. .El -.Ed +.El .It Sy zfs.check submodule -For each function in the zfs.sync submodule, there is a corresponding zfs.check +For each function in the +.Sy zfs.sync +submodule, there is a corresponding +.Sy zfs.check function which performs a "dry run" of the same operation. -Each takes the same arguments as its zfs.sync counterpart and returns 0 if the -operation would succeed, or a non-zero error code if it would fail, along with -any other error details. +Each takes the same arguments as its +.Sy zfs.sync +counterpart and returns 0 if the operation would succeed, +or a non-zero error code if it would fail, along with any other error details. That is, each has the same behavior as the corresponding sync function except for actually executing the requested change. For example, -.Em zfs.check.destroy("fs") +.Fn zfs.check.destroy \&"fs" returns 0 if -.Em zfs.sync.destroy("fs") +.Fn zfs.sync.destroy \&"fs" would successfully destroy the dataset. .Pp -The available zfs.check functions are: -.Bl -tag -width "xx" -.It Em zfs.check.destroy(dataset, [defer=true|false]) -.It Em zfs.check.promote(dataset) -.It Em zfs.check.rollback(filesystem) -.It Em zfs.check.set_property(dataset, property, value) -.It Em zfs.check.snapshot(dataset) +The available +.Sy zfs.check +functions are: +.Bl -tag -compact -width "xx" +.It Sy zfs.check.destroy Ns Pq Ar dataset , Op Ar defer Ns = Ns Sy true Ns | Ns Sy false +.It Fn zfs.check.promote dataset +.It Fn zfs.check.rollback filesystem +.It Fn zfs.check.set_property dataset property value +.It Fn zfs.check.snapshot dataset .El .It Sy zfs.list submodule The zfs.list submodule provides functions for iterating over datasets and properties. Rather than returning tables, these functions act as Lua iterators, and are generally used as follows: -.Bd -literal -offset indent -for child in zfs.list.children("rpool") do +.Bd -literal -compact -offset indent +.No for child in Fn zfs.list.children \&"rpool" No do ... end .Ed .Pp -The available zfs.list functions are: +The available +.Sy zfs.list +functions are: .Bl -tag -width "xx" -.It Em zfs.list.clones(snapshot) +.It Fn zfs.list.clones snapshot Iterate through all clones of the given snapshot. .Pp -snapshot (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar snapshot Pq string Must be a valid snapshot path in the current pool. -.Ed -.It Em zfs.list.snapshots(dataset) +.El +.It Fn zfs.list.snapshots dataset Iterate through all snapshots of the given dataset. -Each snapshot is returned as a string containing the full dataset name, e.g. -"pool/fs@snap". +Each snapshot is returned as a string containing the full dataset name, +e.g. "pool/fs@snap". .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar dataset Pq string Must be a valid filesystem or volume. -.Ed -.It Em zfs.list.children(dataset) +.El +.It Fn zfs.list.children dataset Iterate through all direct children of the given dataset. -Each child is returned as a string containing the full dataset name, e.g. -"pool/fs/child". +Each child is returned as a string containing the full dataset name, +e.g. "pool/fs/child". .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar dataset Pq string Must be a valid filesystem or volume. -.Ed -.It Em zfs.list.bookmarks(dataset) -Iterate through all bookmarks of the given dataset. Each bookmark is returned -as a string containing the full dataset name, e.g. "pool/fs#bookmark". +.El +.It Fn zfs.list.bookmarks dataset +Iterate through all bookmarks of the given dataset. +Each bookmark is returned as a string containing the full dataset name, +e.g. "pool/fs#bookmark". .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar dataset Pq string Must be a valid filesystem or volume. -.Ed -.It Em zfs.list.holds(snapshot) -Iterate through all user holds on the given snapshot. Each hold is returned +.El +.It Fn zfs.list.holds snapshot +Iterate through all user holds on the given snapshot. +Each hold is returned as a pair of the hold's tag and the timestamp (in seconds since the epoch) at which it was created. .Pp -snapshot (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar snapshot Pq string Must be a valid snapshot. -.Ed -.It Em zfs.list.properties(dataset) +.El +.It Fn zfs.list.properties dataset An alias for zfs.list.user_properties (see relevant entry). .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar dataset Pq string Must be a valid filesystem, snapshot, or volume. -.Ed -.It Em zfs.list.user_properties(dataset) -Iterate through all user properties for the given dataset. For each -step of the iteration, output the property name, its value, and its source. +.El +.It Fn zfs.list.user_properties dataset +Iterate through all user properties for the given dataset. +For each step of the iteration, output the property name, its value, +and its source. Throws a Lua error if the dataset is invalid. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar dataset Pq string Must be a valid filesystem, snapshot, or volume. -.Ed -.It Em zfs.list.system_properties(dataset) +.El +.It Fn zfs.list.system_properties dataset Returns an array of strings, the names of the valid system (non-user defined) properties for the given dataset. Throws a Lua error if the dataset is invalid. .Pp -dataset (string) -.Bd -ragged -compact -offset "xxxx" +.Bl -tag -compact -width "snapshot (string)" +.It Ar dataset Pq string Must be a valid filesystem, snapshot or volume. -.Ed .El .El +.El +. .Sh EXAMPLES +. .Ss Example 1 The following channel program recursively destroys a filesystem and all its snapshots and children in a naive manner. Note that this does not involve any error handling or reporting. .Bd -literal -offset indent function destroy_recursive(root) for child in zfs.list.children(root) do destroy_recursive(child) end for snap in zfs.list.snapshots(root) do zfs.sync.destroy(snap) end zfs.sync.destroy(root) end destroy_recursive("pool/somefs") .Ed +. .Ss Example 2 A more verbose and robust version of the same channel program, which properly detects and reports errors, and also takes the dataset to destroy as a command line argument, would be as follows: .Bd -literal -offset indent succeeded = {} failed = {} function destroy_recursive(root) for child in zfs.list.children(root) do destroy_recursive(child) end for snap in zfs.list.snapshots(root) do err = zfs.sync.destroy(snap) if (err ~= 0) then failed[snap] = err else succeeded[snap] = err end end err = zfs.sync.destroy(root) if (err ~= 0) then failed[root] = err else succeeded[root] = err end end args = ... argv = args["argv"] destroy_recursive(argv[1]) results = {} results["succeeded"] = succeeded results["failed"] = failed return results .Ed +. .Ss Example 3 The following function performs a forced promote operation by attempting to promote the given clone and destroying any conflicting snapshots. .Bd -literal -offset indent function force_promote(ds) errno, details = zfs.check.promote(ds) if (errno == EEXIST) then assert(details ~= Nil) for i, snap in ipairs(details) do zfs.sync.destroy(ds .. "@" .. snap) end elseif (errno ~= 0) then return errno end return zfs.sync.promote(ds) end .Ed diff --git a/man/man8/zfs-project.8 b/man/man8/zfs-project.8 index 21c300f83df1..f264a110fc00 100644 --- a/man/man8/zfs-project.8 +++ b/man/man8/zfs-project.8 @@ -1,153 +1,141 @@ .\" .\" 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 .\" 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 +.Dd May 27, 2021 .Dt ZFS-PROJECT 8 .Os +. .Sh NAME .Nm zfs-project -.Nd List, set, or clear project ID and/or inherit flag on the file(s) or directories. +.Nd manage projects in ZFS filesystem .Sh SYNOPSIS .Nm zfs .Cm project .Oo Fl d Ns | Ns Fl r Ns Oc -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Nm zfs .Cm project .Fl C .Oo Fl kr Ns Oc -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Nm zfs .Cm project .Fl c .Oo Fl 0 Ns Oc .Oo Fl d Ns | Ns Fl r Ns Oc .Op Fl p Ar id -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Nm zfs .Cm project .Op Fl p Ar id .Oo Fl rs Ns Oc -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm project .Oo Fl d Ns | Ns Fl r Ns Oc -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Xc -List project identifier (ID) and inherit flag of file(s) or directories. +List project identifier (ID) and inherit flag of files and directories. .Bl -tag -width "-d" .It Fl d -Show the directory project ID and inherit flag, not its children. It will -overwrite the former specified -.Fl r -option. +Show the directory project ID and inherit flag, not its children. .It Fl r -Show on subdirectories recursively. It will overwrite the former specified -.Fl d -option. +List subdirectories recursively. .El .It Xo .Nm zfs .Cm project .Fl C .Oo Fl kr Ns Oc -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Xc -Clear project inherit flag and/or ID on the file(s) or directories. +Clear project inherit flag and/or ID on the files and directories. .Bl -tag -width "-k" .It Fl k -Keep the project ID unchanged. If not specified, the project ID will be reset -as zero. +Keep the project ID unchanged. +If not specified, the project ID will be reset to zero. .It Fl r -Clear on subdirectories recursively. +Clear subdirectories' flags recursively. .El .It Xo .Nm zfs .Cm project .Fl c .Oo Fl 0 Ns Oc .Oo Fl d Ns | Ns Fl r Ns Oc .Op Fl p Ar id -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Xc -Check project ID and inherit flag on the file(s) or directories, report the -entries without project inherit flag or with different project IDs from the -specified (via -.Fl p -option) value or the target directory's project ID. -.Bl -tag -width "-0" +Check project ID and inherit flag on the files and directories: +report entries without the project inherit flag, or with project IDs different from the +target directory's project ID or the one specified with +.Fl p . +.Bl -tag -width "-p id" .It Fl 0 -Print file name with a trailing NUL instead of newline (by default), like -"find -print0". +Delimit filenames with a NUL byte instead of newline. .It Fl d -Check the directory project ID and inherit flag, not its children. It will -overwrite the former specified -.Fl r -option. -.It Fl p -Specify the referenced ID for comparing with the target file(s) or directories' -project IDs. If not specified, the target (top) directory's project ID will be -used as the referenced one. +Check the directory project ID and inherit flag, not its children. +.It Fl p Ar id +Compare to +.Ar id +instead of the target files and directories' project IDs. .It Fl r -Check on subdirectories recursively. It will overwrite the former specified -.Fl d -option. +Check subdirectories recursively. .El .It Xo .Nm zfs .Cm project -.Op Fl p Ar id +.Fl p Ar id .Oo Fl rs Ns Oc -.Ar file Ns | Ns Ar directory Ns ... +.Ar file Ns | Ns Ar directory Ns … .Xc -Set project ID and/or inherit flag on the file(s) or directories. -.Bl -tag -width "-p" -.It Fl p -Set the file(s)' or directories' project ID with the given value. +Set project ID and/or inherit flag on the files and directories. +.Bl -tag -width "-p id" +.It Fl p Ar id +Set the project ID to the given value. .It Fl r Set on subdirectories recursively. .It Fl s -Set project inherit flag on the given file(s) or directories. It is usually used -for setup tree quota on the directory target with -.Fl r -option specified together. When setup tree quota, by default the directory's -project ID will be set to all its descendants unless you specify the project -ID via -.Fl p -option explicitly. +Set project inherit flag on the given files and directories. +This is usually used for setting up tree quotas with +.Fl r . +In that case, the directory's project ID +will be set for all its descendants, unless specified explicitly with +.Fl p . .El .El +. .Sh SEE ALSO .Xr zfs-projectspace 8 diff --git a/man/man8/zfs-promote.8 b/man/man8/zfs-promote.8 index 64c124c11b61..ba8cd5f6da80 100644 --- a/man/man8/zfs-promote.8 +++ b/man/man8/zfs-promote.8 @@ -1,69 +1,64 @@ .\" .\" 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 .\" 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 ZFS-PROMOTE 8 .Os +. .Sh NAME .Nm zfs-promote -.Nd Promotes a clone file system to no longer be dependent on its origin snapshot. +.Nd promote clone dataset to no longer depend on origin snapshot .Sh SYNOPSIS .Nm zfs .Cm promote -.Ar clone-filesystem +.Ar clone +. .Sh DESCRIPTION -.Bl -tag -width "" -.It Xo -.Nm zfs -.Cm promote -.Ar clone-filesystem -.Xc The -.Cm promote -command makes it possible to destroy the file system that the clone was created -from. +.Nm zfs Cm promote +command makes it possible to destroy the dataset that the clone was created from. The clone parent-child dependency relationship is reversed, so that the origin -file system becomes a clone of the specified file system. +dataset becomes a clone of the specified dataset. .Pp The snapshot that was cloned, and any snapshots previous to this snapshot, are now owned by the promoted clone. -The space they use moves from the origin file system to the promoted clone, so +The space they use moves from the origin dataset to the promoted clone, so enough space must be available to accommodate these snapshots. No new space is consumed by this operation, but the space accounting is adjusted. The promoted clone must not have any conflicting snapshot names of its own. The -.Xr zfs-rename 8 +.Nm zfs Cm rename subcommand can be used to rename any conflicting snapshots. -.El +. .Sh SEE ALSO -.Xr zfs-clone 8 +.Xr zfs-clone 8 , +.Xr zfs-rename 8 diff --git a/man/man8/zfs-receive.8 b/man/man8/zfs-receive.8 index 36ed2050683a..ceb6e64ce571 100644 --- a/man/man8/zfs-receive.8 +++ b/man/man8/zfs-receive.8 @@ -1,385 +1,400 @@ .\" .\" 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 .\" 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 February 16, 2020 .Dt ZFS-RECEIVE 8 .Os +. .Sh NAME .Nm zfs-receive -.Nd Creates a snapshot whose contents are as specified in the stream provided on standard input. +.Nd create snapshot from backup stream .Sh SYNOPSIS .Nm zfs .Cm receive .Op Fl FhMnsuv .Op Fl o Sy origin Ns = Ns Ar snapshot .Op Fl o Ar property Ns = Ns Ar value .Op Fl x Ar property .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Nm zfs .Cm receive .Op Fl FhMnsuv .Op Fl d Ns | Ns Fl e .Op Fl o Sy origin Ns = Ns Ar snapshot .Op Fl o Ar property Ns = Ns Ar value .Op Fl x Ar property .Ar filesystem .Nm zfs .Cm receive .Fl A .Ar filesystem Ns | Ns Ar volume +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm receive .Op Fl FhMnsuv .Op Fl o Sy origin Ns = Ns Ar snapshot .Op Fl o Ar property Ns = Ns Ar value .Op Fl x Ar property .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Xc .It Xo .Nm zfs .Cm receive .Op Fl FhMnsuv .Op Fl d Ns | Ns Fl e .Op Fl o Sy origin Ns = Ns Ar snapshot .Op Fl o Ar property Ns = Ns Ar value .Op Fl x Ar property .Ar filesystem .Xc Creates a snapshot whose contents are as specified in the stream provided on standard input. If a full stream is received, then a new file system is created as well. Streams are created using the .Nm zfs Cm send subcommand, which by default creates a full stream. .Nm zfs Cm recv can be used as an alias for -.Nm zfs Cm receive. +.Nm zfs Cm receive . .Pp If an incremental stream is received, then the destination file system must already exist, and its most recent snapshot must match the incremental stream's source. For .Sy zvols , the destination device link is destroyed and recreated, which means the .Sy zvol cannot be accessed during the .Cm receive operation. .Pp When a snapshot replication package stream that is generated by using the .Nm zfs Cm send Fl R command is received, any snapshots that do not exist on the sending location are destroyed by using the .Nm zfs Cm destroy Fl d command. .Pp The ability to send and receive deduplicated send streams has been removed. However, a deduplicated send stream created with older software can be converted to a regular (non-deduplicated) stream by using the .Nm zstream Cm redup command. .Pp If .Fl o Em property Ns = Ns Ar value or .Fl x Em property is specified, it applies to the effective value of the property throughout -the entire subtree of replicated datasets. Effective property values will be -set ( -.Fl o -) or inherited ( -.Fl x -) on the topmost in the replicated subtree. In descendant datasets, if the +the entire subtree of replicated datasets. +Effective property values will be set +.Pq Fl o +or inherited +.Pq Fl x +on the topmost in the replicated subtree. +In descendant datasets, if the property is set by the send stream, it will be overridden by forcing the -property to be inherited from the top‐most file system. Received properties -are retained in spite of being overridden and may be restored with +property to be inherited from the top‐most file system. +Received properties are retained in spite of being overridden +and may be restored with .Nm zfs Cm inherit Fl S . Specifying .Fl o Sy origin Ns = Ns Em snapshot is a special case because, even if .Sy origin is a read-only property and cannot be set, it's allowed to receive the send stream as a clone of the given snapshot. .Pp Raw encrypted send streams (created with -.Nm zfs Cm send Fl w -) may only be received as is, and cannot be re-encrypted, decrypted, or -recompressed by the receive process. Unencrypted streams can be received as +.Nm zfs Cm send Fl w ) +may only be received as is, and cannot be re-encrypted, decrypted, or +recompressed by the receive process. +Unencrypted streams can be received as encrypted datasets, either through inheritance or by specifying encryption parameters with the .Fl o -options. Note that the +options. +Note that the .Sy keylocation property cannot be overridden to .Sy prompt -during a receive. This is because the receive process itself is already using -stdin for the send stream. Instead, the property can be overridden after the -receive completes. +during a receive. +This is because the receive process itself is already using +the standard input for the send stream. +Instead, the property can be overridden after the receive completes. .Pp The added security provided by raw sends adds some restrictions to the send -and receive process. ZFS will not allow a mix of raw receives and non-raw -receives. Specifically, any raw incremental receives that are attempted after -a non-raw receive will fail. Non-raw receives do not have this restriction and, -therefore, are always possible. Because of this, it is best practice to always +and receive process. +ZFS will not allow a mix of raw receives and non-raw receives. +Specifically, any raw incremental receives that are attempted after +a non-raw receive will fail. +Non-raw receives do not have this restriction and, +therefore, are always possible. +Because of this, it is best practice to always use either raw sends for their security benefits or non-raw sends for their flexibility when working with encrypted datasets, but not a combination. .Pp The reason for this restriction stems from the inherent restrictions of the -AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption, +AEAD ciphers that ZFS uses to encrypt data. +When using ZFS native encryption, each block of data is encrypted against a randomly generated number known as the "initialization vector" (IV), which is stored in the filesystem metadata. This number is required by the encryption algorithms whenever the data is to -be decrypted. Together, all of the IVs provided for all of the blocks in a -given snapshot are collectively called an "IV set". When ZFS performs a raw -send, the IV set is transferred from the source to the destination in the send -stream. When ZFS performs a non-raw send, the data is decrypted by the source +be decrypted. +Together, all of the IVs provided for all of the blocks in a +given snapshot are collectively called an "IV set". +When ZFS performs a raw send, the IV set is transferred from the source +to the destination in the send stream. +When ZFS performs a non-raw send, the data is decrypted by the source system and re-encrypted by the destination system, creating a snapshot with -effectively the same data, but a different IV set. In order for decryption to -work after a raw send, ZFS must ensure that the IV set used on both the source -and destination side match. When an incremental raw receive is performed on +effectively the same data, but a different IV set. +In order for decryption to work after a raw send, ZFS must ensure that +the IV set used on both the source and destination side match. +When an incremental raw receive is performed on top of an existing snapshot, ZFS will check to confirm that the "from" snapshot on both the source and destination were using the same IV set, ensuring the new IV set is consistent. .Pp The name of the snapshot .Pq and file system, if a full stream is received that this subcommand creates depends on the argument type and the use of the .Fl d or .Fl e options. .Pp If the argument is a snapshot name, the specified .Ar snapshot is created. If the argument is a file system or volume name, a snapshot with the same name as the sent snapshot is created within the specified .Ar filesystem or .Ar volume . If neither of the .Fl d or .Fl e options are specified, the provided target snapshot name is used exactly as provided. .Pp The .Fl d and .Fl e options cause the file system name of the target snapshot to be determined by appending a portion of the sent snapshot's name to the specified target .Ar filesystem . If the .Fl d option is specified, all but the first element of the sent snapshot's file system path .Pq usually the pool name is used and any required intermediate file systems within the specified one are created. If the .Fl e option is specified, then only the last element of the sent snapshot's file system name .Pq i.e. the name of the source file system itself is used as the target file system name. .Bl -tag -width "-F" .It Fl F Force a rollback of the file system to the most recent snapshot before performing the receive operation. If receiving an incremental replication stream .Po for example, one generated by .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I .Pc , destroy snapshots and file systems that do not exist on the sending side. .It Fl d Discard the first element of the sent snapshot's file system name, using the remaining elements to determine the name of the target file system for the new snapshot as described in the paragraph above. .It Fl e Discard all but the last element of the sent snapshot's file system name, using that element to determine the name of the target file system for the new snapshot as described in the paragraph above. .It Fl h -Skip the receive of holds. There is no effect if holds are not sent. +Skip the receive of holds. +There is no effect if holds are not sent. .It Fl M Force an unmount of the file system while receiving a snapshot. This option is not supported on Linux. .It Fl n Do not actually receive the stream. This can be useful in conjunction with the .Fl v option to verify the name the receive operation would use. .It Fl o Sy origin Ns = Ns Ar snapshot Forces the stream to be received as a clone of the given snapshot. If the stream is a full send stream, this will create the filesystem described by the stream as a clone of the specified snapshot. Which snapshot was specified will not affect the success or failure of the receive, as long as the snapshot does exist. If the stream is an incremental send stream, all the normal verification will be performed. .It Fl o Em property Ns = Ns Ar value Sets the specified property as if the command .Nm zfs Cm set Em property Ns = Ns Ar value -was invoked immediately before the receive. When receiving a stream from +was invoked immediately before the receive. +When receiving a stream from .Nm zfs Cm send Fl R , causes the property to be inherited by all descendant datasets, as through .Nm zfs Cm inherit Em property was run on any descendant datasets that have this property set on the sending system. .Pp If the send stream was sent with .Fl c then overriding the .Sy compression property will have no affect on received data but the .Sy compression -property will be set. To have the data recompressed on receive remove the +property will be set. +To have the data recompressed on receive remove the .Fl c flag from the send stream. .Pp -Any editable property can be set at receive time. Set-once properties bound +Any editable property can be set at receive time. +Set-once properties bound to the received data, such as .Sy normalization and .Sy casesensitivity , cannot be set at receive time even when the datasets are newly created by .Nm zfs Cm receive . Additionally both settable properties .Sy version and .Sy volsize cannot be set at receive time. .Pp The .Fl o -option may be specified multiple times, for different properties. An error -results if the same property is specified in multiple +option may be specified multiple times, for different properties. +An error results if the same property is specified in multiple .Fl o or .Fl x options. .Pp The .Fl o -option may also be used to override encryption properties upon initial -receive. This allows unencrypted streams to be received as encrypted datasets. +option may also be used to override encryption properties upon initial receive. +This allows unencrypted streams to be received as encrypted datasets. To cause the received dataset (or root dataset of a recursive stream) to be received as an encryption root, specify encryption properties in the same manner as is required for -.Nm zfs -.Cm create . +.Nm zfs Cm create . For instance: -.Bd -literal -# zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile -.Ed +.Dl # Nm zfs Cm send Pa tank/test@snap1 | Nm zfs Cm recv Fl o Sy encryption Ns = Ns Sy on Fl o keyformat=passphrase Fl o Sy keylocation Ns = Ns Pa file:///path/to/keyfile .Pp Note that -.Op Fl o Ar keylocation Ns = Ns Ar prompt -may not be specified here, since stdin is already being utilized for the send -stream. Once the receive has completed, you can use -.Nm zfs -.Cm set -to change this setting after the fact. Similarly, you can receive a dataset as -an encrypted child by specifying +.Fl o Sy keylocation Ns = Ns Sy prompt +may not be specified here, since the standard input +is already being utilized for the send stream. +Once the receive has completed, you can use +.Nm zfs Cm set +to change this setting after the fact. +Similarly, you can receive a dataset as an encrypted child by specifying .Op Fl x Ar encryption -to force the property to be inherited. Overriding encryption properties (except -for -.Sy keylocation Ns ) +to force the property to be inherited. +Overriding encryption properties (except for +.Sy keylocation ) is not possible with raw send streams. .It Fl s If the receive is interrupted, save the partially received state, rather than deleting it. Interruption may be due to premature termination of the stream .Po e.g. due to network failure or failure of the remote system if the stream is being read over a network connection .Pc , a checksum error in the stream, termination of the .Nm zfs Cm receive process, or unclean shutdown of the system. .Pp The receive can be resumed with a stream generated by .Nm zfs Cm send Fl t Ar token , where the .Ar token is the value of the .Sy receive_resume_token property of the filesystem or volume which is received into. .Pp To use this flag, the storage pool must have the .Sy extensible_dataset feature enabled. See .Xr zpool-features 5 for details on ZFS feature flags. .It Fl u File system that is associated with the received stream is not mounted. .It Fl v Print verbose information about the stream and the time required to perform the receive operation. .It Fl x Em property Ensures that the effective value of the specified property after the receive is unaffected by the value of that property in the send stream (if any), as if the property had been excluded from the send stream. .Pp If the specified property is not present in the send stream, this option does nothing. .Pp If a received property needs to be overridden, the effective value will be set or inherited, depending on whether the property is inheritable or not. .Pp In the case of an incremental update, .Fl x leaves any existing local setting or explicit inheritance unchanged. .Pp All .Fl o restrictions (e.g. set-once) apply equally to .Fl x . .El .It Xo .Nm zfs .Cm receive .Fl A .Ar filesystem Ns | Ns Ar volume .Xc Abort an interrupted .Nm zfs Cm receive Fl s , deleting its saved partially received state. .El +. .Sh SEE ALSO -.Xr zfs-send 8 +.Xr zfs-send 8 , .Xr zstream 8 diff --git a/man/man8/zfs-rename.8 b/man/man8/zfs-rename.8 index f57bcd8441f4..6caee50657ee 100644 --- a/man/man8/zfs-rename.8 +++ b/man/man8/zfs-rename.8 @@ -1,122 +1,123 @@ .\" .\" 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 .\" 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 September 1, 2020 .Dt ZFS-RENAME 8 .Os +. .Sh NAME .Nm zfs-rename -.Nd Renames the given dataset (filesystem or snapshot). +.Nd rename ZFS dataset .Sh SYNOPSIS .Nm zfs .Cm rename .Op Fl f .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Nm zfs .Cm rename .Fl p .Op Fl f .Ar filesystem Ns | Ns Ar volume .Ar filesystem Ns | Ns Ar volume .Nm zfs .Cm rename .Fl u .Op Fl f .Ar filesystem Ar filesystem .Nm zfs .Cm rename .Fl r .Ar snapshot Ar snapshot +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm rename .Op Fl f .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Xc .It Xo .Nm zfs .Cm rename .Fl p .Op Fl f .Ar filesystem Ns | Ns Ar volume .Ar filesystem Ns | Ns Ar volume .Xc .It Xo .Nm zfs .Cm rename .Fl u .Op Fl f .Ar filesystem .Ar filesystem .Xc Renames the given dataset. The new target can be located anywhere in the ZFS hierarchy, with the exception of snapshots. Snapshots can only be renamed within the parent file system or volume. When renaming a snapshot, the parent file system of the snapshot does not need to be specified as part of the second argument. Renamed file systems can inherit new mount points, in which case they are unmounted and remounted at the new mount point. .Bl -tag -width "-a" .It Fl f Force unmount any file systems that need to be unmounted in the process. This flag has no effect if used together with the .Fl u flag. .It Fl p Creates all the nonexistent parent datasets. Datasets created in this manner are automatically mounted according to the .Sy mountpoint property inherited from their parent. .It Fl u Do not remount file systems during rename. If a file system's .Sy mountpoint property is set to .Sy legacy or .Sy none , the file system is not unmounted even if this option is not given. .El .It Xo .Nm zfs .Cm rename .Fl r .Ar snapshot Ar snapshot .Xc Recursively rename the snapshots of all descendent datasets. Snapshots are the only dataset that can be renamed recursively. .El diff --git a/man/man8/zfs-rollback.8 b/man/man8/zfs-rollback.8 index 8a7cb6621fae..08e914b47659 100644 --- a/man/man8/zfs-rollback.8 +++ b/man/man8/zfs-rollback.8 @@ -1,81 +1,75 @@ .\" .\" 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 .\" 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 +.Dd May 27, 2021 .Dt ZFS-ROLLBACK 8 .Os +. .Sh NAME .Nm zfs-rollback -.Nd Roll back the given dataset to a previous snapshot. +.Nd roll ZFS dataset back to snapshot .Sh SYNOPSIS .Nm zfs .Cm rollback .Op Fl Rfr .Ar snapshot +. .Sh DESCRIPTION -.Bl -tag -width "" -.It Xo -.Nm zfs -.Cm rollback -.Op Fl Rfr -.Ar snapshot -.Xc When a dataset is rolled back, all data that has changed since the snapshot is discarded, and the dataset reverts to the state at the time of the snapshot. By default, the command refuses to roll back to a snapshot other than the most recent one. In order to do so, all intermediate snapshots and bookmarks must be destroyed by specifying the .Fl r option. .Pp The .Fl rR options do not recursively destroy the child snapshots of a recursive snapshot. Only direct snapshots of the specified filesystem are destroyed by either of these options. -To completely roll back a recursive snapshot, you must rollback the individual +To completely roll back a recursive snapshot, you must roll back the individual child snapshots. .Bl -tag -width "-R" .It Fl R Destroy any more recent snapshots and bookmarks, as well as any clones of those snapshots. .It Fl f Used with the .Fl R option to force an unmount of any clone file systems that are to be destroyed. .It Fl r Destroy any snapshots and bookmarks more recent than the one specified. .El -.El +. .Sh SEE ALSO .Xr zfs-snapshot 8 diff --git a/man/man8/zfs-send.8 b/man/man8/zfs-send.8 index 5a072c18527a..47b6c47ad03e 100644 --- a/man/man8/zfs-send.8 +++ b/man/man8/zfs-send.8 @@ -1,620 +1,648 @@ .\" .\" 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 .\" 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 April 15, 2021 .Dt ZFS-SEND 8 .Os +. .Sh NAME .Nm zfs-send -.Nd Generate a send stream, which may be of a filesystem, and may be incremental from a bookmark. +.Nd generate backup stream of ZFS dataset .Sh SYNOPSIS .Nm zfs .Cm send .Op Fl DLPRbcehnpsvw .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Nm zfs .Cm send .Op Fl DLPRcenpsvw .Op Fl i Ar snapshot Ns | Ns Ar bookmark .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Nm zfs .Cm send .Fl -redact Ar redaction_bookmark .Op Fl DLPcenpv -.br .Op Fl i Ar snapshot Ns | Ns Ar bookmark .Ar snapshot .Nm zfs .Cm send .Op Fl Penv .Fl t .Ar receive_resume_token .Nm zfs .Cm send .Op Fl Pnv .Fl S Ar filesystem .Nm zfs .Cm redact .Ar snapshot redaction_bookmark -.Ar redaction_snapshot Ns ... +.Ar redaction_snapshot Ns … +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm send .Op Fl DLPRbcehnpvw .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot .Ar snapshot .Xc Creates a stream representation of the second .Ar snapshot , which is written to standard output. The output can be redirected to a file or to a different system .Po for example, using .Xr ssh 1 .Pc . By default, a full stream is generated. .Bl -tag -width "-D" -.It Fl D, -dedup +.It Fl D , -dedup Deduplicated send is no longer supported. This flag is accepted for backwards compatibility, but a regular, non-deduplicated stream will be generated. .It Fl I Ar snapshot Generate a stream package that sends all intermediary snapshots from the first snapshot to the second snapshot. For example, .Fl I Em @a Em fs@d is similar to .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d . The incremental source may be specified as with the .Fl i option. -.It Fl L, -large-block +.It Fl L , -large-block Generate a stream which may contain blocks larger than 128KB. This flag has no effect if the .Sy large_blocks pool feature is disabled, or if the .Sy recordsize property of this filesystem has never been set above 128KB. The receiving system must have the .Sy large_blocks pool feature enabled as well. See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy large_blocks feature. -.It Fl P, -parsable +.It Fl P , -parsable Print machine-parsable verbose information about the stream package generated. -.It Fl R, -replicate +.It Fl R , -replicate Generate a replication stream package, which will replicate the specified file system, and all descendent file systems, up to the named snapshot. When received, all properties, snapshots, descendent file systems, and clones are preserved. .Pp If the .Fl i or .Fl I flags are used in conjunction with the .Fl R flag, an incremental replication stream is generated. The current values of properties, and current snapshot and file system names are set when the stream is received. If the .Fl F flag is specified when this stream is received, snapshots and file systems that -do not exist on the sending side are destroyed. If the +do not exist on the sending side are destroyed. +If the .Fl R flag is used to send encrypted datasets, then .Fl w must also be specified. -.It Fl e, -embed +.It Fl e , -embed Generate a more compact stream by using .Sy WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the .Sy embedded_data pool feature. This flag has no effect if the .Sy embedded_data feature is disabled. The receiving system must have the .Sy embedded_data feature enabled. If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have -that feature enabled as well. Datasets that are sent with this flag may not be +that feature enabled as well. +Datasets that are sent with this flag may not be received as an encrypted dataset, since encrypted datasets cannot use the .Sy embedded_data feature. See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy embedded_data feature. -.It Fl b, -backup +.It Fl b , -backup Sends only received property values whether or not they are overridden by local -settings, but only if the dataset has ever been received. Use this option when -you want +settings, but only if the dataset has ever been received. +Use this option when you want .Nm zfs Cm receive to restore received properties backed up on the sent dataset and to avoid sending local settings that may have nothing to do with the source dataset, but only with how the data is backed up. -.It Fl c, -compressed +.It Fl c , -compressed Generate a more compact stream by using compressed WRITE records for blocks which are compressed on disk and in memory .Po see the .Sy compression property for details .Pc . If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have that feature enabled as well. If the .Sy large_blocks feature is enabled on the sending system but the .Fl L option is not supplied in conjunction with .Fl c , then the data will be decompressed before sending so it can be split into -smaller block sizes. Streams sent with +smaller block sizes. +Streams sent with .Fl c will not have their data recompressed on the receiver side using -.Fl o compress=value. -The data will stay compressed as it was from the sender. The new compression -property will be set for future data. -.It Fl w, -raw -For encrypted datasets, send data exactly as it exists on disk. This allows -backups to be taken even if encryption keys are not currently loaded. The -backup may then be received on an untrusted machine since that machine will +.Fl o Sy compress Ns = Ar value . +The data will stay compressed as it was from the sender. +The new compression property will be set for future data. +.It Fl w , -raw +For encrypted datasets, send data exactly as it exists on disk. +This allows backups to be taken even if encryption keys are not currently loaded. +The backup may then be received on an untrusted machine since that machine will not have the encryption keys to read the protected data or alter it without -being detected. Upon being received, the dataset will have the same encryption +being detected. +Upon being received, the dataset will have the same encryption keys as it did on the send side, although the .Sy keylocation property will be defaulted to .Sy prompt -if not otherwise provided. For unencrypted datasets, this flag will be -equivalent to +if not otherwise provided. +For unencrypted datasets, this flag will be equivalent to .Fl Lec . Note that if you do not use this flag for sending encrypted datasets, data will be sent unencrypted and may be re-encrypted with a different encryption key on the receiving system, which will disable the ability to do a raw send to that system for incrementals. -.It Fl h, -holds +.It Fl h , -holds Generate a stream package that includes any snapshot holds (created with the -.Sy zfs hold +.Nm zfs Cm hold command), and indicating to -.Sy zfs receive +.Nm zfs Cm receive that the holds be applied to the dataset on the receiving system. .It Fl i Ar snapshot Generate an incremental stream from the first .Ar snapshot .Pq the incremental source to the second .Ar snapshot .Pq the incremental target . The incremental source can be specified as the last component of the snapshot name .Po the .Sy @ character and following .Pc and it is assumed to be from the same file system as the incremental target. .Pp If the destination is a clone, the source may be the origin snapshot, which must be fully specified .Po for example, .Em pool/fs@origin , not just .Em @origin .Pc . -.It Fl n, -dryrun +.It Fl n , -dryrun Do a dry-run .Pq Qq No-op send. Do not generate any actual send data. This is useful in conjunction with the .Fl v or .Fl P flags to determine what data will be sent. In this case, the verbose output will be written to standard output .Po contrast with a non-dry-run, where the stream is written to standard output and the verbose output goes to standard error .Pc . -.It Fl p, -props +.It Fl p , -props Include the dataset's properties in the stream. This flag is implicit when .Fl R is specified. -The receiving system must also support this feature. Sends of encrypted datasets -must use +The receiving system must also support this feature. +Sends of encrypted datasets must use .Fl w when using this flag. -.It Fl s, -skip-missing +.It Fl s , -skip-missing Allows sending a replication stream even when there are snapshots missing in the -hierarchy. When a snapshot is missing, instead of throwing an error and aborting -the send, a warning is printed to STDERR and the dataset to which it belongs -and its descendents are skipped. This flag can only be used in conjunction with +hierarchy. +When a snapshot is missing, instead of throwing an error and aborting the send, +a warning is printed to the standard error stream and the dataset to which it belongs +and its descendents are skipped. +This flag can only be used in conjunction with .Fl R . -.It Fl v, -verbose +.It Fl v , -verbose Print verbose information about the stream package generated. This information includes a per-second report of how much data has been sent. .Pp The format of the stream is committed. You will be able to receive your streams on future versions of ZFS. .El .It Xo .Nm zfs .Cm send .Op Fl DLPRcenpvw .Op Fl i Ar snapshot Ns | Ns Ar bookmark .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot .Xc Generate a send stream, which may be of a filesystem, and may be incremental from a bookmark. If the destination is a filesystem or volume, the pool must be read-only, or the filesystem must not be mounted. When the stream generated from a filesystem or volume is received, the default snapshot name will be .Qq --head-- . .Bl -tag -width "-L" -.It Fl L, -large-block +.It Fl L , -large-block Generate a stream which may contain blocks larger than 128KB. This flag has no effect if the .Sy large_blocks pool feature is disabled, or if the .Sy recordsize property of this filesystem has never been set above 128KB. The receiving system must have the .Sy large_blocks pool feature enabled as well. See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy large_blocks feature. -.It Fl P, -parsable +.It Fl P , -parsable Print machine-parsable verbose information about the stream package generated. -.It Fl c, -compressed +.It Fl c , -compressed Generate a more compact stream by using compressed WRITE records for blocks which are compressed on disk and in memory .Po see the .Sy compression property for details .Pc . If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have that feature enabled as well. If the .Sy large_blocks feature is enabled on the sending system but the .Fl L option is not supplied in conjunction with .Fl c , then the data will be decompressed before sending so it can be split into smaller block sizes. -.It Fl w, -raw -For encrypted datasets, send data exactly as it exists on disk. This allows -backups to be taken even if encryption keys are not currently loaded. The -backup may then be received on an untrusted machine since that machine will +.It Fl w , -raw +For encrypted datasets, send data exactly as it exists on disk. +This allows backups to be taken even if encryption keys are not currently loaded. +The backup may then be received on an untrusted machine since that machine will not have the encryption keys to read the protected data or alter it without -being detected. Upon being received, the dataset will have the same encryption +being detected. +Upon being received, the dataset will have the same encryption keys as it did on the send side, although the .Sy keylocation property will be defaulted to .Sy prompt -if not otherwise provided. For unencrypted datasets, this flag will be -equivalent to +if not otherwise provided. +For unencrypted datasets, this flag will be equivalent to .Fl Lec . Note that if you do not use this flag for sending encrypted datasets, data will be sent unencrypted and may be re-encrypted with a different encryption key on the receiving system, which will disable the ability to do a raw send to that system for incrementals. -.It Fl e, -embed +.It Fl e , -embed Generate a more compact stream by using .Sy WRITE_EMBEDDED records for blocks which are stored more compactly on disk by the .Sy embedded_data pool feature. This flag has no effect if the .Sy embedded_data feature is disabled. The receiving system must have the .Sy embedded_data feature enabled. If the .Sy lz4_compress feature is active on the sending system, then the receiving system must have -that feature enabled as well. Datasets that are sent with this flag may not be -received as an encrypted dataset, since encrypted datasets cannot use the +that feature enabled as well. +Datasets that are sent with this flag may not be received as an encrypted dataset, +since encrypted datasets cannot use the .Sy embedded_data feature. See .Xr zpool-features 5 for details on ZFS feature flags and the .Sy embedded_data feature. .It Fl i Ar snapshot Ns | Ns Ar bookmark Generate an incremental send stream. The incremental source must be an earlier snapshot in the destination's history. It will commonly be an earlier snapshot in the destination's file system, in which case it can be specified as the last component of the name .Po the .Sy # or .Sy @ character and following .Pc . .Pp If the incremental target is a clone, the incremental source can be the origin snapshot, or an earlier snapshot in the origin's filesystem, or the origin's origin, etc. -.It Fl n, -dryrun +.It Fl n , -dryrun Do a dry-run .Pq Qq No-op send. Do not generate any actual send data. This is useful in conjunction with the .Fl v or .Fl P flags to determine what data will be sent. In this case, the verbose output will be written to standard output .Po contrast with a non-dry-run, where the stream is written to standard output and the verbose output goes to standard error .Pc . -.It Fl v, -verbose +.It Fl v , -verbose Print verbose information about the stream package generated. This information includes a per-second report of how much data has been sent. .El .It Xo .Nm zfs .Cm send .Fl -redact Ar redaction_bookmark .Op Fl DLPcenpv -.br .Op Fl i Ar snapshot Ns | Ns Ar bookmark .Ar snapshot .Xc Generate a redacted send stream. This send stream contains all blocks from the snapshot being sent that aren't included in the redaction list contained in the bookmark specified by the .Fl -redact (or -.Fl -d -) flag. +.Fl d ) +flag. The resulting send stream is said to be redacted with respect to the snapshots the bookmark specified by the .Fl -redact No flag was created with. The bookmark must have been created by running -.Sy zfs redact +.Nm zfs Cm redact on the snapshot being sent. -.sp +.Pp This feature can be used to allow clones of a filesystem to be made available on a remote system, in the case where their parent need not (or needs to not) be usable. For example, if a filesystem contains sensitive data, and it has clones where that sensitive data has been secured or replaced with dummy data, redacted sends can be used to replicate the secured data without replicating the original sensitive data, while still sharing all possible blocks. A snapshot that has been redacted with respect to a set of snapshots will contain all blocks referenced by at least one snapshot in the set, but will contain none of the blocks referenced by none of the snapshots in the set. In other words, if all snapshots in the set have modified a given block in the parent, that block will not be sent; but if one or more snapshots have not modified a block in the parent, they will still reference the parent's block, so that block will be sent. Note that only user data will be redacted. -.sp +.Pp When the redacted send stream is received, we will generate a redacted snapshot. Due to the nature of redaction, a redacted dataset can only be used in the following ways: -.sp -1. To receive, as a clone, an incremental send from the original snapshot to one +.Bl -enum -width "a." +.It +To receive, as a clone, an incremental send from the original snapshot to one of the snapshots it was redacted with respect to. In this case, the stream will produce a valid dataset when received because all blocks that were redacted in the parent are guaranteed to be present in the child's send stream. This use case will produce a normal snapshot, which can be used just like other snapshots. -.sp -2. To receive an incremental send from the original snapshot to something +. +.It +To receive an incremental send from the original snapshot to something redacted with respect to a subset of the set of snapshots the initial snapshot was redacted with respect to. In this case, each block that was redacted in the original is still redacted (redacting with respect to additional snapshots causes less data to be redacted (because the snapshots define what is permitted, and everything else is redacted)). This use case will produce a new redacted snapshot. -.sp -3. To receive an incremental send from a redaction bookmark of the original +.It +To receive an incremental send from a redaction bookmark of the original snapshot that was created when redacting with respect to a subset of the set of snapshots the initial snapshot was created with respect to anything else. A send stream from such a redaction bookmark will contain all of the blocks necessary to fill in any redacted data, should it be needed, because the sending system is aware of what blocks were originally redacted. This will either produce a normal snapshot or a redacted one, depending on whether the new send stream is redacted. -.sp -4. To receive an incremental send from a redacted version of the initial +.It +To receive an incremental send from a redacted version of the initial snapshot that is redacted with respect to a subject of the set of snapshots the initial snapshot was created with respect to. A send stream from a compatible redacted dataset will contain all of the blocks necessary to fill in any redacted data. This will either produce a normal snapshot or a redacted one, depending on whether the new send stream is redacted. -.sp -5. To receive a full send as a clone of the redacted snapshot. +.It +To receive a full send as a clone of the redacted snapshot. Since the stream is a full send, it definitionally contains all the data needed to create a new dataset. This use case will either produce a normal snapshot or a redacted one, depending on whether the full send stream was redacted. -.sp -These restrictions are detected and enforced by \fBzfs receive\fR; a -redacted send stream will contain the list of snapshots that the stream is +.El +.Pp +These restrictions are detected and enforced by +.Nm zfs Cm receive ; +a redacted send stream will contain the list of snapshots that the stream is redacted with respect to. These are stored with the redacted snapshot, and are used to detect and -correctly handle the cases above. Note that for technical reasons, raw sends -and redacted sends cannot be combined at this time. +correctly handle the cases above. +Note that for technical reasons, +raw sends and redacted sends cannot be combined at this time. .It Xo .Nm zfs .Cm send .Op Fl Penv .Fl t .Ar receive_resume_token .Xc Creates a send stream which resumes an interrupted receive. The .Ar receive_resume_token is the value of this property on the filesystem or volume that was being received into. See the documentation for -.Sy zfs receive -s +.Nm zfs Cm receive Fl s for more details. .It Xo .Nm zfs .Cm send .Op Fl Pnv .Op Fl i Ar snapshot Ns | Ns Ar bookmark .Fl S .Ar filesystem .Xc Generate a send stream from a dataset that has been partially received. .Bl -tag -width "-L" -.It Fl S, -saved +.It Fl S , -saved This flag requires that the specified filesystem previously received a resumable -send that did not finish and was interrupted. In such scenarios this flag -enables the user to send this partially received state. Using this flag will -always use the last fully received snapshot as the incremental source if it -exists. +send that did not finish and was interrupted. +In such scenarios this flag +enables the user to send this partially received state. +Using this flag will always use the last fully received snapshot +as the incremental source if it exists. .El .It Xo .Nm zfs .Cm redact .Ar snapshot redaction_bookmark -.Ar redaction_snapshot Ns ... +.Ar redaction_snapshot Ns … .Xc Generate a new redaction bookmark. In addition to the typical bookmark information, a redaction bookmark contains the list of redacted blocks and the list of redaction snapshots specified. The redacted blocks are blocks in the snapshot which are not referenced by any of the redaction snapshots. These blocks are found by iterating over the metadata in each redaction snapshot to determine what has been changed since the target snapshot. Redaction is designed to support redacted zfs sends; see the entry for -.Sy zfs send +.Nm zfs Cm send for more information on the purpose of this operation. If a redact operation fails partway through (due to an error or a system failure), the redaction can be resumed by rerunning the same command. .El .Ss Redaction ZFS has support for a limited version of data subsetting, in the form of -redaction. Using the -.Sy zfs redact +redaction. +Using the +.Nm zfs Cm redact command, a .Sy redaction bookmark -can be created that stores a list of blocks containing sensitive information. When -provided to -.Sy zfs -.Sy send , +can be created that stores a list of blocks containing sensitive information. +When provided to +.Nm zfs Cm send , this causes a .Sy redacted send -to occur. Redacted sends omit the blocks containing sensitive information, -replacing them with REDACT records. When these send streams are received, a +to occur. +Redacted sends omit the blocks containing sensitive information, +replacing them with REDACT records. +When these send streams are received, a .Sy redacted dataset -is created. A redacted dataset cannot be mounted by default, since it is -incomplete. It can be used to receive other send streams. In this way datasets -can be used for data backup and replication, with all the benefits that zfs send -and receive have to offer, while protecting sensitive information from being +is created. +A redacted dataset cannot be mounted by default, since it is incomplete. +It can be used to receive other send streams. +In this way datasets can be used for data backup and replication, +with all the benefits that zfs send and receive have to offer, +while protecting sensitive information from being stored on less-trusted machines or services. .Pp -For the purposes of redaction, there are two steps to the process. A redact -step, and a send/receive step. First, a redaction bookmark is created. This is -done by providing the -.Sy zfs redact +For the purposes of redaction, there are two steps to the process. +A redact step, and a send/receive step. +First, a redaction bookmark is created. +This is done by providing the +.Nm zfs Cm redact command with a parent snapshot, a bookmark to be created, and a number of -redaction snapshots. These redaction snapshots must be descendants of the -parent snapshot, and they should modify data that is considered sensitive in -some way. Any blocks of data modified by all of the redaction snapshots will +redaction snapshots. +These redaction snapshots must be descendants of the parent snapshot, +and they should modify data that is considered sensitive in some way. +Any blocks of data modified by all of the redaction snapshots will be listed in the redaction bookmark, because it represents the truly sensitive -information. When it comes to the send step, the send process will not send +information. +When it comes to the send step, the send process will not send the blocks listed in the redaction bookmark, instead replacing them with -REDACT records. When received on the target system, this will create a +REDACT records. +When received on the target system, this will create a redacted dataset, missing the data that corresponds to the blocks in the -redaction bookmark on the sending system. The incremental send streams from +redaction bookmark on the sending system. +The incremental send streams from the original parent to the redaction snapshots can then also be received on the target system, and this will produce a complete snapshot that can be used -normally. Incrementals from one snapshot on the parent filesystem and another +normally. +Incrementals from one snapshot on the parent filesystem and another can also be done by sending from the redaction bookmark, rather than the snapshots themselves. .Pp -In order to make the purpose of the feature more clear, an example is -provided. Consider a zfs filesystem containing four files. These files -represent information for an online shopping service. One file contains a list -of usernames and passwords, another contains purchase histories, a third -contains click tracking data, and a fourth contains user preferences. The -owner of this data wants to make it available for their development teams to -test against, and their market research teams to do analysis on. The -development teams need information about user preferences and the click +In order to make the purpose of the feature more clear, an example is provided. +Consider a zfs filesystem containing four files. +These files represent information for an online shopping service. +One file contains a list of usernames and passwords, another contains purchase histories, +a third contains click tracking data, and a fourth contains user preferences. +The owner of this data wants to make it available for their development teams to +test against, and their market research teams to do analysis on. +The development teams need information about user preferences and the click tracking data, while the market research teams need information about purchase -histories and user preferences. Neither needs access to the usernames and -passwords. However, because all of this data is stored in one ZFS filesystem, -it must all be sent and received together. In addition, the owner of the data +histories and user preferences. +Neither needs access to the usernames and passwords. +However, because all of this data is stored in one ZFS filesystem, +it must all be sent and received together. +In addition, the owner of the data wants to take advantage of features like compression, checksumming, and -snapshots, so they do want to continue to use ZFS to store and transmit their -data. Redaction can help them do so. First, they would make two clones of a -snapshot of the data on the source. In one clone, they create the setup they -want their market research team to see; they delete the usernames and -passwords file, and overwrite the click tracking data with dummy -information. In another, they create the setup they want the development teams +snapshots, so they do want to continue to use ZFS to store and transmit their data. +Redaction can help them do so. +First, they would make two clones of a snapshot of the data on the source. +In one clone, they create the setup they want their market research team to see; +they delete the usernames and passwords file, +and overwrite the click tracking data with dummy information. +In another, they create the setup they want the development teams to see, by replacing the passwords with fake information and replacing the -purchase histories with randomly generated ones. They would then create a -redaction bookmark on the parent snapshot, using snapshots on the two clones -as redaction snapshots. The parent can then be sent, redacted, to the target -server where the research and development teams have access. Finally, -incremental sends from the parent snapshot to each of the clones can be send +purchase histories with randomly generated ones. +They would then create a redaction bookmark on the parent snapshot, +using snapshots on the two clones as redaction snapshots. +The parent can then be sent, redacted, to the target +server where the research and development teams have access. +Finally, incremental sends from the parent snapshot to each of the clones can be sent to and received on the target server; these snapshots are identical to the ones on the source, and are ready to be used, while the parent snapshot on the target contains none of the username and password data present on the source, because it was removed by the redacted send operation. +. .Sh SEE ALSO .Xr zfs-bookmark 8 , .Xr zfs-receive 8 , .Xr zfs-redact 8 , .Xr zfs-snapshot 8 diff --git a/man/man8/zfs-set.8 b/man/man8/zfs-set.8 index 74a7a61d0e29..83709fa6149c 100644 --- a/man/man8/zfs-set.8 +++ b/man/man8/zfs-set.8 @@ -1,188 +1,182 @@ .\" .\" 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 .\" 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 +.Dd June 2, 2021 .Dt ZFS-SET 8 .Os +. .Sh NAME .Nm zfs-set -.Nd Sets the property or list of properties to the given value(s) for each dataset. +.Nd set properties on ZFS datasets .Sh SYNOPSIS .Nm zfs .Cm set -.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns … +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns … .Nm zfs .Cm get .Op Fl r Ns | Ns Fl d Ar depth .Op Fl Hp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc -.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... -.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns … Oc +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc +.Cm all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns … +.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns … .Nm zfs .Cm inherit .Op Fl rS -.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns … +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm set -.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns … +.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns … .Xc Only some properties can be edited. See .Xr zfsprops 8 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 with a suffix of .Sy B , K , M , G , T , P , E , Z .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, or zettabytes, respectively .Pc . User properties can be set on snapshots. For more information, see the .Em User Properties section of .Xr zfsprops 8 . .It Xo .Nm zfs .Cm get .Op Fl r Ns | Ns Fl d Ar depth .Op Fl Hp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc -.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... -.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns … Oc +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc +.Cm all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns … +.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns … .Xc Displays properties for the given datasets. If no datasets are specified, then the command displays properties for all datasets on the system. For each property, the following columns are displayed: -.Bd -literal - name Dataset name - property Property name - value Property value - source Property source \fBlocal\fP, \fBdefault\fP, \fBinherited\fP, - \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP). -.Ed +.Bl -tag -compact -offset 4n -width "property" +.It Sy name +Dataset name +.It Sy property +Property name +.It Sy value +Property value +.It Sy source +Property source +.Sy local , default , inherited , temporary , received , No or Sy - Pq none . +.El .Pp All columns are displayed by default, though this can be controlled by using the .Fl o option. This command takes a comma-separated list of properties as described in the -.Em Native Properties +.Sx Native Properties and -.Em User Properties +.Sx User Properties sections of .Xr zfsprops 8 . .Pp The value .Sy all can be used to display all properties that apply to the given dataset's type -.Pq filesystem, volume, snapshot, or bookmark . -.Bl -tag -width "-H" +.Pq Sy filesystem , volume , snapshot , No or Sy bookmark . +.Bl -tag -width "-s source" .It Fl H Display output in a form more easily parsed by scripts. Any headers are omitted, and fields are explicitly separated by a single tab instead of an arbitrary amount of space. .It Fl d Ar depth Recursively display any children of the dataset, limiting the recursion to .Ar depth . A depth of .Sy 1 will display only the dataset and its direct children. .It Fl o Ar field -A comma-separated list of columns to display. -.Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source -is the default value. +A comma-separated list of columns to display, defaults to +.Sy name , Ns Sy property , Ns Sy value , Ns Sy source . .It Fl p Display numbers in parsable .Pq exact values. .It Fl r Recursively display properties for any children. .It Fl s Ar source A comma-separated list of sources to display. Those properties coming from a source other than those in this list are ignored. Each source must be one of the following: -.Sy local , -.Sy default , -.Sy inherited , -.Sy temporary , -.Sy received , -and -.Sy none . +.Sy local , default , inherited , temporary , received , No or Sy none . The default value is all sources. .It Fl t Ar type A comma-separated list of types to display, where .Ar type is one of -.Sy filesystem , -.Sy snapshot , -.Sy volume , -.Sy bookmark , -or -.Sy all . +.Sy filesystem , snapshot , volume , bookmark , No or Sy all . .El .It Xo .Nm zfs .Cm inherit .Op Fl rS -.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... +.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns … .Xc Clears the specified property, causing it to be inherited from an ancestor, 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 for a listing of default values, and details on which properties can be inherited. .Bl -tag -width "-r" .It Fl r Recursively inherit the given property for all children. .It Fl S Revert the property to the received value if one exists; otherwise operate as if the .Fl S option was not specified. .El .El +. .Sh SEE ALSO .Xr zfs-list 8 , .Xr zfsprops 8 diff --git a/man/man8/zfs-share.8 b/man/man8/zfs-share.8 index ce35accdbf7e..369f667c9d02 100644 --- a/man/man8/zfs-share.8 +++ b/man/man8/zfs-share.8 @@ -1,88 +1,90 @@ .\" .\" 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 .\" 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 ZFS-SHARE 8 .Os +. .Sh NAME .Nm zfs-share -.Nd Shares and unshares available ZFS filesystems. +.Nd share and unshare ZFS filesystems .Sh SYNOPSIS .Nm zfs .Cm share -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Nm zfs .Cm unshare -.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Fl a Ns | Ns Ar filesystem Ns | Ns Ar mountpoint +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm share -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Xc Shares available ZFS file systems. .Bl -tag -width "-a" .It Fl a Share all available ZFS file systems. Invoked automatically as part of the boot process. .It Ar filesystem Share the specified filesystem according to the .Sy sharenfs and .Sy sharesmb properties. File systems are shared when the .Sy sharenfs or .Sy sharesmb property is set. .El .It Xo .Nm zfs .Cm unshare -.Fl a | Ar filesystem Ns | Ns Ar mountpoint +.Fl a Ns | Ns Ar filesystem Ns | Ns Ar mountpoint .Xc Unshares currently shared ZFS file systems. .Bl -tag -width "-a" .It Fl a Unshare all available ZFS file systems. Invoked automatically as part of the shutdown process. .It Ar filesystem Ns | Ns Ar mountpoint Unshare the specified filesystem. The command can also be given a path to a ZFS file system shared on the system. .El .El +. .Sh SEE ALSO .Xr exports 5 , .Xr smb.conf 5 , .Xr zfsprops 8 diff --git a/man/man8/zfs-snapshot.8 b/man/man8/zfs-snapshot.8 index b677bc73d2bd..fdff39fbc4b8 100644 --- a/man/man8/zfs-snapshot.8 +++ b/man/man8/zfs-snapshot.8 @@ -1,83 +1,76 @@ .\" .\" 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 .\" 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 +.Dd May 27, 2021 .Dt ZFS-SNAPSHOT 8 .Os +. .Sh NAME .Nm zfs-snapshot -.Nd Creates snapshots with the given names. +.Nd create snapshots of ZFS datasets .Sh SYNOPSIS .Nm zfs .Cm snapshot .Op Fl r -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … +.Ar dataset Ns @ Ns Ar snapname Ns … +. .Sh DESCRIPTION -.Bl -tag -width "" -.It Xo -.Nm zfs -.Cm snapshot -.Op Fl r -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... -.Xc All previous modifications by successful system calls to the file system are part of the snapshots. Snapshots are taken atomically, so that all snapshots correspond to the same moment in time. .Nm zfs Cm snap can be used as an alias for -.Nm zfs Cm snapshot. +.Nm zfs Cm snapshot . See the -.Em Snapshots +.Sx Snapshots section of .Xr zfsconcepts 8 for details. .Bl -tag -width "-o" .It Fl o Ar property Ns = Ns Ar value -Sets the specified property; see +Set the specified property; see .Nm zfs Cm create for details. .It Fl r Recursively create snapshots of all descendent datasets .El -.El +. .Sh SEE ALSO .Xr zfs-bookmark 8 , .Xr zfs-clone 8 , .Xr zfs-destroy 8 , .Xr zfs-diff 8 , .Xr zfs-hold 8 , .Xr zfs-rename 8 , .Xr zfs-rollback 8 , .Xr zfs-send 8 diff --git a/man/man8/zfs-upgrade.8 b/man/man8/zfs-upgrade.8 index 6a79f3ea77fd..0ba276dc6ad5 100644 --- a/man/man8/zfs-upgrade.8 +++ b/man/man8/zfs-upgrade.8 @@ -1,106 +1,103 @@ .\" .\" 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 .\" 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 ZFS-UPGRADE 8 .Os +. .Sh NAME .Nm zfs-upgrade -.Nd Manage upgrading the on-disk version of filesystems. +.Nd manage on-disk version of ZFS filesystems .Sh SYNOPSIS .Nm zfs .Cm upgrade .Nm zfs .Cm upgrade .Fl v .Nm zfs .Cm upgrade .Op Fl r .Op Fl V Ar version -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm upgrade .Xc Displays a list of file systems that are not the most recent version. .It Xo .Nm zfs .Cm upgrade .Fl v .Xc Displays a list of currently supported file system versions. .It Xo .Nm zfs .Cm upgrade .Op Fl r .Op Fl V Ar version -.Fl a | Ar filesystem +.Fl a Ns | Ns Ar filesystem .Xc Upgrades file systems to a new on-disk version. Once this is done, the file systems will no longer be accessible on systems -running older versions of the software. +running older versions of ZFS. .Nm zfs Cm send streams generated from new snapshots of these file systems cannot be accessed on -systems running older versions of the software. +systems running older versions of ZFS. .Pp In general, the file system version is independent of the pool version. See -.Xr zpool 8 -for information on the -.Nm zpool Cm upgrade -command. +.Xr zpool-features 5 +for information on features of ZFS storage pools. .Pp In some cases, the file system version and the pool version are interrelated and the pool version must be upgraded before the file system version can be upgraded. -.Bl -tag -width "-V" +.Bl -tag -width "filesystem" .It Fl V Ar version -Upgrade to the specified +Upgrade to .Ar version . -If the -.Fl V -flag is not specified, this command upgrades to the most recent version. +If not specified, upgrade to the most recent version. This option can only be used to increase the version number, and only up to the most -recent version supported by this software. +recent version supported by this version of ZFS. .It Fl a Upgrade all file systems on all imported pools. .It Ar filesystem Upgrade the specified file system. .It Fl r Upgrade the specified file system and all descendent file systems. .El .El .Sh SEE ALSO .Xr zpool-upgrade 8 diff --git a/man/man8/zfs-userspace.8 b/man/man8/zfs-userspace.8 index 0a9977a61c6a..d09e35e1fdd8 100644 --- a/man/man8/zfs-userspace.8 +++ b/man/man8/zfs-userspace.8 @@ -1,187 +1,187 @@ .\" .\" 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 .\" 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 ZFS-USERSPACE 8 .Os +. .Sh NAME .Nm zfs-userspace -.Nd Displays space consumed by, and quotas on, each user or group in the specified filesystem or snapshot. +.Nd display space and quotas of ZFS dataset .Sh SYNOPSIS .Nm zfs .Cm userspace .Op Fl Hinp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar field Oc Ns … +.Oo Fl S Ar field Oc Ns … +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc .Ar filesystem Ns | Ns Ar snapshot Ns | Ns Ar path .Nm zfs .Cm groupspace .Op Fl Hinp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar field Oc Ns … +.Oo Fl S Ar field Oc Ns … +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc .Ar filesystem Ns | Ns Ar snapshot Ns | Ns Ar path .Nm zfs .Cm projectspace .Op Fl Hp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar field Oc Ns … +.Oo Fl S Ar field Oc Ns … .Ar filesystem Ns | Ns Ar snapshot Ns | Ns Ar path +. .Sh DESCRIPTION .Bl -tag -width "" .It Xo .Nm zfs .Cm userspace .Op Fl Hinp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar field Oc Ns … +.Oo Fl S Ar field Oc Ns … +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc .Ar filesystem Ns | Ns Ar snapshot Ns | Ns Ar path .Xc Displays space consumed by, and quotas on, each user in the specified filesystem, snapshot, or path. If a path is given, the filesystem that contains that path will be used. This corresponds to the .Sy userused@ Ns Em user , .Sy userobjused@ Ns Em user , -.Sy userquota@ Ns Em user, +.Sy userquota@ Ns Em user , and .Sy userobjquota@ Ns Em user properties. -.Bl -tag -width "-H" +.Bl -tag -width "-S field" .It Fl H Do not print headers, use tab-delimited output. .It Fl S Ar field Sort by this field in reverse order. See .Fl s . .It Fl i Translate SID to POSIX ID. The POSIX ID may be ephemeral if no mapping exists. Normal POSIX interfaces -.Po for example, -.Xr stat 2 , -.Nm ls Fl l -.Pc +.Pq like Xr stat 2 , Nm ls Fl l perform this translation, so the .Fl i option allows the output from .Nm zfs Cm userspace to be compared directly with those utilities. However, .Fl i may lead to confusion if some files were created by an SMB user before a SMB-to-POSIX name mapping was established. In such a case, some files will be owned by the SMB entity and some by the POSIX entity. However, the .Fl i option will report that the POSIX entity has the total usage and quota for both. .It Fl n Print numeric ID instead of user/group name. -.It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... +.It Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Display only the specified fields from the following set: .Sy type , .Sy name , .Sy used , .Sy quota . The default is to display all fields. .It Fl p Use exact .Pq parsable numeric output. .It Fl s Ar field Sort output by this field. The .Fl s and .Fl S flags may be specified multiple times to sort first by one field, then by another. The default is .Fl s Sy type Fl s Sy name . -.It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... +.It Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Print only the specified types from the following set: .Sy all , .Sy posixuser , .Sy smbuser , .Sy posixgroup , .Sy smbgroup . The default is -.Fl t Sy posixuser Ns \&, Ns Sy smbuser . +.Fl t Sy posixuser , Ns Sy smbuser . The default can be changed to include group types. .El .It Xo .Nm zfs .Cm groupspace .Op Fl Hinp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... -.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar field Oc Ns … +.Oo Fl S Ar field Oc Ns … +.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc .Ar filesystem Ns | Ns Ar snapshot .Xc Displays space consumed by, and quotas on, each group in the specified filesystem or snapshot. This subcommand is identical to .Cm userspace , except that the default types to display are -.Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . +.Fl t Sy posixgroup , Ns Sy smbgroup . .It Xo .Nm zfs .Cm projectspace .Op Fl Hp -.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc -.Oo Fl s Ar field Oc Ns ... -.Oo Fl S Ar field Oc Ns ... +.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns … Oc +.Oo Fl s Ar field Oc Ns … +.Oo Fl S Ar field Oc Ns … .Ar filesystem Ns | Ns Ar snapshot Ns | Ns Ar path .Xc Displays space consumed by, and quotas on, each project in the specified -filesystem or snapshot. This subcommand is identical to +filesystem or snapshot. +This subcommand is identical to .Cm userspace , -except that the project identifier is numeral, not name. So need neither -the option -.Sy -i +except that the project identifier is a numeral, not a name. +So need neither the option +.Fl i for SID to POSIX ID nor -.Sy -n +.Fl n for numeric ID, nor -.Sy -t +.Fl t for types. .El +. .Sh SEE ALSO .Xr zfs-set 8 , .Xr zfsprops 8 diff --git a/man/man8/zfs.8 b/man/man8/zfs.8 index 6499ea471753..16c874eb20de 100644 --- a/man/man8/zfs.8 +++ b/man/man8/zfs.8 @@ -1,777 +1,773 @@ .\" .\" 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 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. .\" Copyright (c) 2011, Pawel Jakub Dawidek .\" Copyright (c) 2012, Glen Barber .\" Copyright (c) 2012, Bryan Drewery .\" Copyright (c) 2013, Steven Hartland .\" 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) 2014, Xin LI .\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved. .\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved. .\" Copyright 2019 Richard Laager. All rights reserved. .\" Copyright 2018 Nexenta Systems, Inc. .\" Copyright 2019 Joyent, Inc. .\" .Dd June 30, 2019 .Dt ZFS 8 .Os +. .Sh NAME .Nm zfs -.Nd configures ZFS file systems +.Nd configure ZFS datasets .Sh SYNOPSIS .Nm .Fl ?V .Nm .Cm version .Nm -.Cm -.Op Ar +.Cm subcommand +.Op Ar arguments +. .Sh DESCRIPTION The .Nm command configures ZFS datasets within a ZFS storage pool, as described in .Xr zpool 8 . A dataset is identified by a unique path within the ZFS namespace. For example: -.Bd -literal -pool/{filesystem,volume,snapshot} -.Ed +.Dl pool/{filesystem,volume,snapshot} .Pp where the maximum length of a dataset name is -.Dv MAXNAMELEN -.Pq 256 bytes +.Sy MAXNAMELEN Pq 256B and the maximum amount of nesting allowed in a path is 50 levels deep. .Pp A dataset can be one of the following: -.Bl -tag -width "file system" +.Bl -tag -offset Ds -width "file system" .It Sy file system -A ZFS dataset of type -.Sy filesystem -can be mounted within the standard system namespace and behaves like other file +Can be mounted within the standard system namespace and behaves like other file systems. -While ZFS file systems are designed to be POSIX compliant, known issues exist +While ZFS file systems are designed to be POSIX-compliant, known issues exist that prevent compliance in some cases. Applications that depend on standards conformance might fail due to non-standard behavior when checking file system free space. .It Sy volume A logical volume exported as a raw or block device. This type of dataset should only be used when a block device is required. File systems are typically used in most environments. .It Sy snapshot A read-only version of a file system or volume at a given point in time. It is specified as .Ar filesystem Ns @ Ns Ar name or .Ar volume Ns @ Ns Ar name . .It Sy bookmark Much like a .Sy snapshot , but without the hold on on-disk data. -It can be used as the source of a send (but not for a receive). It is specified as +It can be used as the source of a send (but not for a receive). +It is specified as .Ar filesystem Ns # Ns Ar name or .Ar volume Ns # Ns Ar name . .El .Pp -For details see -.Xr zfsconcepts 8 . +See +.Xr zfsconcepts 8 +for details. +. .Ss Properties -Properties are divided into two types, native properties and user-defined -.Po or -.Qq user -.Pc +Properties are divided into two types: native properties and user-defined +.Pq or Qq user 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 properties, see the -.Xr zfsprops 8 man page. +For more information about properties, see +.Xr zfsprops 8 . +. .Ss Encryption Enabling the .Sy encryption feature allows for the creation of encrypted filesystems and volumes. ZFS will encrypt file and zvol data, file attributes, ACLs, permission bits, directory listings, FUID mappings, and -.Sy userused -/ -.Sy groupused +.Sy userused Ns / Ns Sy groupused Ns / Ns Sy projectused data. -For an overview of encryption see the -.Xr zfs-load-key 8 command manual. +For an overview of encryption, see +.Xr zfs-load-key 8 . +. .Sh SUBCOMMANDS All subcommands that modify state are logged persistently to the pool in their original form. .Bl -tag -width "" .It Nm Fl ? Displays a help message. .It Xo .Nm .Fl V , -version .Xc -An alias for the -.Nm zfs Cm version -subcommand. .It Xo .Nm .Cm version .Xc Displays the software version of the .Nm userland utility and the zfs kernel module. .El +. .Ss Dataset Management .Bl -tag -width "" .It Xr zfs-list 8 Lists the property information for the given datasets in tabular form. .It Xr zfs-create 8 Creates a new ZFS file system or volume. .It Xr zfs-destroy 8 Destroys the given dataset(s), snapshot(s), or bookmark. .It Xr zfs-rename 8 Renames the given dataset (filesystem or snapshot). .It Xr zfs-upgrade 8 Manage upgrading the on-disk version of filesystems. .El +. .Ss Snapshots .Bl -tag -width "" .It Xr zfs-snapshot 8 Creates snapshots with the given names. .It Xr zfs-rollback 8 Roll back the given dataset to a previous snapshot. -.It Xo -.Xr zfs-hold 8 / -.Xr zfs-release 8 -.Xc +.It Xr zfs-hold 8 Ns / Ns Xr zfs-release 8 Add or remove a hold reference to the specified snapshot or snapshots. If a hold exists on a snapshot, attempts to destroy that snapshot by using the .Nm zfs Cm destroy command return -.Er EBUSY . +.Sy EBUSY . .It Xr zfs-diff 8 Display the difference between a snapshot of a given filesystem and another snapshot of that filesystem from a later time or the current contents of the filesystem. .El +. .Ss Clones .Bl -tag -width "" .It Xr zfs-clone 8 Creates a clone of the given snapshot. .It Xr zfs-promote 8 Promotes a clone file system to no longer be dependent on its .Qq origin snapshot. .El +. .Ss Send & Receive .Bl -tag -width "" .It Xr zfs-send 8 Generate a send stream, which may be of a filesystem, and may be incremental from a bookmark. .It Xr zfs-receive 8 Creates a snapshot whose contents are as specified in the stream provided on standard input. If a full stream is received, then a new file system is created as well. Streams are created using the .Xr zfs-send 8 subcommand, which by default creates a full stream. .It Xr zfs-bookmark 8 Creates a new bookmark of the given snapshot or bookmark. Bookmarks mark the point in time when the snapshot was created, and can be used as the incremental source for a .Nm zfs Cm send command. .It Xr zfs-redact 8 Generate a new redaction bookmark. This feature can be used to allow clones of a filesystem to be made available on a remote system, in the case where their parent need not (or needs to not) be usable. .El +. .Ss Properties .Bl -tag -width "" .It Xr zfs-get 8 Displays properties for the given datasets. .It Xr zfs-set 8 Sets the property or list of properties to the given value(s) for each dataset. .It Xr zfs-inherit 8 Clears the specified property, causing it to be inherited from an ancestor, restored to default if no ancestor has the property set, or with the .Fl S option reverted to the received value if one exists. .El +. .Ss Quotas .Bl -tag -width "" -.It Xo -.Xr zfs-userspace 8 / -.Xr zfs-groupspace 8 / -.Xr zfs-projectspace 8 -.Xc +.It Xr zfs-userspace 8 Ns / Ns Xr zfs-groupspace 8 Ns / Ns Xr zfs-projectspace 8 Displays space consumed by, and quotas on, each user, group, or project in the specified filesystem or snapshot. .It Xr zfs-project 8 List, set, or clear project ID and/or inherit flag on the file(s) or directories. .El +. .Ss Mountpoints .Bl -tag -width "" .It Xr zfs-mount 8 Displays all ZFS file systems currently mounted, or mount ZFS filesystem on a path described by its .Sy mountpoint property. .It Xr zfs-unmount 8 Unmounts currently mounted ZFS file systems. .El +. .Ss Shares .Bl -tag -width "" .It Xr zfs-share 8 Shares available ZFS file systems. .It Xr zfs-unshare 8 Unshares currently shared ZFS file systems. .El +. .Ss Delegated Administration .Bl -tag -width "" .It Xr zfs-allow 8 Delegate permissions on the specified filesystem or volume. .It Xr zfs-unallow 8 Remove delegated permissions on the specified filesystem or volume. .El +. .Ss Encryption .Bl -tag -width "" .It Xr zfs-change-key 8 Add or change an encryption key on the specified dataset. .It Xr zfs-load-key 8 Load the key for the specified encrypted dataset, enabling access. .It Xr zfs-unload-key 8 Unload a key for the specified dataset, removing the ability to access the dataset. .El +. .Ss Channel Programs .Bl -tag -width "" .It Xr zfs-program 8 Execute ZFS administrative operations programmatically via a Lua script-language channel program. .El +. .Ss Jails .Bl -tag -width "" .It Xr zfs-jail 8 Attaches a filesystem to a jail. .It Xr zfs-unjail 8 Detaches a filesystem from a jail. .El +. .Ss Waiting .Bl -tag -width "" .It Xr zfs-wait 8 Wait for background activity in a filesystem to complete. .El +. .Sh EXIT STATUS The .Nm -utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line -options were specified. +utility exits +.Sy 0 +on success, +.Sy 1 +if an error occurs, and +.Sy 2 +if invalid command line options were specified. +. .Sh EXAMPLES .Bl -tag -width "" -.It Sy Example 1 No Creating a ZFS File System Hierarchy +. +.It Sy Example 1 : No Creating a ZFS File System Hierarchy The following commands create a file system named -.Em pool/home +.Ar pool/home and a file system named -.Em pool/home/bob . +.Ar pool/home/bob . The mount point .Pa /export/home is set for the parent file system, and is automatically inherited by the child file system. -.Bd -literal -# zfs create pool/home -# zfs set mountpoint=/export/home pool/home -# zfs create pool/home/bob -.Ed -.It Sy Example 2 No Creating a ZFS Snapshot +.Dl # Nm zfs Cm create Ar pool/home +.Dl # Nm zfs Cm set Sy mountpoint Ns = Ns Ar /export/home pool/home +.Dl # Nm zfs Cm create Ar pool/home/bob +. +.It Sy Example 2 : No Creating a ZFS Snapshot The following command creates a snapshot named -.Sy yesterday . +.Ar yesterday . This snapshot is mounted on demand in the .Pa .zfs/snapshot directory at the root of the -.Em pool/home/bob +.Ar pool/home/bob file system. -.Bd -literal -# zfs snapshot pool/home/bob@yesterday -.Ed -.It Sy Example 3 No Creating and Destroying Multiple Snapshots +.Dl # Nm zfs Cm snapshot Ar pool/home/bob Ns @ Ns Ar yesterday +. +.It Sy Example 3 : No Creating and Destroying Multiple Snapshots The following command creates snapshots named -.Sy yesterday -of -.Em pool/home +.Ar yesterday No of Ar pool/home and all of its descendent file systems. Each snapshot is mounted on demand in the .Pa .zfs/snapshot directory at the root of its file system. The second command destroys the newly created snapshots. -.Bd -literal -# zfs snapshot -r pool/home@yesterday -# zfs destroy -r pool/home@yesterday -.Ed -.It Sy Example 4 No Disabling and Enabling File System Compression +.Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday +.Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday +. +.It Sy Example 4 : No Disabling and Enabling File System Compression The following command disables the .Sy compression property for all file systems under -.Em pool/home . +.Ar pool/home . The next command explicitly enables .Sy compression for -.Em pool/home/anne . -.Bd -literal -# zfs set compression=off pool/home -# zfs set compression=on pool/home/anne -.Ed -.It Sy Example 5 No Listing ZFS Datasets +.Ar pool/home/anne . +.Dl # Nm zfs Cm set Sy compression Ns = Ns Sy off Ar pool/home +.Dl # Nm zfs Cm set Sy compression Ns = Ns Sy on Ar pool/home/anne +. +.It Sy Example 5 : No Listing ZFS Datasets The following command lists all active file systems and volumes in the system. -Snapshots are displayed if the -.Sy listsnaps -property is -.Sy on . +Snapshots are displayed if +.Sy listsnaps Ns = Ns Sy on . The default is .Sy off . See -.Xr zpool 8 +.Xr zpoolprops 8 for more information on pool properties. -.Bd -literal -# zfs list +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm list NAME USED AVAIL REFER MOUNTPOINT pool 450K 457G 18K /pool pool/home 315K 457G 21K /export/home pool/home/anne 18K 457G 18K /export/home/anne pool/home/bob 276K 457G 276K /export/home/bob .Ed -.It Sy Example 6 No Setting a Quota on a ZFS File System +. +.It Sy Example 6 : No Setting a Quota on a ZFS File System The following command sets a quota of 50 Gbytes for -.Em pool/home/bob . -.Bd -literal -# zfs set quota=50G pool/home/bob -.Ed -.It Sy Example 7 No Listing ZFS Properties +.Ar pool/home/bob : +.Dl # Nm zfs Cm set Sy quota Ns = Ns Ar 50G pool/home/bob +. +.It Sy Example 7 : No Listing ZFS Properties The following command lists all properties for -.Em pool/home/bob . -.Bd -literal -# zfs get all pool/home/bob +.Ar pool/home/bob : +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm get Sy all Ar pool/home/bob NAME PROPERTY VALUE SOURCE pool/home/bob type filesystem - pool/home/bob creation Tue Jul 21 15:53 2009 - pool/home/bob used 21K - pool/home/bob available 20.0G - pool/home/bob referenced 21K - pool/home/bob compressratio 1.00x - pool/home/bob mounted yes - pool/home/bob quota 20G local pool/home/bob reservation none default pool/home/bob recordsize 128K default pool/home/bob mountpoint /pool/home/bob default pool/home/bob sharenfs off default pool/home/bob checksum on default pool/home/bob compression on local pool/home/bob atime on default pool/home/bob devices on default pool/home/bob exec on default pool/home/bob setuid on default pool/home/bob readonly off default pool/home/bob zoned off default pool/home/bob snapdir hidden default pool/home/bob acltype off default pool/home/bob aclmode discard default pool/home/bob aclinherit restricted default pool/home/bob canmount on default pool/home/bob xattr on default pool/home/bob copies 1 default pool/home/bob version 4 - pool/home/bob utf8only off - pool/home/bob normalization none - pool/home/bob casesensitivity sensitive - pool/home/bob vscan off default pool/home/bob nbmand off default pool/home/bob sharesmb off default pool/home/bob refquota none default pool/home/bob refreservation none default pool/home/bob primarycache all default pool/home/bob secondarycache all default pool/home/bob usedbysnapshots 0 - pool/home/bob usedbydataset 21K - pool/home/bob usedbychildren 0 - pool/home/bob usedbyrefreservation 0 - .Ed .Pp -The following command gets a single property value. -.Bd -literal -# zfs get -H -o value compression pool/home/bob +The following command gets a single property value: +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm get Fl H o Sy value compression Ar pool/home/bob on .Ed +.Pp The following command lists all properties with local settings for -.Em pool/home/bob . -.Bd -literal -# zfs get -r -s local -o name,property,value all pool/home/bob +.Ar pool/home/bob : +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm get Fl r s Sy local Fl o Sy name , Ns Sy property , Ns Sy value all Ar pool/home/bob NAME PROPERTY VALUE pool/home/bob quota 20G pool/home/bob compression on .Ed -.It Sy Example 8 No Rolling Back a ZFS File System +. +.It Sy Example 8 : No Rolling Back a ZFS File System The following command reverts the contents of -.Em pool/home/anne +.Ar pool/home/anne to the snapshot named -.Sy yesterday , -deleting all intermediate snapshots. -.Bd -literal -# zfs rollback -r pool/home/anne@yesterday -.Ed -.It Sy Example 9 No Creating a ZFS Clone +.Ar yesterday , +deleting all intermediate snapshots: +.Dl # Nm zfs Cm rollback Fl r Ar pool/home/anne Ns @ Ns Ar yesterday +. +.It Sy Example 9 : No Creating a ZFS Clone The following command creates a writable file system whose initial contents are the same as -.Em pool/home/bob@yesterday . -.Bd -literal -# zfs clone pool/home/bob@yesterday pool/clone -.Ed -.It Sy Example 10 No Promoting a ZFS Clone +.Ar pool/home/bob@yesterday . +.Dl # Nm zfs Cm clone Ar pool/home/bob@yesterday pool/clone +. +.It Sy Example 10 : No Promoting a ZFS Clone The following commands illustrate how to test out changes to a file system, and then replace the original file system with the changed one, using clones, clone promotion, and renaming: -.Bd -literal -# zfs create pool/project/production +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm create Ar pool/project/production populate /pool/project/production with data -# zfs snapshot pool/project/production@today -# zfs clone pool/project/production@today pool/project/beta +.No # Nm zfs Cm snapshot Ar pool/project/production Ns @ Ns Ar today +.No # Nm zfs Cm clone Ar pool/project/production@today pool/project/beta make changes to /pool/project/beta and test them -# zfs promote pool/project/beta -# zfs rename pool/project/production pool/project/legacy -# zfs rename pool/project/beta pool/project/production +.No # Nm zfs Cm promote Ar pool/project/beta +.No # Nm zfs Cm rename Ar pool/project/production pool/project/legacy +.No # Nm zfs Cm rename Ar pool/project/beta pool/project/production once the legacy version is no longer needed, it can be destroyed -# zfs destroy pool/project/legacy +.No # Nm zfs Cm destroy Ar pool/project/legacy .Ed -.It Sy Example 11 No Inheriting ZFS Properties +. +.It Sy Example 11 : No Inheriting ZFS Properties The following command causes -.Em pool/home/bob -and -.Em pool/home/anne +.Ar pool/home/bob No and Ar pool/home/anne to inherit the .Sy checksum property from their parent. -.Bd -literal -# zfs inherit checksum pool/home/bob pool/home/anne -.Ed -.It Sy Example 12 No Remotely Replicating ZFS Data +.Dl # Nm zfs Cm inherit Sy checksum Ar pool/home/bob pool/home/anne +. +.It Sy Example 12 : No Remotely Replicating ZFS Data The following commands send a full stream and then an incremental stream to a remote machine, restoring them into .Em poolB/received/fs@a and .Em poolB/received/fs@b , respectively. .Em poolB must contain the file system .Em poolB/received , and must not initially contain .Em poolB/received/fs . -.Bd -literal -# zfs send pool/fs@a | \e - ssh host zfs receive poolB/received/fs@a -# zfs send -i a pool/fs@b | \e - ssh host zfs receive poolB/received/fs +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm send Ar pool/fs@a | +.No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs Ns @ Ns Ar a +.No # Nm zfs Cm send Fl i Ar a pool/fs@b | +.No " " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs .Ed -.It Sy Example 13 No Using the Nm zfs Cm receive Fl d No Option +. +.It Sy Example 13 : No Using the Nm zfs Cm receive Fl d No Option The following command sends a full stream of -.Em poolA/fsA/fsB@snap +.Ar poolA/fsA/fsB@snap to a remote machine, receiving it into -.Em poolB/received/fsA/fsB@snap . +.Ar poolB/received/fsA/fsB@snap . The -.Em fsA/fsB@snap +.Ar fsA/fsB@snap portion of the received snapshot's name is determined from the name of the sent snapshot. -.Em poolB +.Ar poolB must contain the file system -.Em poolB/received . +.Ar poolB/received . If -.Em poolB/received/fsA +.Ar poolB/received/fsA does not exist, it is created as an empty file system. -.Bd -literal -# zfs send poolA/fsA/fsB@snap | \e - ssh host zfs receive -d poolB/received +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm send Ar poolA/fsA/fsB@snap | +.No " " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received .Ed -.It Sy Example 14 No Setting User Properties +. +.It Sy Example 14 : No Setting User Properties The following example sets the user-defined -.Sy com.example:department -property for a dataset. -.Bd -literal -# zfs set com.example:department=12345 tank/accounting -.Ed -.It Sy Example 15 No Performing a Rolling Snapshot +.Ar com.example : Ns Ar department +property for a dataset: +.Dl # Nm zfs Cm set Ar com.example : Ns Ar department Ns = Ns Ar 12345 tank/accounting +. +.It Sy Example 15 : No Performing a Rolling Snapshot The following example shows how to maintain a history of snapshots with a consistent naming scheme. To keep a week's worth of snapshots, the user destroys the oldest snapshot, renames the remaining snapshots, and then creates a new snapshot, as follows: -.Bd -literal -# zfs destroy -r pool/users@7daysago -# zfs rename -r pool/users@6daysago @7daysago -# zfs rename -r pool/users@5daysago @6daysago -# zfs rename -r pool/users@4daysago @5daysago -# zfs rename -r pool/users@3daysago @4daysago -# zfs rename -r pool/users@2daysago @3daysago -# zfs rename -r pool/users@yesterday @2daysago -# zfs rename -r pool/users@today @yesterday -# zfs snapshot -r pool/users@today +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm destroy Fl r Ar pool/users@7daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@6daysago No @ Ns Ar 7daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@5daysago No @ Ns Ar 6daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@4daysago No @ Ns Ar 5daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@3daysago No @ Ns Ar 4daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@2daysago No @ Ns Ar 3daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@yesterday No @ Ns Ar 2daysago +.No # Nm zfs Cm rename Fl r Ar pool/users@today No @ Ns Ar yesterday +.No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today .Ed -.It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System +. +.It Sy Example 16 : No Setting sharenfs Property Options on a ZFS File System The following commands show how to set .Sy sharenfs -property options to enable -.Sy rw -access for a set of -.Sy IP -addresses and to enable root access for system -.Sy neo +property options to enable read-write +access for a set of IP addresses and to enable root access for system +.Qq neo on the -.Em tank/home -file system. -.Bd -literal -# zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home -.Ed +.Ar tank/home +file system: +.Dl # Nm zfs Cm set Sy sharenfs Ns = Ns ' Ns Ar rw Ns =@123.123.0.0/16,root= Ns Ar neo Ns ' tank/home .Pp -If you are using -.Sy DNS -for host name resolution, specify the fully qualified hostname. -.It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset +If you are using DNS for host name resolution, +specify the fully-qualified hostname. +. +.It Sy Example 17 : No Delegating ZFS Administration Permissions on a ZFS Dataset The following example shows how to set permissions so that user -.Sy cindys +.Ar cindys can create, destroy, mount, and take snapshots on -.Em tank/cindys . +.Ar tank/cindys . The permissions on -.Em tank/cindys +.Ar tank/cindys are also displayed. -.Bd -literal -# zfs allow cindys create,destroy,mount,snapshot tank/cindys -# zfs allow tank/cindys +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm allow Sy cindys create , Ns Sy destroy , Ns Sy mount , Ns Sy snapshot Ar tank/cindys +.No # Nm zfs Cm allow Ar tank/cindys ---- Permissions on tank/cindys -------------------------------------- Local+Descendent permissions: user cindys create,destroy,mount,snapshot .Ed .Pp Because the -.Em tank/cindys +.Ar tank/cindys mount point permission is set to 755 by default, user -.Sy cindys +.Ar cindys will be unable to mount file systems under -.Em tank/cindys . +.Ar tank/cindys . Add an ACE similar to the following syntax to provide mount point access: -.Bd -literal -# chmod A+user:cindys:add_subdirectory:allow /tank/cindys -.Ed -.It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset +.Dl # Cm chmod No A+user: Ns Ar cindys Ns :add_subdirectory:allow Ar /tank/cindys +. +.It Sy Example 18 : No Delegating Create Time Permissions on a ZFS Dataset The following example shows how to grant anyone in the group -.Sy staff +.Ar staff to create file systems in -.Em tank/users . +.Ar tank/users . This syntax also allows staff members to destroy their own file systems, but not destroy anyone else's file system. The permissions on -.Em tank/users +.Ar tank/users are also displayed. -.Bd -literal -# zfs allow staff create,mount tank/users -# zfs allow -c destroy tank/users -# zfs allow tank/users +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm allow Ar staff Sy create , Ns Sy mount Ar tank/users +.No # Nm zfs Cm allow Fl c Sy destroy Ar tank/users +.No # Nm zfs Cm allow Ar tank/users ---- Permissions on tank/users --------------------------------------- Permission sets: destroy Local+Descendent permissions: group staff create,mount .Ed -.It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset +. +.It Sy Example 19 : No Defining and Granting a Permission Set on a ZFS Dataset The following example shows how to define and grant a permission set on the -.Em tank/users +.Ar tank/users file system. The permissions on -.Em tank/users +.Ar tank/users are also displayed. -.Bd -literal -# zfs allow -s @pset create,destroy,snapshot,mount tank/users -# zfs allow staff @pset tank/users -# zfs allow tank/users +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm allow Fl s No @ Ns Ar pset Sy create , Ns Sy destroy , Ns Sy snapshot , Ns Sy mount Ar tank/users +.No # Nm zfs Cm allow staff No @ Ns Ar pset tank/users +.No # Nm zfs Cm allow Ar tank/users ---- Permissions on tank/users --------------------------------------- Permission sets: @pset create,destroy,mount,snapshot Local+Descendent permissions: group staff @pset .Ed -.It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset +. +.It Sy Example 20 : No Delegating Property Permissions on a ZFS Dataset The following example shows to grant the ability to set quotas and reservations on the -.Em users/home +.Ar users/home file system. The permissions on -.Em users/home +.Ar users/home are also displayed. -.Bd -literal -# zfs allow cindys quota,reservation users/home -# zfs allow users/home +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm allow Ar cindys Sy quota , Ns Sy reservation Ar users/home +.No # Nm zfs Cm allow Ar users/home ---- Permissions on users/home --------------------------------------- Local+Descendent permissions: user cindys quota,reservation cindys% zfs set quota=10G users/home/marks cindys% zfs get quota users/home/marks NAME PROPERTY VALUE SOURCE users/home/marks quota 10G local .Ed -.It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset +. +.It Sy Example 21 : No Removing ZFS Delegated Permissions on a ZFS Dataset The following example shows how to remove the snapshot permission from the -.Sy staff +.Ar staff group on the -.Em tank/users +.Sy tank/users file system. The permissions on -.Em tank/users +.Sy tank/users are also displayed. -.Bd -literal -# zfs unallow staff snapshot tank/users -# zfs allow tank/users +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm unallow Ar staff Sy snapshot Ar tank/users +.No # Nm zfs Cm allow Ar tank/users ---- Permissions on tank/users --------------------------------------- Permission sets: @pset create,destroy,mount,snapshot Local+Descendent permissions: group staff @pset .Ed -.It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset +. +.It Sy Example 22 : No Showing the differences between a snapshot and a ZFS Dataset The following example shows how to see what has changed between a prior snapshot of a ZFS dataset and its current state. The .Fl F option is used to indicate type information for the files affected. -.Bd -literal -# zfs diff -F tank/test@before tank/test +.Bd -literal -compact -offset Ds +.No # Nm zfs Cm diff Fl F Ar tank/test@before tank/test M / /tank/test/ M F /tank/test/linked (+1) R F /tank/test/oldname -> /tank/test/newname - F /tank/test/deleted + F /tank/test/created M F /tank/test/modified .Ed -.It Sy Example 23 No Creating a bookmark +. +.It Sy Example 23 : No Creating a bookmark The following example create a bookmark to a snapshot. This bookmark can then be used instead of snapshot in send streams. -.Bd -literal -# zfs bookmark rpool@snapshot rpool#bookmark -.Ed -.It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System +.Dl # Nm zfs Cm bookmark Ar rpool Ns @ Ns Ar snapshot rpool Ns # Ns Ar bookmark +. +.It Sy Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System The following example show how to share SMB filesystem through ZFS. -Note that a user and his/her password must be given. -.Bd -literal -# smbmount //127.0.0.1/share_tmp /mnt/tmp \\ - -o user=workgroup/turbo,password=obrut,uid=1000 -.Ed +Note that a user and their password must be given. +.Dl # Nm smbmount Ar //127.0.0.1/share_tmp /mnt/tmp Fl o No user=workgroup/turbo,password=obrut,uid=1000 .Pp Minimal -.Em /etc/samba/smb.conf -configuration required: +.Pa /etc/samba/smb.conf +configuration is required, as follows. .Pp -Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to +Samba will need to bind to the loopback interface for the ZFS utilities to communicate with Samba. This is the default behavior for most Linux distributions. .Pp Samba must be able to authenticate a user. -This can be done in a number of ways, depending on if using the system password file, LDAP or the Samba -specific smbpasswd file. -How to do this is outside the scope of this manual. -Please refer to the +This can be done in a number of ways +.Pq Xr passwd 5 , LDAP , Xr smbpasswd 5 , &c.\& . +How to do this is outside the scope of this document – refer to .Xr smb.conf 5 -man page for more information. +for more information. .Pp See the -.Sy USERSHARE section -of the -.Xr smb.conf 5 -man page for all configuration options in case you need to modify any options -to the share afterwards. +.Sx USERSHARES +section for all configuration options, +in case you need to modify any options of the share afterwards. Do note that any changes done with the .Xr net 8 -command will be undone if the share is ever unshared (such as at a reboot etc). +command will be undone if the share is ever unshared (like via a reboot). .El +. .Sh ENVIRONMENT VARIABLES .Bl -tag -width "ZFS_MOUNT_HELPER" -.It Ev ZFS_MOUNT_HELPER +.It Sy ZFS_MOUNT_HELPER Cause -.Nm zfs mount +.Nm zfs Cm mount to use -.Em /bin/mount -to mount zfs datasets. This option is provided for backwards compatibility with older zfs versions. +.Xr mount 8 +to mount ZFS datasets. +This option is provided for backwards compatibility with older ZFS versions. .El +. .Sh INTERFACE STABILITY .Sy Committed . +. .Sh SEE ALSO .Xr attr 1 , .Xr gzip 1 , .Xr ssh 1 , .Xr chmod 2 , .Xr fsync 2 , .Xr stat 2 , .Xr write 2 , .Xr acl 5 , .Xr attributes 5 , .Xr exports 5 , .Xr exportfs 8 , .Xr mount 8 , .Xr net 8 , .Xr selinux 8 , .Xr zfs-allow 8 , .Xr zfs-bookmark 8 , .Xr zfs-change-key 8 , .Xr zfs-clone 8 , .Xr zfs-create 8 , .Xr zfs-destroy 8 , .Xr zfs-diff 8 , .Xr zfs-get 8 , .Xr zfs-groupspace 8 , .Xr zfs-hold 8 , .Xr zfs-inherit 8 , .Xr zfs-jail 8 , .Xr zfs-list 8 , .Xr zfs-load-key 8 , .Xr zfs-mount 8 , .Xr zfs-program 8 , .Xr zfs-project 8 , .Xr zfs-projectspace 8 , .Xr zfs-promote 8 , .Xr zfs-receive 8 , .Xr zfs-redact 8 , .Xr zfs-release 8 , .Xr zfs-rename 8 , .Xr zfs-rollback 8 , .Xr zfs-send 8 , .Xr zfs-set 8 , .Xr zfs-share 8 , .Xr zfs-snapshot 8 , .Xr zfs-unallow 8 , .Xr zfs-unjail 8 , .Xr zfs-unload-key 8 , .Xr zfs-unmount 8 , .Xr zfs-unshare 8 , .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/zfs_ids_to_path.8 b/man/man8/zfs_ids_to_path.8 index 4f7b8429e411..d5b74678b29c 100644 --- a/man/man8/zfs_ids_to_path.8 +++ b/man/man8/zfs_ids_to_path.8 @@ -1,50 +1,51 @@ .\" .\" 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) 2020 by Delphix. All rights reserved. +.\" .Dd April 17, 2020 .Dt ZFS_IDS_TO_PATH 8 .Os +. .Sh NAME .Nm zfs_ids_to_path .Nd convert objset and object ids to names and paths .Sh SYNOPSIS .Nm .Op Fl v .Ar pool -.Ar objset id -.Ar object id -.Nm +.Ar objset-id +.Ar object-id +. .Sh DESCRIPTION -.Pp The .Sy zfs_ids_to_path -utility converts a provided objset and object id into a path to the file that -those ids refer to. +utility converts a provided objset and object ids +into a path to the file they refer to. .Bl -tag -width "-D" .It Fl v Verbose. -Print the dataset name and the file path within the dataset separately. This -will work correctly even if the dataset is not mounted. +Print the dataset name and the file path within the dataset separately. +This will work correctly even if the dataset is not mounted. .El +. .Sh SEE ALSO -.Xr zfs 8 , -.Xr zdb 8 +.Xr zdb 8 , +.Xr zfs 8 diff --git a/man/man8/zfsconcepts.8 b/man/man8/zfsconcepts.8 index 8e0e68678789..3403d53bf8e7 100644 --- a/man/man8/zfsconcepts.8 +++ b/man/man8/zfsconcepts.8 @@ -1,198 +1,206 @@ .\" .\" 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 .\" 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 An overview of ZFS concepts. +.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. +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 +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 +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 systemd.mount(5) for details. +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 +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 +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 +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. +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. As an alternative to deduplication -consider using -.Sy compression=on , -as a less resource-intensive alternative. +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 index 866c4cfffb7b..672eb0276cff 100644 --- a/man/man8/zfsprops.8 +++ b/man/man8/zfsprops.8 @@ -1,2003 +1,2045 @@ .\" .\" 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 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. .\" Copyright (c) 2011, Pawel Jakub Dawidek .\" Copyright (c) 2012, Glen Barber .\" Copyright (c) 2012, Bryan Drewery .\" Copyright (c) 2013, Steven Hartland .\" 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 .\" 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 properties and user-defined of ZFS datasets. +.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 +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. +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 +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 -.Em Encryption +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 +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 +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 -, the -.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 -.Em Snapshots +.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 -.Dv O_SYNC +.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 Em user +.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 -and -.Nm ls Fl s . +.Nm du No and Nm ls Fl s . See the .Nm zfs Cm userspace -subcommand for more information. +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 Em ... +.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 @ symbol, using one of the following -forms: -.Bl -bullet -width "" +The user's name must be appended after the +.Sy @ +symbol, using one of the following forms: +.Bl -bullet -compact -offset 4n .It -.Em POSIX name -.Po for example, -.Sy joe -.Pc +POSIX name +.Pq Qq joe .It -.Em POSIX numeric ID -.Po for example, -.Sy 789 -.Pc +POSIX numeric ID +.Pq Qq 789 .It -.Em SID name -.Po for example, -.Sy joe.smith@mydomain -.Pc +SID name +.Pq Qq joe.smith@mydomain .It -.Em SID numeric ID -.Po for example, -.Sy S-1-123-456-789 -.Pc +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 Em user +.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 +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=on +.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 +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=sa +.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 Em group +.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 Em user +.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 Em group +.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 Em user +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 Em 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 +.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 +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 +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 Em user +.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 Em project +.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=on +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 +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=sa -no additional internal objects are required. See the -.Sy userobjused Ns @ Ns Em user +.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 Em 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 -.Em snapshot +.Ar snapshot may be specified as a short snapshot name -.Po just the part after the -.Sy @ -.Pc , +.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 -.Em snapshot +.Ar snapshot may be a full snapshot name -.Po Em filesystem Ns @ Ns Em snapshot Pc , +.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 -width "passthrough-x" +.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@ , -.Sy group@ , -and -.Sy everyone@ +.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 -width "passthrough" +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 -.Tn ACL -other than creating or updating the necessary -.Tn ACL -entries to represent the new mode of the file or directory. +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 -.Tn ACL -whose entries can not be represented by a mode. +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 -.Tn ACL -entries. +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 -.Tn ACL -when +on a file or directory with a non-trivial ACL when .Sy aclmode is set to .Sy restricted , -you must first remove all -.Tn ACL -entries which do not represent the current mode. +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 -width "posixacl" +.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 FreeBSD, indicates that NFSv4-style ZFS ACLs should be used. +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 -commands on FreeBSD. The +.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 +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=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 +.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=sa -property. See 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 +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 +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 -.Sy NOT +.Em NOT a recommended practice. .Pp The .Sy sha512 , .Sy skein , and .Sy edonr checksum algorithms require enabling the appropriate features on the pool. -FreeBSD does not support the +.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 Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns -.Sy zstd- Ns Em N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Em N +.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 Em N , +.Sy gzip- Ns Ar N , where -.Em N +.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 +compression algorithm provides both high compression ratios and good performance. +You can specify the .Sy zstd level by using the value -.Sy zstd- Ns Em N , +.Sy zstd- Ns Ar N , where -.Em N +.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 Em N , +level. +This is done using +.Sy zstd-fast- Ns Ar N , where -.Em N +.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 - 1000 provides -the fastest compression and lowest compression ratio. +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 +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 +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 8k blocks on disks with 4k disk sectors must compress to 1/2 +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 -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level +.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 +a mount point for that file system. +See .Xr selinux 8 for more information. .It Xo .Sy fscontext Ns = Ns Sy none Ns | Ns -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level +.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 +mounted. +See .Xr selinux 8 for more information. .It Xo .Sy defcontext Ns = Ns Sy none Ns | Ns -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level +.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 +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 -.Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level +.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 +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 -.Sy NOT +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=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. +.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 Em 3 +.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[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns -.Sy edonr,verify +.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 +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 +(this may change in the future). +When .Sy dedup is enabled, the checksum defined here overrides the .Sy checksum -property. Setting the value to +property. +Setting the value to .Sy verify has the same effect as the setting -.Sy sha256,verify. +.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 +signature to make sure the block contents are identical. +Specifying .Sy verify is mandatory for the .Sy edonr algorithm. .Pp -Unless necessary, deduplication should NOT be enabled on a system. See the -.Em Deduplication +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 +file system. +The default value is .Sy legacy . Setting this property to a value other than -.Sy legacy -requires the large_dnode pool feature to be enabled. +.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=sa -property setting and the workload makes heavy use of extended attributes. This +.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 +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 large_dnode feature, or if you need to import this pool on a system -that doesn't support the large_dnode feature. +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 +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 -.Em Encryption +.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. +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: -.Bd -literal -# dd if=/dev/urandom of=/path/to/output/key bs=32 count=1 -.Ed +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 +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 Em .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. +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 STDIN, +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 +the command line. +If a file URI is selected, the key will be loaded from the specified absolute file path. .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 +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 +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 Em count Ns | Ns Sy none +.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 Em size +.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 +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 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 +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 -.Em Mount Points +.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. +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 FreeBSD file systems. +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 Em size Ns | Ns Sy none +.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 Em count Ns | Ns Sy none +.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 Em user Ns = Ns Em size Ns | Ns Sy none +.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 Em user +.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 -subcommand for more information. +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 Em ... +.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 +.Bl -bullet -compact -offset 4n .It -.Em POSIX name -.Po for example, -.Sy joe -.Pc +POSIX name +.Pq Qq joe .It -.Em POSIX numeric ID -.Po for example, -.Sy 789 -.Pc +POSIX numeric ID +.Pq Qq 789 .It -.Em SID name -.Po for example, -.Sy joe.smith@mydomain -.Pc +SID name +.Pq Qq joe.smith@mydomain .It -.Em SID numeric ID -.Po for example, -.Sy S-1-123-456-789 -.Pc +SID numeric ID +.Pq Qq S-1-123-456-789 .El .Pp Files created on Linux always have POSIX owners. -.It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none +.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 +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 Em group Ns = Ns Em size Ns | Ns Sy none +.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 Em group +.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 Em group Ns = Ns Em size Ns | Ns Sy none +.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 +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 Em project Ns = Ns Em 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 Em project -property. Please refer to +.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 Em project Ns = Ns Em size Ns | Ns Sy none +.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 +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 Em size +.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 512 and less -than or equal to 128 Kbytes. +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 1 Mbyte. +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 Em size Ns | Ns Sy none +.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 Em size Ns | Ns Sy none Ns | Ns Sy auto +.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=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 +.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 +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 Em size Ns | Ns Sy none +.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 Em opts +.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 +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 +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 +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", ie. read and write permissions) and no guest +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 Em opts +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 -.Em /etc/exports +.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: -.Pp -.Em sec=sys,rw,crossmnt,no_subtree_check +.Dl sec=sys,rw,crossmnt,no_subtree_check .Pp See .Xr exports 5 -for the meaning of the default options. Otherwise, the +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 -.Em /dev/zvol/ -are hidden or visible. The default value is +.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 -.Em Snapshots +.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 -.Tn 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 +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 Em N Ns | Ns Sy current +.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 Em size +.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 -.Po or -.Sy refreservation -.Pc . +.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. +.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 Cm default | full | geom | dev | none +.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 +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 -.Va zvol_volmode , +.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 on Linux. .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. +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 +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 OpenZFS implementations. +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 +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=sa +.Sy xattr Ns = Ns Sy sa feature. .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 +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 the -.Qq Sx Jails -section in -.Xr zfs 8 -for more information. Jails are a FreeBSD feature and are not relevant on -other platforms. The default value is -.Cm off . +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 +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 -.Tn POSIX -file systems have case-sensitive file names. +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" +. +.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: -.Bd -literal - PROPERTY MOUNT OPTION - atime atime/noatime - canmount auto/noauto - devices dev/nodev - exec exec/noexec - readonly ro/rw - relatime relatime/norelatime - setuid suid/nosuid - xattr xattr/noxattr - nbmand mand/nomand - context context= - fscontext fscontext= - defcontext defcontext= - rootcontext rootcontext= -.Ed +.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 \&, Ns Sy nosetuid . +.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" +. +.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 -.Em module Ns \&: Ns Em property , +.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 -.Sy DNS -domain name for the -.Em module +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/zpool-add.8 b/man/man8/zpool-add.8 index cf1630435eb4..a0f15076f230 100644 --- a/man/man8/zpool-add.8 +++ b/man/man8/zpool-add.8 @@ -1,102 +1,101 @@ .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-ADD 8 .Os +. .Sh NAME .Nm zpool-add -.Nd Adds specified virtual devices to a ZFS storage pool +.Nd add vdevs to ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm add .Op Fl fgLnP .Oo Fl o Ar property Ns = Ns Ar value Oc -.Ar pool vdev Ns ... +.Ar pool vdev Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm add -.Op Fl fgLnP -.Oo Fl o Ar property Ns = Ns Ar value Oc -.Ar pool vdev Ns ... -.Xc Adds the specified virtual devices to the given pool. The .Ar vdev specification is described in the .Em Virtual Devices section of -.Xr zpoolconcepts 8. +.Xr zpoolconcepts 8 . The behavior of the .Fl f option, and the device checks performed are described in the .Nm zpool Cm create subcommand. .Bl -tag -width Ds .It Fl f Forces use of .Ar vdev Ns s , even if they appear in use or specify a conflicting replication level. Not all devices can be overridden in this manner. .It Fl g Display .Ar vdev , -GUIDs instead of the normal device names. These GUIDs can be used in place of +GUIDs instead of the normal device names. +These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. .It Fl L Display real paths for .Ar vdev Ns s -resolving all symbolic links. This can be used to look up the current block -device name regardless of the /dev/disk/ path used to open it. +resolving all symbolic links. +This can be used to look up the current block +device name regardless of the +.Pa /dev/disk +path used to open it. .It Fl n Displays the configuration that would be used without actually adding the .Ar vdev Ns s . The actual pool creation can still fail due to insufficient privileges or device sharing. .It Fl P Display real paths for .Ar vdev Ns s -instead of only the last component of the path. This can be used in -conjunction with the +instead of only the last component of the path. +This can be used in conjunction with the .Fl L flag. .It Fl o Ar property Ns = Ns Ar value -Sets the given pool properties. See the +Sets the given pool properties. +See the .Xr zpoolprops 8 -manual page for a list of valid properties that can be set. The only property -supported at the moment is ashift. -.El +manual page for a list of valid properties that can be set. +The only property supported at the moment is +.Sy ashift . .El +. .Sh SEE ALSO -.Xr zpool-remove 8 , .Xr zpool-attach 8 , .Xr zpool-import 8 , .Xr zpool-initialize 8 , -.Xr zpool-online 8 +.Xr zpool-online 8 , +.Xr zpool-remove 8 diff --git a/man/man8/zpool-attach.8 b/man/man8/zpool-attach.8 index 41b6a6b613da..04c0fca21d0d 100644 --- a/man/man8/zpool-attach.8 +++ b/man/man8/zpool-attach.8 @@ -1,103 +1,98 @@ .\" .\" 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 May 15, 2020 .Dt ZPOOL-ATTACH 8 .Os +. .Sh NAME .Nm zpool-attach -.Nd Attach a new device to an existing ZFS virtual device (vdev). +.Nd attach new device to existing ZFS vdev .Sh SYNOPSIS .Nm zpool .Cm attach .Op Fl fsw .Oo Fl o Ar property Ns = Ns Ar value Oc .Ar pool device new_device +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm attach -.Op Fl fsw -.Oo Fl o Ar property Ns = Ns Ar value Oc -.Ar pool device new_device -.Xc Attaches .Ar new_device to the existing .Ar device . The existing device cannot be part of a raidz configuration. If .Ar device is not currently part of a mirrored configuration, .Ar device automatically transforms into a two-way mirror of .Ar device and .Ar new_device . If .Ar device is part of a two-way mirror, attaching .Ar new_device creates a three-way mirror, and so on. In either case, .Ar new_device begins to resilver immediately and any running scrub is cancelled. .Bl -tag -width Ds .It Fl f Forces use of .Ar new_device , even if it appears to be in use. 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 +Sets the given pool properties. +See the .Xr zpoolprops 8 -manual page for a list of valid properties that can be set. The only property -supported at the moment is ashift. +manual page for a list of valid properties that can be set. +The only property supported at the moment is +.Sy ashift . .It Fl s The .Ar new_device is reconstructed sequentially to restore redundancy as quickly as possible. Checksums are not verfied during sequential reconstruction so a scrub is started when the resilver completes. Sequential reconstruction is not supported for raidz configurations. .It Fl w Waits until .Ar new_device has finished resilvering before returning. .El -.El +. .Sh SEE ALSO -.Xr zpool-detach 8 , .Xr zpool-add 8 , +.Xr zpool-detach 8 , .Xr zpool-import 8 , .Xr zpool-initialize 8 , .Xr zpool-online 8 , .Xr zpool-replace 8 , .Xr zpool-resilver 8 diff --git a/man/man8/zpool-checkpoint.8 b/man/man8/zpool-checkpoint.8 index 128970ee66ac..d5add14aed2f 100644 --- a/man/man8/zpool-checkpoint.8 +++ b/man/man8/zpool-checkpoint.8 @@ -1,82 +1,72 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-CHECKPOINT 8 .Os +. .Sh NAME .Nm zpool-checkpoint -.Nd Checkpoints the current state of a ZFS storage pool +.Nd check-point current ZFS storage pool state .Sh SYNOPSIS .Nm zpool .Cm checkpoint -.Op Fl d, -discard Oo Fl w, -wait Oc +.Op Fl d Op Fl w .Ar pool +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm checkpoint -.Op Fl d, -discard Oo Fl w, -wait Oc -.Ar pool -.Xc Checkpoints the current state of .Ar pool , which can be later restored by .Nm zpool Cm import --rewind-to-checkpoint . The existence of a checkpoint in a pool prohibits the following .Nm zpool -commands: -.Cm remove , -.Cm attach , -.Cm detach , -.Cm split , -and -.Cm reguid . +subcommands: +.Cm remove , attach , detach , split , No and Cm reguid . In addition, it may break reservation boundaries if the pool lacks free space. The .Nm zpool Cm status command indicates the existence of a checkpoint or the progress of discarding a checkpoint from a pool. -The .Nm zpool Cm list -command reports how much space the checkpoint takes from the pool. +can be used to check how much space the checkpoint takes from the pool. +. +.Sh OPTIONS .Bl -tag -width Ds -.It Fl d, -discard +.It Fl d , -discard Discards an existing checkpoint from .Ar pool . -.It Fl w, -wait +.It Fl w , -wait Waits until the checkpoint has finished being discarded before returning. .El -.El +. .Sh SEE ALSO +.Xr zfs-snapshot 8 , .Xr zpool-import 8 , -.Xr zpool-status 8 , -.Xr zfs-snapshot 8 +.Xr zpool-status 8 diff --git a/man/man8/zpool-clear.8 b/man/man8/zpool-clear.8 index e00eb760af61..6e41566ca6da 100644 --- a/man/man8/zpool-clear.8 +++ b/man/man8/zpool-clear.8 @@ -1,60 +1,56 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-CLEAR 8 .Os +. .Sh NAME .Nm zpool-clear -.Nd Clears device errors in a ZFS storage pool. +.Nd clear device errors in ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm clear .Ar pool -.Op Ar device +.Oo Ar device Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm clear -.Ar pool -.Op Ar device -.Xc Clears device errors in a pool. If no arguments are specified, all device errors within the pool are cleared. If one or more devices is specified, only those errors associated with the specified device or devices are cleared. -If multihost is enabled, and the pool has been suspended, this will not -resume I/O. While the pool was suspended, it may have been imported on +If +.Sy multihost +is enabled and the pool has been suspended, this will not resume I/O. +While the pool was suspended, it may have been imported on another host, and resuming I/O could result in pool damage. -.El +. .Sh SEE ALSO .Xr zdb 8 , .Xr zpool-reopen 8 , .Xr zpool-status 8 diff --git a/man/man8/zpool-create.8 b/man/man8/zpool-create.8 index d8cb61c45170..91e6f427d837 100644 --- a/man/man8/zpool-create.8 +++ b/man/man8/zpool-create.8 @@ -1,221 +1,211 @@ .\" .\" 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 .\" -.Dd August 9, 2019 +.Dd June 2, 2021 .Dt ZPOOL-CREATE 8 .Os +. .Sh NAME .Nm zpool-create -.Nd Creates a new ZFS storage pool +.Nd create ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm create .Op Fl dfn .Op Fl m Ar mountpoint -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Oo Fl o Ar feature@feature Ns = Ns Ar value Oc -.Op Fl o Ar compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ... -.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ... -.Op Fl R Ar root -.Ar pool vdev Ns ... -.Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm create -.Op Fl dfn -.Op Fl m Ar mountpoint -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Oo Fl o Ar feature@feature Ns = Ns Ar value Oc Ns ... -.Op Fl o Ar compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ... -.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … +.Oo Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value Oc +.Op Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns … +.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns … .Op Fl R Ar root .Op Fl t Ar tname -.Ar pool vdev Ns ... -.Xc +.Ar pool +.Ar vdev Ns … +. +.Sh DESCRIPTION Creates a new storage pool containing the virtual devices specified on the command line. The pool name must begin with a letter, and can only contain -alphanumeric characters as well as underscore +alphanumeric characters as well as the underscore .Pq Qq Sy _ , dash .Pq Qq Sy \&- , colon .Pq Qq Sy \&: , space .Pq Qq Sy \&\ , and period .Pq Qq Sy \&. . The pool names .Sy mirror , .Sy raidz , .Sy draid , .Sy spare and .Sy log are reserved, as are names beginning with .Sy mirror , .Sy raidz , .Sy draid , -.Sy spare , -and the pattern -.Sy c[0-9] . +and +.Sy spare . The .Ar vdev specification is described in the -.Em Virtual Devices +.Sx Virtual Devices section of .Xr zpoolconcepts 8 . .Pp The command attempts to verify that each device specified is accessible and not -currently in use by another subsystem. However this check is not robust enough +currently in use by another subsystem. +However this check is not robust enough to detect simultaneous attempts to use a new device in different pools, even if -.Sy multihost -is -.Sy enabled. -The -administrator must ensure that simultaneous invocations of any combination of -.Sy zpool replace , -.Sy zpool create , -.Sy zpool add , +.Sy multihost Ns = Sy enabled . +The administrator must ensure, that simultaneous invocations of any combination of +.Nm zpool Cm replace , +.Nm zpool Cm create , +.Nm zpool Cm add , or -.Sy zpool labelclear , -do not refer to the same device. Using the same device in two pools will -result in pool corruption. +.Nm zpool Cm labelclear , +do not refer to the same device. +Using the same device in two pools will result in pool corruption. .Pp There are some uses, such as being currently mounted, or specified as the dedicated dump device, that prevents a device from ever being used by ZFS. Other uses, such as having a preexisting UFS file system, can be overridden with -the -.Fl f -option. +.Fl f . .Pp The command also checks that the replication strategy for the pool is consistent. -An attempt to combine redundant and non-redundant storage in a single pool, or -to mix disks and files, results in an error unless +An attempt to combine redundant and non-redundant storage in a single pool, +or to mix disks and files, results in an error unless .Fl f is specified. -The use of differently sized devices within a single raidz or mirror group is +The use of differently-sized devices within a single raidz or mirror group is also flagged as an error unless .Fl f is specified. .Pp Unless the .Fl R option is specified, the default mount point is .Pa / Ns Ar pool . The mount point must not exist or must be empty, or else the root dataset -cannot be mounted. +will not be able to be be mounted. This can be overridden with the .Fl m option. .Pp -By default all supported features are enabled on the new pool. The +By default all supported features are enabled on the new pool. +The .Fl d -option or the +option and the .Fl o Ar compatibility -property (eg: -.Fl o Ar compatibility=2020 -) can be used to restrict the features that are enabled, so that the -pool can be imported on other releases of the ZFS software. -.Bl -tag -width Ds +property +.Pq e.g Fl o Sy compatibility Ns = Ns Ar 2020 +can be used to restrict the features that are enabled, so that the +pool can be imported on other releases of ZFS. +.Bl -tag -width "-t tname" .It Fl d Do not enable any features on the new pool. Individual features can be enabled by setting their corresponding properties to .Sy enabled -with the -.Fl o -option. +with +.Fl o . See .Xr zpool-features 5 for details about feature properties. .It Fl f Forces use of .Ar vdev Ns s , even if they appear in use or specify a conflicting replication level. Not all devices can be overridden in this manner. .It Fl m Ar mountpoint Sets the mount point for the root dataset. The default mount point is .Pa /pool or .Pa altroot/pool if -.Ar altroot +.Sy altroot is specified. The mount point must be an absolute path, .Sy legacy , or .Sy none . For more information on dataset mount points, see -.Xr zfs 8 . +.Xr zfsprops 8 . .It Fl n Displays the configuration that would be used without actually creating the pool. The actual pool creation can still fail due to insufficient privileges or device sharing. .It Fl o Ar property Ns = Ns Ar value Sets the given pool properties. -See the +See .Xr zpoolprops 8 -manual page for a list of valid properties that can be set. -.It Fl o Ar compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ... -Specifies compatibility feature sets. See +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 for more information about compatibility feature sets. -.It Fl o Ar feature@feature Ns = Ns Ar value -Sets the given pool feature. See the +.It Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value +Sets the given pool feature. +See the .Xr zpool-features 5 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 the +See .Xr zfsprops 8 -manual page for a list of valid properties that can be set. +for a list of valid properties that can be set. .It Fl R Ar root Equivalent to .Fl o Sy cachefile Ns = Ns Sy none Fl o Sy altroot Ns = Ns Ar root .It Fl t Ar tname Sets the in-core pool name to -.Sy tname -while the on-disk name will be the name specified as the pool name -.Sy pool . -This will set the default cachefile property to none. This is intended +.Ar tname +while the on-disk name will be the name specified as +.Ar pool . +This will set the default of the +.Sy cachefile +property to +.Sy none . +This is intended to handle name space collisions when creating pools for other systems, such as virtual machines or physical machines whose pools live on network block devices. .El -.El +. .Sh SEE ALSO .Xr zpool-destroy 8 , .Xr zpool-export 8 , .Xr zpool-import 8 diff --git a/man/man8/zpool-detach.8 b/man/man8/zpool-detach.8 index 75a5786d5a3d..952dd7882a90 100644 --- a/man/man8/zpool-detach.8 +++ b/man/man8/zpool-detach.8 @@ -1,61 +1,58 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-DETACH 8 .Os +. .Sh NAME .Nm zpool-detach -.Nd Detaches a device from a ZFS mirror vdev (virtual device) +.Nd detach device from ZFS mirror .Sh SYNOPSIS .Nm zpool .Cm detach .Ar pool device +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm detach -.Ar pool device -.Xc Detaches .Ar device from a mirror. The operation is refused if there are no other valid replicas of the data. -If device may be re-added to the pool later on then consider the -.Sy zpool offline +If +.Ar device +may be re-added to the pool later on then consider the +.Nm zpool Cm offline command instead. -.El +. .Sh SEE ALSO .Xr zpool-attach 8 , -.Xr zpool-offline 8 , .Xr zpool-labelclear 8 , +.Xr zpool-offline 8 , .Xr zpool-remove 8 , .Xr zpool-replace 8 , .Xr zpool-split 8 diff --git a/man/man8/zpool-events.8 b/man/man8/zpool-events.8 index 3a6ff8840168..a95ce48d93a8 100644 --- a/man/man8/zpool-events.8 +++ b/man/man8/zpool-events.8 @@ -1,71 +1,73 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-EVENTS 8 .Os +. .Sh NAME .Nm zpool-events -.Nd Lists all recent events generated by the ZFS kernel modules +.Nd list recent events generated by kernel .Sh SYNOPSIS .Nm zpool .Cm events -.Op Fl vHf Oo Ar pool Oc | Fl c -.Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo +.Op Fl vHf +.Op Ar pool .Nm zpool .Cm events -.Op Fl vHf Oo Ar pool Oc | Fl c -.Xc -Lists all recent events generated by the ZFS kernel modules. These events -are consumed by the +.Fl c +. +.Sh DESCRIPTION +Lists all recent events generated by the ZFS kernel modules. +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 +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. -.Bl -tag -width Ds +.Pp +.Bl -tag -compact -width Ds .It Fl c Clear all previous events. .It Fl f Follow mode. .It Fl H -Scripted mode. Do not display headers, and separate fields by a +Scripted mode. +Do not display headers, and separate fields by a single tab instead of arbitrary space. .It Fl v Print the entire payload for each event. .El -.El +. .Sh SEE ALSO -.Xr zed 8 , -.Xr zpool-wait 8 , .Xr zfs-events 5 , -.Xr zfs-module-parameters 5 +.Xr zfs-module-parameters 5 , +.Xr zed 8 , +.Xr zpool-wait 8 diff --git a/man/man8/zpool-get.8 b/man/man8/zpool-get.8 index 118743080095..06908238999c 100644 --- a/man/man8/zpool-get.8 +++ b/man/man8/zpool-get.8 @@ -1,102 +1,108 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-GET 8 .Os +. .Sh NAME .Nm zpool-get -.Nd Retrieves properties for the specified ZFS storage pool(s) +.Nd retrieve properties of ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm get .Op Fl Hp -.Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... -.Sy all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns ... -.Oo Ar pool Oc Ns ... +.Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns … +.Sy all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns … +.Oo Ar pool Oc Ns … .Nm zpool .Cm set .Ar property Ns = Ns Ar value .Ar pool +. .Sh DESCRIPTION .Bl -tag -width Ds .It Xo .Nm zpool .Cm get .Op Fl Hp -.Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... -.Sy all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns ... -.Oo Ar pool Oc Ns ... +.Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns … +.Sy all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns … +.Oo Ar pool Oc Ns … .Xc Retrieves the given list of properties .Po or all properties if .Sy all is used .Pc for the specified storage pool(s). These properties are displayed with the following fields: -.Bd -literal - name Name of storage pool - property Property name - value Property value - source Property source, either 'default' or 'local'. -.Ed +.Bl -tag -compact -offset Ds -width "property" +.It Sy name +Name of storage pool. +.It Sy property +Property name. +.It Sy value +Property value. +.It Sy source +Property source, either +.Sy default No or Sy local . +.El .Pp See the .Xr zpoolprops 8 manual page for more information on the available pool properties. -.Bl -tag -width Ds +.Bl -tag -compact -offset Ds -width "-o field" .It Fl H Scripted mode. Do not display headers, and separate fields by a single tab instead of arbitrary space. .It Fl o Ar field -A comma-separated list of columns to display. -.Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source -is the default value. +A comma-separated list of columns to display, defaults to +.Sy name , Ns Sy property , Ns Sy value , Ns Sy source . .It Fl p Display numbers in parsable (exact) values. .El .It Xo .Nm zpool .Cm set .Ar property Ns = Ns Ar value .Ar pool .Xc Sets the given property on the specified pool. See the .Xr zpoolprops 8 manual page for more information on what properties can be set and acceptable values. .El +. .Sh SEE ALSO -.Xr zpoolprops 8 , +.Xr zpool-features 5 , .Xr zpool-list 8 , -.Xr zpool-features 5 +.Xr zpoolprops 8 diff --git a/man/man8/zpool-import.8 b/man/man8/zpool-import.8 index 66a8d94d6de6..1b1f3c5ae5b0 100644 --- a/man/man8/zpool-import.8 +++ b/man/man8/zpool-import.8 @@ -1,388 +1,409 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-IMPORT 8 .Os +. .Sh NAME .Nm zpool-import -.Nd Lists ZFS storage pools available to import or import the specified pools +.Nd import ZFS storage pools or list available pools .Sh SYNOPSIS .Nm zpool .Cm import .Op Fl D -.Op Fl d Ar dir Ns | Ns device +.Oo Fl d Ar dir Ns | Ns Ar device Oc Ns … .Nm zpool .Cm import .Fl a .Op Fl DflmN -.Op Fl F Oo Fl n Oc Oo Fl T Oc Oo Fl X Oc +.Op Fl F Op Fl nTX .Op Fl -rewind-to-checkpoint -.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device +.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device .Op Fl o Ar mntopts -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Op Fl R Ar root .Nm zpool .Cm import -.Op Fl Dflm -.Op Fl F Oo Fl n Oc Oo Fl T Oc Oo Fl X Oc +.Op Fl Dflmt +.Op Fl F Op Fl nTX .Op Fl -rewind-to-checkpoint -.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device +.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device .Op Fl o Ar mntopts -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Op Fl R Ar root .Op Fl s .Ar pool Ns | Ns Ar id -.Op Ar newpool Oo Fl t Oc +.Op Ar newpool +. .Sh DESCRIPTION .Bl -tag -width Ds .It Xo .Nm zpool .Cm import .Op Fl D -.Op Fl d Ar dir Ns | Ns device +.Oo Fl d Ar dir Ns | Ns Ar device Oc Ns … .Xc Lists pools available to import. If the .Fl d or .Fl c options are not specified, this command searches for devices using libblkid -on Linux and geom on FreeBSD. +on Linux and geom on +.Fx . The .Fl d option can be specified multiple times, and all directories are searched. If the device appears to be part of an exported pool, this command displays a summary of the pool with the name of the pool, a numeric identifier, as well as the vdev layout and current health of the device for each device or file. Destroyed pools, pools that were previously destroyed with the .Nm zpool Cm destroy command, are not listed unless the .Fl D option is specified. .Pp The numeric identifier is unique, and can be used instead of the pool name when multiple exported pools of the same name are available. .Bl -tag -width Ds .It Fl c Ar cachefile Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile pool property. This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir Ns | Ns Ar device Uses .Ar device or searches for devices or files in .Ar dir . The .Fl d option can be specified multiple times. .It Fl D Lists destroyed pools only. .El .It Xo .Nm zpool .Cm import .Fl a .Op Fl DflmN -.Op Fl F Oo Fl n Oc Oo Fl T Oc Oo Fl X Oc -.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device +.Op Fl F Op Fl nTX +.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device .Op Fl o Ar mntopts -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Op Fl R Ar root .Op Fl s .Xc Imports all pools found in the search directories. Identical to the previous command, except that all pools with a sufficient number of devices available are imported. Destroyed pools, pools that were previously destroyed with the .Nm zpool Cm destroy command, will not be imported unless the .Fl D option is specified. .Bl -tag -width Ds .It Fl a Searches for and imports all pools found. .It Fl c Ar cachefile Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile pool property. This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir Ns | Ns Ar device Uses .Ar device or searches for devices or files in .Ar dir . The .Fl d option can be specified multiple times. This option is incompatible with the .Fl c option. .It Fl D Imports destroyed pools only. The .Fl f option is also required. .It Fl f Forces import, even if the pool appears to be potentially active. .It Fl F Recovery mode for a non-importable pool. Attempt to return the pool to an importable state by discarding the last few transactions. Not all damaged pools can be recovered by using this option. If successful, the data from the discarded transactions is irretrievably lost. This option is ignored if the pool is importable or already imported. .It Fl l Indicates that this command will request encryption keys for all encrypted -datasets it attempts to mount as it is bringing the pool online. Note that if -any datasets have a +datasets it attempts to mount as it is bringing the pool online. +Note that if any datasets have a .Sy keylocation of .Sy prompt -this command will block waiting for the keys to be entered. Without this flag +this command will block waiting for the keys to be entered. +Without this flag encrypted datasets will be left unavailable until the keys are loaded. .It Fl m Allows a pool to import when there is a missing log device. Recent transactions can be lost because the log device will be discarded. .It Fl n Used with the .Fl F recovery option. Determines whether a non-importable pool can be made importable again, but does not actually perform the pool recovery. For more details about pool recovery mode, see the .Fl F option, above. .It Fl N Import the pool without mounting any file systems. .It Fl o Ar mntopts Comma-separated list of mount options to use when mounting datasets within the pool. See .Xr zfs 8 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 manual page for more information on the available pool properties. .It Fl R Ar root Sets the .Sy cachefile property to .Sy none and the .Sy altroot property to .Ar root . .It Fl -rewind-to-checkpoint Rewinds pool to the checkpointed state. Once the pool is imported with this flag there is no way to undo the rewind. All changes and data that were written after the checkpoint are lost! The only exception is when the .Sy readonly mounting option is enabled. In this case, the checkpointed state of the pool is opened and an administrator can see how the pool would look like if they were to fully rewind. .It Fl s Scan using the default search path, the libblkid cache will not be -consulted. A custom search path may be specified by setting the -ZPOOL_IMPORT_PATH environment variable. +consulted. +A custom search path may be specified by setting the +.Sy ZPOOL_IMPORT_PATH +environment variable. .It Fl X Used with the .Fl F -recovery option. Determines whether extreme -measures to find a valid txg should take place. This allows the pool to +recovery option. +Determines whether extreme measures to find a valid txg should take place. +This allows the pool to be rolled back to a txg which is no longer guaranteed to be consistent. -Pools imported at an inconsistent txg may contain uncorrectable -checksum errors. For more details about pool recovery mode, see the +Pools imported at an inconsistent txg may contain uncorrectable checksum errors. +For more details about pool recovery mode, see the .Fl F -option, above. WARNING: This option can be extremely hazardous to the +option, above. +WARNING: This option can be extremely hazardous to the health of your pool and should only be used as a last resort. .It Fl T -Specify the txg to use for rollback. Implies +Specify the txg to use for rollback. +Implies .Fl FX . For more details about pool recovery mode, see the .Fl X -option, above. WARNING: This option can be extremely hazardous to the +option, above. +WARNING: This option can be extremely hazardous to the health of your pool and should only be used as a last resort. .El .It Xo .Nm zpool .Cm import -.Op Fl Dflm -.Op Fl F Oo Fl n Oc Oo Fl t Oc Oo Fl T Oc Oo Fl X Oc -.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device +.Op Fl Dflmt +.Op Fl F Op Fl nTX +.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns Ar device .Op Fl o Ar mntopts -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Op Fl R Ar root .Op Fl s .Ar pool Ns | Ns Ar id .Op Ar newpool .Xc Imports a specific pool. A pool can be identified by its name or the numeric identifier. If .Ar newpool is specified, the pool is imported using the name .Ar newpool . Otherwise, it is imported with the same name as its exported name. .Pp If a device is removed from a system without running .Nm zpool Cm export first, the device appears as potentially active. It cannot be determined if this was a failed export, or whether the device is really in use from another host. To import a pool in this state, the .Fl f option is required. .Bl -tag -width Ds .It Fl c Ar cachefile Reads configuration from the given .Ar cachefile that was created with the .Sy cachefile pool property. This .Ar cachefile is used instead of searching for devices. .It Fl d Ar dir Ns | Ns Ar device Uses .Ar device or searches for devices or files in .Ar dir . The .Fl d option can be specified multiple times. This option is incompatible with the .Fl c option. .It Fl D Imports destroyed pool. The .Fl f option is also required. .It Fl f Forces import, even if the pool appears to be potentially active. .It Fl F Recovery mode for a non-importable pool. Attempt to return the pool to an importable state by discarding the last few transactions. Not all damaged pools can be recovered by using this option. If successful, the data from the discarded transactions is irretrievably lost. This option is ignored if the pool is importable or already imported. .It Fl l Indicates that this command will request encryption keys for all encrypted -datasets it attempts to mount as it is bringing the pool online. Note that if -any datasets have a +datasets it attempts to mount as it is bringing the pool online. +Note that if any datasets have a .Sy keylocation of .Sy prompt -this command will block waiting for the keys to be entered. Without this flag +this command will block waiting for the keys to be entered. +Without this flag encrypted datasets will be left unavailable until the keys are loaded. .It Fl m Allows a pool to import when there is a missing log device. Recent transactions can be lost because the log device will be discarded. .It Fl n Used with the .Fl F recovery option. Determines whether a non-importable pool can be made importable again, but does not actually perform the pool recovery. For more details about pool recovery mode, see the .Fl F option, above. .It Fl o Ar mntopts Comma-separated list of mount options to use when mounting datasets within the pool. See .Xr zfs 8 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 manual page for more information on the available pool properties. .It Fl R Ar root Sets the .Sy cachefile property to .Sy none and the .Sy altroot property to .Ar root . .It Fl s Scan using the default search path, the libblkid cache will not be -consulted. A custom search path may be specified by setting the -ZPOOL_IMPORT_PATH environment variable. +consulted. +A custom search path may be specified by setting the +.Sy ZPOOL_IMPORT_PATH +environment variable. .It Fl X Used with the .Fl F -recovery option. Determines whether extreme -measures to find a valid txg should take place. This allows the pool to +recovery option. +Determines whether extreme measures to find a valid txg should take place. +This allows the pool to be rolled back to a txg which is no longer guaranteed to be consistent. Pools imported at an inconsistent txg may contain uncorrectable -checksum errors. For more details about pool recovery mode, see the +checksum errors. +For more details about pool recovery mode, see the .Fl F -option, above. WARNING: This option can be extremely hazardous to the +option, above. +WARNING: This option can be extremely hazardous to the health of your pool and should only be used as a last resort. .It Fl T -Specify the txg to use for rollback. Implies +Specify the txg to use for rollback. +Implies .Fl FX . For more details about pool recovery mode, see the .Fl X -option, above. WARNING: This option can be extremely hazardous to the +option, above. +WARNING: This option can be extremely hazardous to the health of your pool and should only be used as a last resort. .It Fl t Used with .Sy newpool . Specifies that .Sy newpool -is temporary. Temporary pool names last until export. Ensures that -the original pool name will be used in all label updates and therefore -is retained upon export. -Will also set -o cachefile=none when not explicitly specified. +is temporary. +Temporary pool names last until export. +Ensures that the original pool name will be used +in all label updates and therefore is retained upon export. +Will also set +.Fl o Sy cachefile Ns = Ns Sy none +when not explicitly specified. .El .El +. .Sh SEE ALSO .Xr zpool-export 8 , .Xr zpool-list 8 , .Xr zpool-status 8 diff --git a/man/man8/zpool-initialize.8 b/man/man8/zpool-initialize.8 index 2734c1b340b8..0a108180dbbe 100644 --- a/man/man8/zpool-initialize.8 +++ b/man/man8/zpool-initialize.8 @@ -1,81 +1,73 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-INITIALIZE 8 .Os +. .Sh NAME .Nm zpool-initialize -.Nd Write to all unallocated regions of eligible devices in a ZFS storage pool +.Nd write to unallocated regions of ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm initialize -.Op Fl c | Fl s +.Op Fl c Ns | Ns Fl s .Op Fl w .Ar pool -.Op Ar device Ns ... +.Oo Ar device Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm initialize -.Op Fl c | Fl s -.Op Fl w -.Ar pool -.Op Ar device Ns ... -.Xc Begins initializing by writing to all unallocated regions on the specified devices, or all eligible devices in the pool if no individual devices are specified. Only leaf data or log devices may be initialized. .Bl -tag -width Ds -.It Fl c, -cancel +.It Fl c , -cancel Cancel initializing on the specified devices, or all eligible devices if none are specified. If one or more target devices are invalid or are not currently being initialized, the command will fail and no cancellation will occur on any device. -.It Fl s -suspend +.It Fl s , -suspend Suspend initializing on the specified devices, or all eligible devices if none are specified. If one or more target devices are invalid or are not currently being initialized, the command will fail and no suspension will occur on any device. Initializing can then be resumed by running .Nm zpool Cm initialize with no flags on the relevant target devices. -.It Fl w, -wait +.It Fl w , -wait Wait until the devices have finished initializing before returning. .El -.El +. .Sh SEE ALSO .Xr zpool-add 8 , .Xr zpool-attach 8 , .Xr zpool-create 8 , .Xr zpool-online 8 , .Xr zpool-replace 8 , .Xr zpool-trim 8 diff --git a/man/man8/zpool-iostat.8 b/man/man8/zpool-iostat.8 index e457eb142ab8..0e64aa71b1d6 100644 --- a/man/man8/zpool-iostat.8 +++ b/man/man8/zpool-iostat.8 @@ -1,247 +1,257 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-IOSTAT 8 .Os +. .Sh NAME .Nm zpool-iostat -.Nd Display logical I/O statistics for the given ZFS storage pools/vdevs +.Nd display logical I/O statistics for ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm iostat .Op Oo Oo Fl c Ar SCRIPT Oc Oo Fl lq Oc Oc Ns | Ns Fl rw .Op Fl T Sy u Ns | Ns Sy d .Op Fl ghHLnpPvy -.Oo Oo Ar pool Ns ... Oc Ns | Ns Oo Ar pool vdev Ns ... Oc Ns | Ns Oo Ar vdev Ns ... Oc Oc +.Oo Ar pool Ns … Ns | Ns Oo Ar pool vdev Ns … Oc Ns | Ns Ar vdev Ns … Oc .Op Ar interval Op Ar count +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm iostat -.Op Oo Oo Fl c Ar SCRIPT Oc Oo Fl lq Oc Oc Ns | Ns Fl rw -.Op Fl T Sy u Ns | Ns Sy d -.Op Fl ghHLnpPvy -.Oo Oo Ar pool Ns ... Oc Ns | Ns Oo Ar pool vdev Ns ... Oc Ns | Ns Oo Ar vdev Ns ... Oc Oc -.Op Ar interval Op Ar count -.Xc -Displays logical I/O statistics for the given pools/vdevs. Physical I/Os may -be observed via +Displays logical I/O statistics for the given pools/vdevs. +Physical I/O statistics may be observed via .Xr iostat 1 . If writes are located nearby, they may be merged into a single -larger operation. Additional I/O may be generated depending on the level of -vdev redundancy. +larger operation. +Additional I/O may be generated depending on the level of vdev redundancy. To filter output, you may pass in a list of pools, a pool and list of vdevs -in that pool, or a list of any vdevs from any pool. If no items are specified, -statistics for every pool in the system are shown. +in that pool, or a list of any vdevs from any pool. +If no items are specified, statistics for every pool in the system are shown. When given an .Ar interval , the statistics are printed every .Ar interval -seconds until ^C is pressed. If +seconds until killed. +If .Fl n flag is specified the headers are displayed only once, otherwise they are -displayed periodically. If count is specified, the command exits -after count reports are printed. The first report printed is always -the statistics since boot regardless of whether +displayed periodically. +If +.Ar count +is specified, the command exits after +.Ar count +reports are printed. +The first report printed is always the statistics since boot regardless of whether .Ar interval and .Ar count -are passed. However, this behavior can be suppressed with the +are passed. +However, this behavior can be suppressed with the .Fl y -flag. Also note that the units of +flag. +Also note that the units of .Sy K , .Sy M , -.Sy G ... -that are printed in the report are in base 1024. To get the raw -values, use the +.Sy G Ns … +that are printed in the report are in base 1024. +To get the raw values, use the .Fl p flag. .Bl -tag -width Ds -.It Fl c Op Ar SCRIPT1 Ns Oo , Ns Ar SCRIPT2 Oc Ns ... +.It Fl c Op Ar SCRIPT1 Ns Oo , Ns Ar SCRIPT2 Oc Ns … Run a script (or scripts) on each vdev and include the output as a new column in the .Nm zpool Cm iostat -output. Users can run any script found in their +output. +Users can run any script found in their .Pa ~/.zpool.d directory or from the system .Pa /etc/zfs/zpool.d -directory. Script names containing the slash (/) character are not allowed. +directory. +Script names containing the slash +.Pq Sy / +character are not allowed. The default search path can be overridden by setting the -ZPOOL_SCRIPTS_PATH environment variable. A privileged user can run +.Sy ZPOOL_SCRIPTS_PATH +environment variable. +A privileged user can only run .Fl c -if they have the ZPOOL_SCRIPTS_AS_ROOT -environment variable set. If a script requires the use of a privileged -command, like +if they have the +.Sy ZPOOL_SCRIPTS_AS_ROOT +environment variable set. +If a script requires the use of a privileged command, like .Xr smartctl 8 , then it's recommended you allow the user access to it in .Pa /etc/sudoers or add the user to the .Pa /etc/sudoers.d/zfs file. .Pp If .Fl c is passed without a script name, it prints a list of all scripts. .Fl c also sets verbose mode .No \&( Ns Fl v Ns No \&). .Pp -Script output should be in the form of "name=value". The column name is -set to "name" and the value is set to "value". Multiple lines can be -used to output multiple columns. The first line of output not in the -"name=value" format is displayed without a column title, and no more -output after that is displayed. This can be useful for printing error -messages. Blank or NULL values are printed as a '-' to make output -awk-able. +Script output should be in the form of "name=value". +The column name is set to "name" and the value is set to "value". +Multiple lines can be used to output multiple columns. +The first line of output not in the +"name=value" format is displayed without a column title, +and no more output after that is displayed. +This can be useful for printing error messages. +Blank or NULL values are printed as a '-' to make output AWKable. .Pp The following environment variables are set before running each script: -.Bl -tag -width "VDEV_PATH" +.Bl -tag -compact -width "VDEV_ENC_SYSFS_PATH" .It Sy VDEV_PATH Full path to the vdev -.El -.Bl -tag -width "VDEV_UPATH" .It Sy VDEV_UPATH -Underlying path to the vdev (/dev/sd*). For use with device mapper, -multipath, or partitioned vdevs. -.El -.Bl -tag -width "VDEV_ENC_SYSFS_PATH" +Underlying path to the vdev +.Pq Pa /dev/sd* . +For use with device mapper, multipath, or partitioned vdevs. .It Sy VDEV_ENC_SYSFS_PATH The sysfs path to the enclosure for the vdev (if any). .El .It Fl T Sy u Ns | Ns Sy d Display a time stamp. Specify .Sy u for a printed representation of the internal representation of time. See .Xr time 2 . Specify .Sy d for standard date format. See .Xr date 1 . .It Fl g -Display vdev GUIDs instead of the normal device names. These GUIDs -can be used in place of device names for the zpool +Display vdev GUIDs instead of the normal device names. +These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. .It Fl H -Scripted mode. Do not display headers, and separate fields by a +Scripted mode. +Do not display headers, and separate fields by a single tab instead of arbitrary space. .It Fl L -Display real paths for vdevs resolving all symbolic links. This can -be used to look up the current block device name regardless of the +Display real paths for vdevs resolving all symbolic links. +This can be used to look up the current block device name regardless of the .Pa /dev/disk/ path used to open it. .It Fl n Print headers only once when passed .It Fl p -Display numbers in parsable (exact) values. Time values are in -nanoseconds. +Display numbers in parsable (exact) values. +Time values are in nanoseconds. .It Fl P -Display full paths for vdevs instead of only the last component of -the path. This can be used in conjunction with the +Display full paths for vdevs instead of only the last component of the path. +This can be used in conjunction with the .Fl L flag. .It Fl r -Print request size histograms for the leaf vdev's IO. This includes -histograms of individual IOs (ind) and aggregate IOs (agg). These stats -can be useful for observing how well IO aggregation is working. Note -that TRIM IOs may exceed 16M, but will be counted as 16M. +Print request size histograms for the leaf vdev's I/O. +This includes histograms of individual I/O (ind) and aggregate I/O (agg). +These stats can be useful for observing how well I/O aggregation is working. +Note that TRIM I/O may exceed 16M, but will be counted as 16M. .It Fl v Verbose statistics Reports usage statistics for individual vdevs within the pool, in addition to the pool-wide statistics. .It Fl y -Omit statistics since boot. -Normally the first line of output reports the statistics since boot. -This option suppresses that first line of output. -.Ar interval +Normally the first line of output reports the statistics since boot: +suppress it. .It Fl w Display latency histograms: -.Pp -.Ar total_wait : -Total IO time (queuing + disk IO time). -.Ar disk_wait : -Disk IO time (time reading/writing the disk). -.Ar syncq_wait : -Amount of time IO spent in synchronous priority queues. Does not include -disk time. -.Ar asyncq_wait : -Amount of time IO spent in asynchronous priority queues. Does not include -disk time. -.Ar scrub : -Amount of time IO spent in scrub queue. Does not include disk time. +.Bl -tag -compact -width "asyncq_read/write" +.It Sy total_wait +Total I/O time (queuing + disk I/O time). +.It Sy disk_wait +Disk I/O time (time reading/writing the disk). +.It Sy syncq_wait +Amount of time I/O spent in synchronous priority queues. +Does not include disk time. +.It Sy asyncq_wait +Amount of time I/O spent in asynchronous priority queues. +Does not include disk time. +.It Sy scrub +Amount of time I/O spent in scrub queue. +Does not include disk time. +.El .It Fl l Include average latency statistics: -.Pp -.Ar total_wait : -Average total IO time (queuing + disk IO time). -.Ar disk_wait : -Average disk IO time (time reading/writing the disk). -.Ar syncq_wait : -Average amount of time IO spent in synchronous priority queues. Does -not include disk time. -.Ar asyncq_wait : -Average amount of time IO spent in asynchronous priority queues. +.Bl -tag -compact -width "asyncq_read/write" +.It Sy total_wait +Average total I/O time (queuing + disk I/O time). +.It Sy disk_wait +Average disk I/O time (time reading/writing the disk). +.It Sy syncq_wait +Average amount of time I/O spent in synchronous priority queues. +Does not include disk time. +.It Sy asyncq_wait +Average amount of time I/O spent in asynchronous priority queues. +Does not include disk time. +.It Sy scrub +Average queuing time in scrub queue. Does not include disk time. -.Ar scrub : -Average queuing time in scrub queue. Does not include disk time. -.Ar trim : -Average queuing time in trim queue. Does not include disk time. +.It Sy trim +Average queuing time in trim queue. +Does not include disk time. +.El .It Fl q -Include active queue statistics. Each priority queue has both -pending ( -.Ar pend ) -and active ( -.Ar activ ) -IOs. Pending IOs are waiting to -be issued to the disk, and active IOs have been issued to disk and are -waiting for completion. These stats are broken out by priority queue: -.Pp -.Ar syncq_read/write : +Include active queue statistics. +Each priority queue has both pending +.Sy ( pend ) +and active +.Sy ( activ ) +I/O requests. +Pending requests are waiting to be issued to the disk, +and active requests have been issued to disk and are waiting for completion. +These stats are broken out by priority queue: +.Bl -tag -compact -width "asyncq_read/write" +.It Sy syncq_read/write Current number of entries in synchronous priority queues. -.Ar asyncq_read/write : +.It Sy asyncq_read/write Current number of entries in asynchronous priority queues. -.Ar scrubq_read : +.It Sy scrubq_read Current number of entries in scrub queue. -.Ar trimq_write : +.It Sy trimq_write Current number of entries in trim queue. +.El .Pp All queue statistics are instantaneous measurements of the number of -entries in the queues. If you specify an interval, the measurements -will be sampled from the end of the interval. -.El +entries in the queues. +If you specify an interval, +the measurements will be sampled from the end of the interval. .El +. .Sh SEE ALSO -.Xr zpool-list 8 , -.Xr zpool-status 8 , .Xr iostat 1 , -.Xr smartctl 8 +.Xr smartctl 8 , +.Xr zpool-list 8 , +.Xr zpool-status 8 diff --git a/man/man8/zpool-list.8 b/man/man8/zpool-list.8 index 4b3aae74cac1..3dec7370c5e8 100644 --- a/man/man8/zpool-list.8 +++ b/man/man8/zpool-list.8 @@ -1,119 +1,112 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-LIST 8 .Os +. .Sh NAME .Nm zpool-list -.Nd Lists ZFS storage pools along with a health status and space usage +.Nd list information about ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm list .Op Fl HgLpPv -.Op Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... +.Op Fl o Ar property Ns Oo , Ns Ar property Oc Ns … .Op Fl T Sy u Ns | Ns Sy d -.Oo Ar pool Oc Ns ... +.Oo Ar pool Oc Ns … .Op Ar interval Op Ar count +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm list -.Op Fl HgLpPv -.Op Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... -.Op Fl T Sy u Ns | Ns Sy d -.Oo Ar pool Oc Ns ... -.Op Ar interval Op Ar count -.Xc Lists the given pools along with a health status and space usage. If no .Ar pool Ns s are specified, all pools in the system are listed. When given an .Ar interval , the information is printed every .Ar interval -seconds until ^C is pressed. +seconds until killed. If .Ar count is specified, the command exits after .Ar count reports are printed. .Bl -tag -width Ds .It Fl g -Display vdev GUIDs instead of the normal device names. These GUIDs -can be used in place of device names for the zpool +Display vdev GUIDs instead of the normal device names. +These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. .It Fl H Scripted mode. Do not display headers, and separate fields by a single tab instead of arbitrary space. .It Fl o Ar property Comma-separated list of properties to display. See the .Xr zpoolprops 8 manual page for a list of valid properties. The default list is -.Cm name , size , allocated , free , checkpoint, expandsize , fragmentation , -.Cm capacity , dedupratio , health , altroot . +.Sy name , size , allocated , free , checkpoint, expandsize , fragmentation , +.Sy capacity , dedupratio , health , altroot . .It Fl L -Display real paths for vdevs resolving all symbolic links. This can -be used to look up the current block device name regardless of the -/dev/disk/ path used to open it. +Display real paths for vdevs resolving all symbolic links. +This can be used to look up the current block device name regardless of the +.Pa /dev/disk +path used to open it. .It Fl p Display numbers in parsable .Pq exact values. .It Fl P Display full paths for vdevs instead of only the last component of -the path. This can be used in conjunction with the +the path. +This can be used in conjunction with the .Fl L flag. .It Fl T Sy u Ns | Ns Sy d Display a time stamp. Specify .Sy u for a printed representation of the internal representation of time. See .Xr time 2 . Specify .Sy d for standard date format. See .Xr date 1 . .It Fl v Verbose statistics. Reports usage statistics for individual vdevs within the pool, in addition to the pool-wide statistics. .El -.El +. .Sh SEE ALSO .Xr zpool-import 8 , .Xr zpool-status 8 diff --git a/man/man8/zpool-offline.8 b/man/man8/zpool-offline.8 index 3bf3bae72541..9b2cf59cf414 100644 --- a/man/man8/zpool-offline.8 +++ b/man/man8/zpool-offline.8 @@ -1,89 +1,94 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-OFFLINE 8 .Os +. .Sh NAME .Nm zpool-offline -.Nd Take a physical device in a ZFS storage pool offline +.Nd take physical devices offline in ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm offline -.Op Fl f -.Op Fl t -.Ar pool Ar device Ns ... +.Op Fl ft +.Ar pool +.Ar device Ns … .Nm zpool .Cm online .Op Fl e -.Ar pool Ar device Ns ... +.Ar pool +.Ar device Ns … +. .Sh DESCRIPTION .Bl -tag -width Ds .It Xo .Nm zpool .Cm offline -.Op Fl f -.Op Fl t -.Ar pool Ar device Ns ... +.Op Fl ft +.Ar pool +.Ar device Ns … .Xc Takes the specified physical device offline. While the .Ar device is offline, no attempt is made to read or write to the device. This command is not applicable to spares. .Bl -tag -width Ds .It Fl f -Force fault. Instead of offlining the disk, put it into a faulted -state. The fault will persist across imports unless the +Force fault. +Instead of offlining the disk, put it into a faulted state. +The fault will persist across imports unless the .Fl t flag was specified. .It Fl t Temporary. Upon reboot, the specified physical device reverts to its previous state. .El .It Xo .Nm zpool .Cm online .Op Fl e -.Ar pool Ar device Ns ... +.Ar pool +.Ar device Ns … .Xc Brings the specified physical device online. This command is not applicable to spares. .Bl -tag -width Ds .It Fl e Expand the device to use all available space. If the device is part of a mirror or raidz then all devices must be expanded before the new space will become available to the pool. .El .El +. .Sh SEE ALSO .Xr zpool-detach 8 , .Xr zpool-remove 8 , .Xr zpool-reopen 8 , .Xr zpool-resilver 8 diff --git a/man/man8/zpool-remove.8 b/man/man8/zpool-remove.8 index f491cd40ac5c..5d866cb50d4d 100644 --- a/man/man8/zpool-remove.8 +++ b/man/man8/zpool-remove.8 @@ -1,111 +1,111 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-REMOVE 8 .Os .Sh NAME .Nm zpool-remove -.Nd Remove a device from a ZFS storage pool +.Nd remove devices from ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm remove .Op Fl npw -.Ar pool Ar device Ns ... +.Ar pool Ar device Ns … .Nm zpool .Cm remove .Fl s .Ar pool .Sh DESCRIPTION .Bl -tag -width Ds .It Xo .Nm zpool .Cm remove .Op Fl npw -.Ar pool Ar device Ns ... +.Ar pool Ar device Ns … .Xc Removes the specified device from the pool. This command supports removing hot spare, cache, log, and both mirrored and non-redundant primary top-level vdevs, including dedup and special vdevs. When the primary pool storage includes a top-level raidz vdev only hot spare, cache, and log devices can be removed. Note that keys for all encrypted datasets must be loaded for top-level vdevs to be removed. -.sp +.Pp Removing a top-level vdev reduces the total amount of space in the storage pool. The specified device will be evacuated by copying all allocated space from it to the other devices in the pool. In this case, the .Nm zpool Cm remove command initiates the removal and returns, while the evacuation continues in the background. The removal progress can be monitored with .Nm zpool Cm status . -If an IO error is encountered during the removal process it will be -cancelled. The +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 . .Pp A mirrored top-level device (log or data) can be removed by specifying the top-level mirror for the same. Non-log devices or data devices that are part of a mirrored configuration can be removed using the .Nm zpool Cm detach command. .Bl -tag -width Ds .It Fl n -Do not actually perform the removal ("no-op"). +Do not actually perform the removal +.Pq Qq No-op . Instead, print the estimated amount of memory that will be used by the mapping table after the removal completes. This is nonzero only for top-level vdevs. .El .Bl -tag -width Ds .It Fl p Used in conjunction with the .Fl n flag, displays numbers as parsable (exact) values. .It Fl w Waits until the removal has completed before returning. .El .It Xo .Nm zpool .Cm remove .Fl s .Ar pool .Xc Stops and cancels an in-progress removal of a top-level vdev. .El .Sh SEE ALSO .Xr zpool-add 8 , .Xr zpool-detach 8 , -.Xr zpool-offline 8 , .Xr zpool-labelclear 8 , +.Xr zpool-offline 8 , .Xr zpool-replace 8 , .Xr zpool-split 8 diff --git a/man/man8/zpool-reopen.8 b/man/man8/zpool-reopen.8 index 6f804cc7e5f2..f1f8606f12c7 100644 --- a/man/man8/zpool-reopen.8 +++ b/man/man8/zpool-reopen.8 @@ -1,55 +1,52 @@ .\" .\" 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 August 9, 2019 +.Dd June 2, 2021 .Dt ZPOOL-REOPEN 8 .Os +. .Sh NAME .Nm zpool-reopen -.Nd Reopen all virtual devices (vdevs) associated with a ZFS storage pool +.Nd reopen vdevs associated with ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm reopen .Op Fl n -.Ar pool +.Oo Ar pool Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm reopen -.Op Fl n -.Ar pool -.Xc -Reopen all the vdevs associated with the pool. -.Bl -tag -width Ds +Reopen all vdevs associated with the specified pools, +or all pools if none specified. +. +.Sh OPTIONS +.Bl -tag -width "-n" .It Fl n -Do not restart an in-progress scrub operation. This is not recommended and can +Do not restart an in-progress scrub operation. +This is not recommended and can result in partially resilvered devices unless a second scrub is performed. .El -.El diff --git a/man/man8/zpool-replace.8 b/man/man8/zpool-replace.8 index ae2e66344870..eadb5681895b 100644 --- a/man/man8/zpool-replace.8 +++ b/man/man8/zpool-replace.8 @@ -1,105 +1,99 @@ .\" .\" 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 May 15, 2020 +.Dd May 29, 2021 .Dt ZPOOL-REPLACE 8 .Os +. .Sh NAME .Nm zpool-replace -.Nd Replace one device with another in a ZFS storage pool +.Nd replace one device with another in ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm replace .Op Fl fsw .Oo Fl o Ar property Ns = Ns Ar value Oc -.Ar pool Ar device Op Ar new_device +.Ar pool Ar device Op Ar new-device +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm replace -.Op Fl fsw -.Op Fl o Ar property Ns = Ns Ar value -.Ar pool Ar device Op Ar new_device -.Xc Replaces -.Ar old_device +.Ar device with -.Ar new_device . +.Ar new-device . This is equivalent to attaching -.Ar new_device , +.Ar new-device , waiting for it to resilver, and then detaching -.Ar old_device . +.Ar device . Any in progress scrub will be cancelled. .Pp The size of -.Ar new_device +.Ar new-device must be greater than or equal to the minimum size of all the devices in a mirror or raidz configuration. .Pp -.Ar new_device +.Ar new-device is required if the pool is not redundant. If -.Ar new_device +.Ar new-device is not specified, it defaults to -.Ar old_device . +.Ar device . This form of replacement is useful after an existing disk has failed and has been physically replaced. In this case, the new disk may have the same .Pa /dev path as the old device, even though it is actually a different disk. ZFS recognizes this. .Bl -tag -width Ds .It Fl f Forces use of -.Ar new_device , +.Ar new-device , even if it appears to be in use. 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 +Sets the given pool properties. +See the .Xr zpoolprops 8 manual page for a list of valid properties that can be set. The only property supported at the moment is .Sy ashift . .It Fl s The -.Ar new_device +.Ar new-device is reconstructed sequentially to restore redundancy as quickly as possible. Checksums are not verfied during sequential reconstruction so a scrub is started when the resilver completes. Sequential reconstruction is not supported for raidz configurations. .It Fl w Waits until the replacement has completed before returning. .El -.El +. .Sh SEE ALSO .Xr zpool-detach 8 , .Xr zpool-initialize 8 , .Xr zpool-online 8 , .Xr zpool-resilver 8 diff --git a/man/man8/zpool-resilver.8 b/man/man8/zpool-resilver.8 index 602e296fea11..1ef316ac1825 100644 --- a/man/man8/zpool-resilver.8 +++ b/man/man8/zpool-resilver.8 @@ -1,59 +1,56 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-RESILVER 8 .Os +. .Sh NAME .Nm zpool-resilver -.Nd Start a resilver of a device in a ZFS storage pool +.Nd resilver devices in ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm resilver -.Ar pool Ns ... +.Ar pool Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm resilver -.Ar pool Ns ... -.Xc -Starts a resilver. If an existing resilver is already running it will be -restarted from the beginning. Any drives that were scheduled for a deferred -resilver will be added to the new one. This requires the +Starts a resilver of the specified pools. +If an existing resilver is already running it will be restarted from the beginning. +Any drives that were scheduled for a deferred +resilver will be added to the new one. +This requires the .Sy resilver_defer -feature. -.El +pool feature. +. .Sh SEE ALSO .Xr zpool-iostat 8 , .Xr zpool-online 8 , .Xr zpool-reopen 8 , .Xr zpool-replace 8 , .Xr zpool-scrub 8 , .Xr zpool-status 8 diff --git a/man/man8/zpool-scrub.8 b/man/man8/zpool-scrub.8 index 6ff2eb261017..10375b6393ac 100644 --- a/man/man8/zpool-scrub.8 +++ b/man/man8/zpool-scrub.8 @@ -1,105 +1,98 @@ .\" .\" 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 August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOL-SCRUB 8 .Os +. .Sh NAME .Nm zpool-scrub -.Nd Begin a scrub or resume a paused scrub of a ZFS storage pool +.Nd begin or resume scrub of ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm scrub -.Op Fl s | Fl p +.Op Fl s Ns | Ns Fl p .Op Fl w -.Ar pool Ns ... +.Ar pool Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm scrub -.Op Fl s | Fl p -.Op Fl w -.Ar pool Ns ... -.Xc Begins a scrub or resumes a paused scrub. The scrub examines all data in the specified pools to verify that it checksums correctly. For replicated .Pq mirror, raidz, or draid devices, ZFS automatically repairs any damage discovered during the scrub. The .Nm zpool Cm status command reports the progress of the scrub and summarizes the results of the scrub upon completion. .Pp Scrubbing and resilvering are very similar operations. The difference is that resilvering only examines data that ZFS knows to be out of date .Po for example, when attaching a new device to a mirror or replacing an existing device .Pc , whereas scrubbing examines all data to discover silent errors due to hardware faults or disk failure. .Pp Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows one at a time. If a scrub is paused, the .Nm zpool Cm scrub resumes it. If a resilver is in progress, ZFS does not allow a scrub to be started until the resilver completes. .Pp Note that, due to changes in pool data on a live system, it is possible for -scrubs to progress slightly beyond 100% completion. During this period, no -completion time estimate will be provided. -.Bl -tag -width Ds +scrubs to progress slightly beyond 100% completion. +During this period, no completion time estimate will be provided. +. +.Sh OPTIONS +.Bl -tag -width "-s" .It Fl s Stop scrubbing. -.El -.Bl -tag -width Ds .It Fl p Pause scrubbing. Scrub pause state and progress are periodically synced to disk. If the system is restarted or pool is exported during a paused scrub, even after import, scrub will remain paused until it is resumed. Once resumed the scrub will pick up from the place where it was last checkpointed to disk. To resume a paused scrub issue .Nm zpool Cm scrub again. .It Fl w Wait until scrub has completed before returning. .El -.El +. .Sh SEE ALSO .Xr zpool-iostat 8 , .Xr zpool-resilver 8 , .Xr zpool-status 8 diff --git a/man/man8/zpool-split.8 b/man/man8/zpool-split.8 index 54cb8aa7de1c..7a1a13d5db41 100644 --- a/man/man8/zpool-split.8 +++ b/man/man8/zpool-split.8 @@ -1,124 +1,116 @@ .\" .\" 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 August 9, 2019 +.Dd June 2, 2021 .Dt ZPOOL-SPLIT 8 .Os +. .Sh NAME .Nm zpool-split -.Nd Split devices off a ZFS storage pool creating a new pool +.Nd split devices off ZFS storage pool, creating new pool .Sh SYNOPSIS .Nm zpool .Cm split .Op Fl gLlnP -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... +.Oo Fl o Ar property Ns = Ns Ar value Oc Ns … .Op Fl R Ar root .Ar pool newpool -.Oo Ar device Oc Ns ... +.Oo Ar device Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm split -.Op Fl gLlnP -.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... -.Op Fl R Ar root -.Ar pool newpool -.Op Ar device ... -.Xc Splits devices off .Ar pool creating .Ar newpool . All vdevs in .Ar pool must be mirrors and the pool must not be in the process of resilvering. At the time of the split, .Ar newpool will be a replica of .Ar pool . By default, the last device in each mirror is split from .Ar pool to create .Ar newpool . .Pp The optional device specification causes the specified device(s) to be included in the new .Ar pool and, should any devices remain unspecified, the last device in each mirror is used as would be by default. .Bl -tag -width Ds .It Fl g -Display vdev GUIDs instead of the normal device names. These GUIDs -can be used in place of device names for the zpool +Display vdev GUIDs instead of the normal device names. +These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. .It Fl L -Display real paths for vdevs resolving all symbolic links. This can -be used to look up the current block device name regardless of the +Display real paths for vdevs resolving all symbolic links. +This can be used to look up the current block device name regardless of the .Pa /dev/disk/ path used to open it. .It Fl l Indicates that this command will request encryption keys for all encrypted -datasets it attempts to mount as it is bringing the new pool online. Note that -if any datasets have a -.Sy keylocation -of -.Sy prompt -this command will block waiting for the keys to be entered. Without this flag -encrypted datasets will be left unavailable until the keys are loaded. +datasets it attempts to mount as it is bringing the new pool online. +Note that if any datasets have +.Sy keylocation Ns = Ns Sy prompt , +this command will block waiting for the keys to be entered. +Without this flag, encrypted datasets will be left unavailable until the keys are loaded. .It Fl n -Do dry run, do not actually perform the split. +Do a dry-run +.Pq Qq No-op +split: do not actually perform it. Print out the expected configuration of .Ar newpool . .It Fl P Display full paths for vdevs instead of only the last component of -the path. This can be used in conjunction with the +the path. +This can be used in conjunction with the .Fl L flag. .It Fl o Ar property Ns = Ns Ar value Sets the specified property for .Ar newpool . See the .Xr zpoolprops 8 manual page for more information on the available pool properties. .It Fl R Ar root Set .Sy altroot for .Ar newpool to .Ar root and automatically import it. .El -.El +. .Sh SEE ALSO .Xr zpool-import 8 , .Xr zpool-list 8 , .Xr zpool-remove 8 diff --git a/man/man8/zpool-status.8 b/man/man8/zpool-status.8 index 54f0987b80c6..da5f95e29cdc 100644 --- a/man/man8/zpool-status.8 +++ b/man/man8/zpool-status.8 @@ -1,138 +1,134 @@ .\" .\" 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 May 15, 2020 +.Dd June 2, 2021 .Dt ZPOOL-STATUS 8 .Os +. .Sh NAME .Nm zpool-status -.Nd Display detailed health status for the given ZFS storage pools +.Nd show detailed health status for ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm status -.Oo Fl c Ar SCRIPT Oc .Op Fl DigLpPstvx .Op Fl T Sy u Ns | Ns Sy d -.Oo Ar pool Oc Ns ... +.Op Fl c Op Ar SCRIPT1 Ns Oo , Ns Ar SCRIPT2 Oc Ns … +.Oo Ar pool Oc Ns … .Op Ar interval Op Ar count +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm status -.Op Fl c Op Ar SCRIPT1 Ns Oo , Ns Ar SCRIPT2 Oc Ns ... -.Op Fl DigLpPstvx -.Op Fl T Sy u Ns | Ns Sy d -.Oo Ar pool Oc Ns ... -.Op Ar interval Op Ar count -.Xc Displays the detailed health status for the given pools. If no .Ar pool is specified, then the status of each pool in the system is displayed. For more information on pool and device health, see the -.Em Device Failure and Recovery +.Sx Device Failure and Recovery section of .Xr zpoolconcepts 8 . .Pp If a scrub or resilver is in progress, this command reports the percentage done and the estimated time to completion. Both of these are only approximate, because the amount of data in the pool and the other workloads on the system can change. .Bl -tag -width Ds -.It Fl c Op Ar SCRIPT1 Ns Oo , Ns Ar SCRIPT2 Oc Ns ... +.It Fl c Op Ar SCRIPT1 Ns Oo , Ns Ar SCRIPT2 Oc Ns … Run a script (or scripts) on each vdev and include the output as a new column in the .Nm zpool Cm status -output. See the +output. +See the .Fl c option of .Nm zpool Cm iostat for complete details. .It Fl i Display vdev initialization status. .It Fl g -Display vdev GUIDs instead of the normal device names. These GUIDs -can be used in place of device names for the zpool +Display vdev GUIDs instead of the normal device names +These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. .It Fl L -Display real paths for vdevs resolving all symbolic links. This can -be used to look up the current block device name regardless of the +Display real paths for vdevs resolving all symbolic links. +This can be used to look up the current block device name regardless of the .Pa /dev/disk/ path used to open it. .It Fl p Display numbers in parsable (exact) values. .It Fl P Display full paths for vdevs instead of only the last component of -the path. This can be used in conjunction with the +the path. +This can be used in conjunction with the .Fl L flag. .It Fl D Display a histogram of deduplication statistics, showing the allocated .Pq physically present on disk and referenced .Pq logically referenced in the pool block counts and sizes by reference count. .It Fl s -Display the number of leaf VDEV slow IOs. This is the number of IOs that -didn't complete in \fBzio_slow_io_ms\fR milliseconds (default 30 seconds). +Display the number of leaf VDEV slow IOs. +This is the number of IOs that +didn't complete in +.Sy zio_slow_io_ms +milliseconds (default 30 seconds). This does not necessarily mean the IOs failed to complete, just took an -unreasonably long amount of time. This may indicate a problem with the -underlying storage. +unreasonably long amount of time. +This may indicate a problem with the underlying storage. .It Fl t Display vdev TRIM status. .It Fl T Sy u Ns | Ns Sy d Display a time stamp. Specify .Sy u for a printed representation of the internal representation of time. See .Xr time 2 . Specify .Sy d for standard date format. See .Xr date 1 . .It Fl v Displays verbose data error information, printing out a complete list of all data errors since the last complete pool scrub. .It Fl x Only display status for pools that are exhibiting errors or are otherwise unavailable. Warnings about pools not using the latest on-disk format will not be included. .El -.El +. .Sh SEE ALSO .Xr zpool-events 8 , .Xr zpool-history 8 , .Xr zpool-iostat 8 , .Xr zpool-list 8 , .Xr zpool-resilver 8 , .Xr zpool-scrub 8 , .Xr zpool-wait 8 diff --git a/man/man8/zpool-sync.8 b/man/man8/zpool-sync.8 index 027d129d181c..6d4aa2c29c48 100644 --- a/man/man8/zpool-sync.8 +++ b/man/man8/zpool-sync.8 @@ -1,57 +1,53 @@ .\" .\" 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 August 9, 2019 .Dt ZPOOL-SYNC 8 .Os +. .Sh NAME .Nm zpool-sync -.Nd Force data to be written to primary storage of a ZFS storage pool and update reporting data +.Nd flush data to primary storage of ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm sync -.Oo Ar pool Oc Ns ... +.Oo Ar pool Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm sync -.Op Ar pool ... -.Xc This command forces all in-core dirty data to be written to the primary -pool storage and not the ZIL. It will also update administrative -information including quota reporting. Without arguments, -.Sy zpool sync -will sync all pools on the system. Otherwise, it will sync only the -specified pool(s). -.El +pool storage and not the ZIL. +It will also update administrative information including quota reporting. +Without arguments, +.Nm zpool Cm sync +will sync all pools on the system. +Otherwise, it will sync only the specified pools. +. .Sh SEE ALSO -.Xr zpoolconcepts 8 , .Xr zpool-export 8 , -.Xr zpool-iostat 8 +.Xr zpool-iostat 8 , +.Xr zpoolconcepts 8 diff --git a/man/man8/zpool-trim.8 b/man/man8/zpool-trim.8 index 1d8bc6e44a24..f709dd85414c 100644 --- a/man/man8/zpool-trim.8 +++ b/man/man8/zpool-trim.8 @@ -1,94 +1,91 @@ .\" .\" 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 February 25, 2020 +.Dd May 27, 2021 .Dt ZPOOL-TRIM 8 .Os +. .Sh NAME .Nm zpool-trim -.Nd Initiate immediate TRIM operations for all free space in a ZFS storage pool +.Nd initiate TRIM of free space in ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm trim .Op Fl dw .Op Fl r Ar rate -.Op Fl c | Fl s +.Op Fl c Ns | Ns Fl s .Ar pool -.Op Ar device Ns ... +.Oo Ar device Ns Oc Ns … +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm trim -.Op Fl dw -.Op Fl c | Fl s -.Ar pool -.Op Ar device Ns ... -.Xc Initiates an immediate on-demand TRIM operation for all of the free space in -a pool. This operation informs the underlying storage devices of all blocks +a pool. +This operation informs the underlying storage devices of all blocks in the pool which are no longer allocated and allows thinly provisioned devices to reclaim the space. .Pp A manual on-demand TRIM operation can be initiated irrespective of the .Sy autotrim -pool property setting. See the documentation for the +pool property setting. +See the documentation for the .Sy autotrim property above for the types of vdev devices which can be trimmed. .Bl -tag -width Ds -.It Fl d -secure -Causes a secure TRIM to be initiated. When performing a secure TRIM, the +.It Fl d , -secure +Causes a secure TRIM to be initiated. +When performing a secure TRIM, the device guarantees that data stored on the trimmed blocks has been erased. This requires support from the device and is not supported by all SSDs. -.It Fl r -rate Ar rate -Controls the rate at which the TRIM operation progresses. Without this -option TRIM is executed as quickly as possible. The rate, expressed in bytes +.It Fl r , -rate Ar rate +Controls the rate at which the TRIM operation progresses. +Without this +option TRIM is executed as quickly as possible. +The rate, expressed in bytes per second, is applied on a per-vdev basis and may be set differently for each leaf vdev. -.It Fl c, -cancel +.It Fl c , -cancel Cancel trimming on the specified devices, or all eligible devices if none are specified. If one or more target devices are invalid or are not currently being trimmed, the command will fail and no cancellation will occur on any device. -.It Fl s -suspend +.It Fl s , -suspend Suspend trimming on the specified devices, or all eligible devices if none are specified. If one or more target devices are invalid or are not currently being trimmed, the command will fail and no suspension will occur on any device. Trimming can then be resumed by running .Nm zpool Cm trim with no flags on the relevant target devices. -.It Fl w -wait +.It Fl w , -wait Wait until the devices are done being trimmed before returning. .El -.El +. .Sh SEE ALSO .Xr zpool-initialize 8 , .Xr zpool-wait 8 , .Xr zpoolprops 8 diff --git a/man/man8/zpool-upgrade.8 b/man/man8/zpool-upgrade.8 index 15baf8a52fba..0e67e7884c72 100644 --- a/man/man8/zpool-upgrade.8 +++ b/man/man8/zpool-upgrade.8 @@ -1,108 +1,109 @@ .\" .\" 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 .\" .Dd August 9, 2019 .Dt ZPOOL-UPGRADE 8 .Os +. .Sh NAME .Nm zpool-upgrade -.Nd Manage version and feature flags of ZFS storage pools +.Nd manage version and feature flags of ZFS storage pools .Sh SYNOPSIS .Nm zpool .Cm upgrade .Nm zpool .Cm upgrade .Fl v .Nm zpool .Cm upgrade .Op Fl V Ar version -.Fl a Ns | Ns Ar pool Ns ... +.Fl a Ns | Ns Ar pool Ns … +. .Sh DESCRIPTION .Bl -tag -width Ds .It Xo .Nm zpool .Cm upgrade .Xc Displays pools which do not have all supported features enabled and pools formatted using a legacy ZFS version number. These pools can continue to be used, but some features may not be available. Use .Nm zpool Cm upgrade Fl a to enable all features on all pools (subject to the -.Fl o Ar compatibility +.Fl o Sy compatibility property). .It Xo .Nm zpool .Cm upgrade .Fl v .Xc -Displays legacy ZFS versions supported by the current software. +Displays legacy ZFS versions supported by the this version of ZFS. See .Xr zpool-features 5 -for a description of feature flags features supported by the current software. +for a description of feature flags features supported by this version of ZFS. .It Xo .Nm zpool .Cm upgrade .Op Fl V Ar version -.Fl a Ns | Ns Ar pool Ns ... +.Fl a Ns | Ns Ar pool Ns … .Xc Enables all supported features on the given pool. .Pp If the pool has specified compatibility feature sets using the -.Fl o Ar compatibility +.Fl o Sy compatibility property, only the features present in all requested compatibility sets will be -enabled. If this property is set to +enabled. +If this property is set to .Ar legacy then no upgrade will take place. .Pp Once this is done, the pool will no longer be accessible on systems that do not support feature flags. See .Xr zpool-features 5 for details on compatibility with systems that support feature flags, but do not support all features enabled on the pool. .Bl -tag -width Ds .It Fl a Enables all supported features (from specified compatibility sets, if any) on all pools. .It Fl V Ar version Upgrade to the specified legacy version. -If the -.Fl V -flag is specified, no features will be enabled on the pool. +If specified, no features will be enabled on the pool. This option can only be used to increase the version number up to the last supported legacy version number. .El .El +. .Sh SEE ALSO .Xr zpool-features 5 , +.Xr zpool-history 8 , .Xr zpoolconcepts 8 , -.Xr zpoolprops 8 , -.Xr zpool-history 8 +.Xr zpoolprops 8 diff --git a/man/man8/zpool-wait.8 b/man/man8/zpool-wait.8 index ff6d992243b8..38f4812ace10 100644 --- a/man/man8/zpool-wait.8 +++ b/man/man8/zpool-wait.8 @@ -1,114 +1,116 @@ .\" .\" 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 February 25, 2020 +.Dd May 27, 2021 .Dt ZPOOL-WAIT 8 .Os +. .Sh NAME .Nm zpool-wait -.Nd Wait for background activity to stop in a ZFS storage pool +.Nd wait for activity to stop in a ZFS storage pool .Sh SYNOPSIS .Nm zpool .Cm wait .Op Fl Hp .Op Fl T Sy u Ns | Ns Sy d -.Op Fl t Ar activity Ns Oo , Ns Ar activity Ns Oc Ns ... +.Op Fl t Ar activity Ns Oo , Ns Ar activity Ns Oc Ns … .Ar pool .Op Ar interval +. .Sh DESCRIPTION -.Bl -tag -width Ds -.It Xo -.Nm zpool -.Cm wait -.Op Fl Hp -.Op Fl T Sy u Ns | Ns Sy d -.Op Fl t Ar activity Ns Oo , Ns Ar activity Ns Oc Ns ... -.Ar pool -.Op Ar interval -.Xc Waits until all background activity of the given types has ceased in the given pool. The activity could cease because it has completed, or because it has been paused or canceled by a user, or because the pool has been exported or destroyed. If no activities are specified, the command waits until background activity of every type listed below has ceased. If there is no activity of the given types in progress, the command returns immediately. .Pp These are the possible values for .Ar activity , along with what each one waits for: -.Bd -literal - discard Checkpoint to be discarded - free 'freeing' property to become 0 - initialize All initializations to cease - replace All device replacements to cease - remove Device removal to cease - resilver Resilver to cease - scrub Scrub to cease - trim Manual trim to cease -.Ed +.Bl -tag -compact -offset Ds -width "initialize" +.It Sy discard +Checkpoint to be discarded +.It Sy free +.Sy freeing +property to become +.Sy 0 +.It Sy initialize +All initializations to cease +.It Sy replace +All device replacements to cease +.It Sy remove +Device removal to cease +.It Sy resilver +Resilver to cease +.It Sy scrub +Scrub to cease +.It Sy trim +Manual trim to cease +.El .Pp If an .Ar interval is provided, the amount of work remaining, in bytes, for each activity is printed every .Ar interval seconds. .Bl -tag -width Ds .It Fl H Scripted mode. Do not display headers, and separate fields by a single tab instead of arbitrary space. .It Fl p Display numbers in parsable (exact) values. .It Fl T Sy u Ns | Ns Sy d Display a time stamp. Specify .Sy u for a printed representation of the internal representation of time. See .Xr time 2 . Specify .Sy d for standard date format. See .Xr date 1 . .El -.El +. .Sh SEE ALSO -.Xr zpool-status 8 , .Xr zpool-checkpoint 8 , .Xr zpool-initialize 8 , -.Xr zpool-replace 8 , .Xr zpool-remove 8 , +.Xr zpool-replace 8 , .Xr zpool-resilver 8 , .Xr zpool-scrub 8 , +.Xr zpool-status 8 , .Xr zpool-trim 8 diff --git a/man/man8/zpool.8 b/man/man8/zpool.8 index 0a01807bcad6..dac35eee77b9 100644 --- a/man/man8/zpool.8 +++ b/man/man8/zpool.8 @@ -1,599 +1,563 @@ .\" .\" 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 August 9, 2019 +.Dd June 2, 2021 .Dt ZPOOL 8 .Os +. .Sh NAME .Nm zpool .Nd configure ZFS storage pools .Sh SYNOPSIS .Nm .Fl ?V .Nm .Cm version .Nm -.Cm -.Op Ar +.Cm subcommand +.Op Ar argumentss +. .Sh DESCRIPTION The .Nm command configures ZFS storage pools. A storage pool is a collection of devices that provides physical storage and data replication for ZFS datasets. All datasets within a storage pool share the same space. See .Xr zfs 8 for information on managing datasets. .Pp For an overview of creating and managing ZFS storage pools see the .Xr zpoolconcepts 8 manual page. +. .Sh SUBCOMMANDS All subcommands that modify state are logged persistently to the pool in their original form. .Pp The .Nm command provides subcommands to create and destroy storage pools, add capacity to storage pools, and provide information about the storage pools. The following subcommands are supported: .Bl -tag -width Ds .It Xo .Nm -.Fl ? +.Fl ?\& .Xc Displays a help message. .It Xo .Nm -.Fl V, -version +.Fl V , -version .Xc -An alias for the -.Nm zpool Cm version -subcommand. .It Xo .Nm .Cm version .Xc Displays the software version of the .Nm -userland utility and the zfs kernel module. +userland utility and the ZFS kernel module. .El +. .Ss Creation .Bl -tag -width Ds .It Xr zpool-create 8 Creates a new storage pool containing the virtual devices specified on the command line. .It Xr zpool-initialize 8 Begins initializing by writing to all unallocated regions on the specified devices, or all eligible devices in the pool if no individual devices are specified. .El +. .Ss Destruction .Bl -tag -width Ds .It Xr zpool-destroy 8 Destroys the given pool, freeing up any devices for other use. .It Xr zpool-labelclear 8 Removes ZFS label information from the specified .Ar device . .El +. .Ss Virtual Devices .Bl -tag -width Ds .It Xo -.Xr zpool-attach 8 / -.Xr zpool-detach 8 +.Xr zpool-attach 8 Ns / Ns Xr zpool-detach 8 .Xc Increases or decreases redundancy by -.Cm attach Ns -ing or -.Cm detach Ns -ing a device on an existing vdev (virtual device). +.Cm attach Ns ing or +.Cm detach Ns ing a device on an existing vdev (virtual device). .It Xo -.Xr zpool-add 8 / -.Xr zpool-remove 8 +.Xr zpool-add 8 Ns / Ns Xr zpool-remove 8 .Xc Adds the specified virtual devices to the given pool, or removes the specified device from the pool. .It Xr zpool-replace 8 Replaces an existing device (which may be faulted) with a new one. .It Xr zpool-split 8 Creates a new pool by splitting all mirrors in an existing pool (which decreases its redundancy). .El +. .Ss Properties Available pool properties listed in the .Xr zpoolprops 8 manual page. .Bl -tag -width Ds .It Xr zpool-list 8 Lists the given pools along with a health status and space usage. .It Xo -.Xr zpool-get 8 / -.Xr zpool-set 8 +.Xr zpool-get 8 Ns / Ns Xr zpool-set 8 .Xc Retrieves the given list of properties .Po or all properties if .Sy all is used .Pc for the specified storage pool(s). .El +. .Ss Monitoring .Bl -tag -width Ds .It Xr zpool-status 8 Displays the detailed health status for the given pools. .It Xr zpool-iostat 8 Displays logical I/O statistics for the given pools/vdevs. Physical I/Os may be observed via .Xr iostat 1 . .It Xr zpool-events 8 -Lists all recent events generated by the ZFS kernel modules. These events -are consumed by the +Lists all recent events generated by the ZFS kernel modules. +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 +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. .It Xr zpool-history 8 Displays the command history of the specified pool(s) or all pools if no pool is specified. .El +. .Ss Maintenance .Bl -tag -width Ds .It Xr zpool-scrub 8 Begins a scrub or resumes a paused scrub. .It Xr zpool-checkpoint 8 Checkpoints the current state of -.Ar pool -, which can be later restored by -.Nm zpool Cm import --rewind-to-checkpoint . +.Ar pool , +which can be later restored by +.Nm zpool Cm import Fl -rewind-to-checkpoint . .It Xr zpool-trim 8 -Initiates an immediate on-demand TRIM operation for all of the free space in -a pool. This operation informs the underlying storage devices of all blocks +Initiates an immediate on-demand TRIM operation for all of the free space in a pool. +This operation informs the underlying storage devices of all blocks in the pool which are no longer allocated and allows thinly provisioned devices to reclaim the space. .It Xr zpool-sync 8 This command forces all in-core dirty data to be written to the primary -pool storage and not the ZIL. It will also update administrative -information including quota reporting. Without arguments, -.Sy zpool sync -will sync all pools on the system. Otherwise, it will sync only the -specified pool(s). +pool storage and not the ZIL. +It will also update administrative information including quota reporting. +Without arguments, +.Nm zpool Cm sync +will sync all pools on the system. +Otherwise, it will sync only the specified pool(s). .It Xr zpool-upgrade 8 Manage the on-disk format version of storage pools. .It Xr zpool-wait 8 Waits until all background activity of the given types has ceased in the given pool. .El +. .Ss Fault Resolution .Bl -tag -width Ds .It Xo -.Xr zpool-offline 8 -.Xr zpool-online 8 +.Xr zpool-offline 8 Ns / Ns Xr zpool-online 8 .Xc Takes the specified physical device offline or brings it online. .It Xr zpool-resilver 8 -Starts a resilver. If an existing resilver is already running it will be -restarted from the beginning. +Starts a resilver. +If an existing resilver is already running it will be restarted from the beginning. .It Xr zpool-reopen 8 Reopen all the vdevs associated with the pool. .It Xr zpool-clear 8 Clears device errors in a pool. .El +. .Ss Import & Export .Bl -tag -width Ds .It Xr zpool-import 8 Make disks containing ZFS storage pools available for use on the system. .It Xr zpool-export 8 Exports the given pools from the system. .It Xr zpool-reguid 8 Generates a new unique identifier for the pool. .El +. .Sh EXIT STATUS The following exit values are returned: -.Bl -tag -width Ds +.Bl -tag -compact -offset 4n -width "a" .It Sy 0 Successful completion. .It Sy 1 An error occurred. .It Sy 2 Invalid command line options were specified. .El +. .Sh EXAMPLES -.Bl -tag -width Ds -.It Sy Example 1 No Creating a RAID-Z Storage Pool +.Bl -tag -width "Exam" +.It Sy Example 1 : No Creating a RAID-Z Storage Pool The following command creates a pool with a single raidz root vdev that -consists of six disks. -.Bd -literal -# zpool create tank raidz sda sdb sdc sdd sde sdf -.Ed -.It Sy Example 2 No Creating a Mirrored Storage Pool +consists of six disks: +.Dl # Nm zpool Cm create Ar tank Sy raidz Ar sda sdb sdc sdd sde sdf +. +.It Sy Example 2 : No Creating a Mirrored Storage Pool The following command creates a pool with two mirrors, where each mirror -contains two disks. -.Bd -literal -# zpool create tank mirror sda sdb mirror sdc sdd -.Ed -.It Sy Example 3 No Creating a ZFS Storage Pool by Using Partitions -The following command creates an unmirrored pool using two disk partitions. -.Bd -literal -# zpool create tank sda1 sdb2 -.Ed -.It Sy Example 4 No Creating a ZFS Storage Pool by Using Files +contains two disks: +.Dl # Nm zpool Cm create Ar tank Sy mirror Ar sda sdb Sy mirror Ar sdc sdd +. +.It Sy Example 3 : No Creating a ZFS Storage Pool by Using Partitions +The following command creates an unmirrored pool using two disk partitions: +.Dl # Nm zpool Cm create Ar tank sda1 sdb2 +. +.It Sy Example 4 : No Creating a ZFS Storage Pool by Using Files The following command creates an unmirrored pool using files. While not recommended, a pool based on files can be useful for experimental purposes. -.Bd -literal -# zpool create tank /path/to/file/a /path/to/file/b -.Ed -.It Sy Example 5 No Adding a Mirror to a ZFS Storage Pool +.Dl # Nm zpool Cm create Ar tank /path/to/file/a /path/to/file/b +. +.It Sy Example 5 : No Adding a Mirror to a ZFS Storage Pool The following command adds two mirrored disks to the pool -.Em tank , +.Ar tank , assuming the pool is already made up of two-way mirrors. The additional space is immediately available to any datasets within the pool. -.Bd -literal -# zpool add tank mirror sda sdb -.Ed -.It Sy Example 6 No Listing Available ZFS Storage Pools +.Dl # Nm zpool Cm add Ar tank Sy mirror Ar sda sdb +. +.It Sy Example 6 : No Listing Available ZFS Storage Pools The following command lists all available pools on the system. In this case, the pool -.Em zion +.Ar zion is faulted due to a missing device. The results from this command are similar to the following: -.Bd -literal -# zpool list +.Bd -literal -compact -offset Ds +.No # Nm zpool Cm list NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT rpool 19.9G 8.43G 11.4G - 33% 42% 1.00x ONLINE - tank 61.5G 20.0G 41.5G - 48% 32% 1.00x ONLINE - zion - - - - - - - FAULTED - .Ed -.It Sy Example 7 No Destroying a ZFS Storage Pool +. +.It Sy Example 7 : No Destroying a ZFS Storage Pool The following command destroys the pool -.Em tank -and any datasets contained within. -.Bd -literal -# zpool destroy -f tank -.Ed -.It Sy Example 8 No Exporting a ZFS Storage Pool +.Ar tank +and any datasets contained within: +.Dl # Nm zpool Cm destroy Fl f Ar tank +. +.It Sy Example 8 : No Exporting a ZFS Storage Pool The following command exports the devices in pool -.Em tank -so that they can be relocated or later imported. -.Bd -literal -# zpool export tank -.Ed -.It Sy Example 9 No Importing a ZFS Storage Pool +.Ar tank +so that they can be relocated or later imported: +.Dl # Nm zpool Cm export Ar tank +. +.It Sy Example 9 : No Importing a ZFS Storage Pool The following command displays available pools, and then imports the pool -.Em tank +.Ar tank for use on the system. The results from this command are similar to the following: -.Bd -literal -# zpool import +.Bd -literal -compact -offset Ds +.No # Nm zpool Cm import pool: tank id: 15451357997522795478 state: ONLINE action: The pool can be imported using its name or numeric identifier. config: tank ONLINE mirror ONLINE sda ONLINE sdb ONLINE -# zpool import tank +.No # Nm zpool Cm import Ar tank .Ed -.It Sy Example 10 No Upgrading All ZFS Storage Pools to the Current Version +. +.It Sy Example 10 : No Upgrading All ZFS Storage Pools to the Current Version The following command upgrades all ZFS Storage pools to the current version of -the software. -.Bd -literal -# zpool upgrade -a +the software: +.Bd -literal -compact -offset Ds +.No # Nm zpool Cm upgrade Fl a This system is currently running ZFS version 2. .Ed -.It Sy Example 11 No Managing Hot Spares +. +.It Sy Example 11 : No Managing Hot Spares The following command creates a new pool with an available hot spare: -.Bd -literal -# zpool create tank mirror sda sdb spare sdc -.Ed +.Dl # Nm zpool Cm create Ar tank Sy mirror Ar sda sdb Sy spare Ar sdc .Pp If one of the disks were to fail, the pool would be reduced to the degraded state. The failed device can be replaced using the following command: -.Bd -literal -# zpool replace tank sda sdd -.Ed +.Dl # Nm zpool Cm replace Ar tank sda sdd .Pp Once the data has been resilvered, the spare is automatically removed and is made available for use should another device fail. The hot spare can be permanently removed from the pool using the following command: -.Bd -literal -# zpool remove tank sdc -.Ed -.It Sy Example 12 No Creating a ZFS Pool with Mirrored Separate Intent Logs +.Dl # Nm zpool Cm remove Ar tank sdc +. +.It Sy Example 12 : No Creating a ZFS Pool with Mirrored Separate Intent Logs The following command creates a ZFS storage pool consisting of two, two-way mirrors and mirrored log devices: -.Bd -literal -# zpool create pool mirror sda sdb mirror sdc sdd log mirror \\ - sde sdf -.Ed -.It Sy Example 13 No Adding Cache Devices to a ZFS Pool +.Dl # Nm zpool Cm create Ar pool Sy mirror Ar sda sdb Sy mirror Ar sdc sdd Sy log mirror Ar sde sdf +. +.It Sy Example 13 : No Adding Cache Devices to a ZFS Pool The following command adds two disks for use as cache devices to a ZFS storage pool: -.Bd -literal -# zpool add pool cache sdc sdd -.Ed +.Dl # Nm zpool Cm add Ar pool Sy cache Ar sdc sdd .Pp Once added, the cache devices gradually fill with content from main memory. Depending on the size of your cache devices, it could take over an hour for them to fill. Capacity and reads can be monitored using the .Cm iostat -option as follows: -.Bd -literal -# zpool iostat -v pool 5 -.Ed -.It Sy Example 14 No Removing a Mirrored top-level (Log or Data) Device +subcommand as follows: +.Dl # Nm zpool Cm iostat Fl v Ar pool 5 +. +.It Sy Example 14 : No Removing a Mirrored top-level (Log or Data) Device The following commands remove the mirrored log device .Sy mirror-2 and mirrored top-level data device .Sy mirror-1 . .Pp Given this configuration: -.Bd -literal +.Bd -literal -compact -offset Ds pool: tank state: ONLINE scrub: none requested config: NAME STATE READ WRITE CKSUM tank ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 sda ONLINE 0 0 0 sdb ONLINE 0 0 0 mirror-1 ONLINE 0 0 0 sdc ONLINE 0 0 0 sdd ONLINE 0 0 0 logs mirror-2 ONLINE 0 0 0 sde ONLINE 0 0 0 sdf ONLINE 0 0 0 .Ed .Pp The command to remove the mirrored log -.Sy mirror-2 -is: -.Bd -literal -# zpool remove tank mirror-2 -.Ed +.Ar mirror-2 No is: +.Dl # Nm zpool Cm remove Ar tank mirror-2 .Pp The command to remove the mirrored data -.Sy mirror-1 -is: -.Bd -literal -# zpool remove tank mirror-1 -.Ed -.It Sy Example 15 No Displaying expanded space on a device +.Ar mirror-1 No is: +.Dl # Nm zpool Cm remove Ar tank mirror-1 +. +.It Sy Example 15 : No Displaying expanded space on a device The following command displays the detailed information for the pool -.Em data . +.Ar data . This pool is comprised of a single raidz vdev where one of its devices increased its capacity by 10GB. In this example, the pool will not be able to utilize this extra capacity until all the devices under the raidz vdev have been expanded. -.Bd -literal -# zpool list -v data +.Bd -literal -compact -offset Ds +.No # Nm zpool Cm list Fl v Ar data NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT data 23.9G 14.6G 9.30G - 48% 61% 1.00x ONLINE - raidz1 23.9G 14.6G 9.30G - 48% sda - - - - - sdb - - - 10G - sdc - - - - - .Ed -.It Sy Example 16 No Adding output columns +. +.It Sy Example 16 : No Adding output columns Additional columns can be added to the -.Nm zpool Cm status -and -.Nm zpool Cm iostat -output with -.Fl c -option. -.Bd -literal -# zpool status -c vendor,model,size +.Nm zpool Cm status No and Nm zpool Cm iostat No output with Fl c . +.Bd -literal -compact -offset Ds +.No # Nm zpool Cm status Fl c Ar vendor , Ns Ar model , Ns Ar size NAME STATE READ WRITE CKSUM vendor model size tank ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 U1 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T U10 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T U11 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T U12 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T U13 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T U14 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T -# zpool iostat -vc size +.No # Nm zpool Cm iostat Fl vc Ar size capacity operations bandwidth pool alloc free read write read write size ---------- ----- ----- ----- ----- ----- ----- ---- rpool 14.6G 54.9G 4 55 250K 2.69M sda1 14.6G 54.9G 4 55 250K 2.69M 70G ---------- ----- ----- ----- ----- ----- ----- ---- .Ed .El +. .Sh ENVIRONMENT VARIABLES -.Bl -tag -width "ZFS_ABORT" -.It Ev ZFS_ABORT +.Bl -tag -compact -width "ZPOOL_IMPORT_UDEV_TIMEOUT_MS" +.It Sy ZFS_ABORT Cause -.Nm zpool +.Nm to dump core on exit for the purposes of running .Sy ::findleaks . -.El -.Bl -tag -width "ZFS_COLOR" -.It Ev ZFS_COLOR +.It Sy ZFS_COLOR Use ANSI color in .Nm zpool status output. -.El -.Bl -tag -width "ZPOOL_IMPORT_PATH" -.It Ev ZPOOL_IMPORT_PATH -The search path for devices or files to use with the pool. This is a colon-separated list of directories in which -.Nm zpool +.It Sy ZPOOL_IMPORT_PATH +The search path for devices or files to use with the pool. +This is a colon-separated list of directories in which +.Nm looks for device nodes and files. Similar to the .Fl d option in .Nm zpool import . -.El -.Bl -tag -width "ZPOOL_IMPORT_UDEV_TIMEOUT_MS" -.It Ev ZPOOL_IMPORT_UDEV_TIMEOUT_MS +.It Sy ZPOOL_IMPORT_UDEV_TIMEOUT_MS The maximum time in milliseconds that .Nm zpool import will wait for an expected device to be available. -.El -.Bl -tag -width "ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE" -.It Ev ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE +.It Sy ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE If set, suppress warning about non-native vdev ashift in .Nm zpool status . The value is not used, only the presence or absence of the variable matters. -.El -.Bl -tag -width "ZPOOL_VDEV_NAME_GUID" -.It Ev ZPOOL_VDEV_NAME_GUID +.It Sy ZPOOL_VDEV_NAME_GUID Cause -.Nm zpool -subcommands to output vdev guids by default. This behavior is identical to the +.Nm +subcommands to output vdev guids by default. +This behavior is identical to the .Nm zpool Cm status Fl g command line option. -.El -.Bl -tag -width "ZPOOL_VDEV_NAME_FOLLOW_LINKS" -.It Ev ZPOOL_VDEV_NAME_FOLLOW_LINKS +.It Sy ZPOOL_VDEV_NAME_FOLLOW_LINKS Cause -.Nm zpool -subcommands to follow links for vdev names by default. This behavior is identical to the +.Nm +subcommands to follow links for vdev names by default. +This behavior is identical to the .Nm zpool Cm status Fl L command line option. -.El -.Bl -tag -width "ZPOOL_VDEV_NAME_PATH" -.It Ev ZPOOL_VDEV_NAME_PATH +.It Sy ZPOOL_VDEV_NAME_PATH Cause -.Nm zpool -subcommands to output full vdev path names by default. This -behavior is identical to the +.Nm +subcommands to output full vdev path names by default. +This behavior is identical to the .Nm zpool Cm status Fl P command line option. -.El -.Bl -tag -width "ZFS_VDEV_DEVID_OPT_OUT" -.It Ev ZFS_VDEV_DEVID_OPT_OUT +.It Sy ZFS_VDEV_DEVID_OPT_OUT Older OpenZFS implementations had issues when attempting to display pool config VDEV names if a .Sy devid NVP value is present in the pool's config. .Pp -For example, a pool that originated on illumos platform would have a devid +For example, a pool that originated on illumos platform would have a +.Sy devid value in the config and .Nm zpool status would fail when listing the config. -This would also be true for future Linux based pools. +This would also be true for future Linux-based pools. .Pp A pool can be stripped of any .Sy devid values on import or prevented from adding them on -.Nm zpool create +.Nm zpool Cm create or -.Nm zpool add +.Nm zpool Cm add by setting .Sy ZFS_VDEV_DEVID_OPT_OUT . -.El -.Bl -tag -width "ZPOOL_SCRIPTS_AS_ROOT" -.It Ev ZPOOL_SCRIPTS_AS_ROOT -Allow a privileged user to run the -.Nm zpool status/iostat -with the -.Fl c -option. Normally, only unprivileged users are allowed to run +.Pp +.It Sy ZPOOL_SCRIPTS_AS_ROOT +Allow a privileged user to run +.Nm zpool status/iostat Fl c . +Normally, only unprivileged users are allowed to run .Fl c . -.El -.Bl -tag -width "ZPOOL_SCRIPTS_PATH" -.It Ev ZPOOL_SCRIPTS_PATH +.It Sy ZPOOL_SCRIPTS_PATH The search path for scripts when running -.Nm zpool status/iostat -with the -.Fl c -option. This is a colon-separated list of directories and overrides the default +.Nm zpool status/iostat Fl c . +This is a colon-separated list of directories and overrides the default .Pa ~/.zpool.d and .Pa /etc/zfs/zpool.d search paths. -.El -.Bl -tag -width "ZPOOL_SCRIPTS_ENABLED" -.It Ev ZPOOL_SCRIPTS_ENABLED +.It Sy ZPOOL_SCRIPTS_ENABLED Allow a user to run -.Nm zpool status/iostat -with the -.Fl c -option. If +.Nm zpool status/iostat Fl c . +If .Sy ZPOOL_SCRIPTS_ENABLED is not set, it is assumed that the user is allowed to run -.Nm zpool Cm status/iostat Fl c . +.Nm zpool Cm status Ns / Ns Cm iostat Fl c . .El +. .Sh INTERFACE STABILITY .Sy Evolving +. .Sh SEE ALSO .Xr zfs-events 5 , .Xr zfs-module-parameters 5 , .Xr zpool-features 5 , .Xr zed 8 , .Xr zfs 8 , .Xr zpool-add 8 , .Xr zpool-attach 8 , .Xr zpool-checkpoint 8 , .Xr zpool-clear 8 , .Xr zpool-create 8 , .Xr zpool-destroy 8 , .Xr zpool-detach 8 , .Xr zpool-events 8 , .Xr zpool-export 8 , .Xr zpool-get 8 , .Xr zpool-history 8 , .Xr zpool-import 8 , .Xr zpool-initialize 8 , .Xr zpool-iostat 8 , .Xr zpool-labelclear 8 , .Xr zpool-list 8 , .Xr zpool-offline 8 , .Xr zpool-online 8 , .Xr zpool-reguid 8 , .Xr zpool-remove 8 , .Xr zpool-reopen 8 , .Xr zpool-replace 8 , .Xr zpool-resilver 8 , .Xr zpool-scrub 8 , .Xr zpool-set 8 , .Xr zpool-split 8 , .Xr zpool-status 8 , .Xr zpool-sync 8 , .Xr zpool-trim 8 , .Xr zpool-upgrade 8 , .Xr zpool-wait 8 , .Xr zpoolconcepts 8 , .Xr zpoolprops 8 diff --git a/man/man8/zpoolconcepts.8 b/man/man8/zpoolconcepts.8 index b1081714eacb..80a1885fb1cb 100644 --- a/man/man8/zpoolconcepts.8 +++ b/man/man8/zpoolconcepts.8 @@ -1,503 +1,512 @@ .\" .\" 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 August 9, 2019 +.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 Ds +.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 of which it is a part. +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 N disks of size X can hold X bytes and can withstand (N-1) devices -failing without losing data. +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 +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 N disks of size X with P parity disks can hold approximately -(N-P)*X bytes and can withstand P device(s) failing without losing data. +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 D -data devices and P parity devices. +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 D=8 and 4k disk sectors the minimum allocation -size is 32k. +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 volblocksize property is increased -to account for the allocation size. +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 IO/s, performance is similar to raidz since for any read all D -data disks must be accessed. +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 -floor((N-S)/(D+P))*. +.Sy floor((N-S)/(D+P))*single_drive_IOPS . .Pp -Like raidz a dRAID can have single-, double-, or triple-parity. The +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 N disks of size X, D data disks per redundancy group, P parity -level, and S distributed hot spares can hold approximately (N-S)*(D/(D+P))*X -bytes and can withstand P device(s) failing without losing data. -.It Sy draid[][:d][:c][:s] +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. -.Pp -.Em parity -- The parity level (1-3). -.Pp -.Em data -- The number of data devices per redundancy group. -In general a smaller value of D will increase IOPS, improve the compression ratio, and speed up resilvering at the expense of total usable capacity. -Defaults to 8, unless N-P-S is less than 8. -.Pp -.Em children -- The expected number of children. +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. -.Pp -.Em spares -- The number of distributed hot spares. +.It Ar spares +The number of distributed hot spares. Defaults to zero. -.Pp -.Pp +.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 +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 +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. -The keywords -.Sy mirror -and -.Sy raidz +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 two root vdevs, each a mirror of two disks: -.Bd -literal -# zpool create mypool mirror sda sdb mirror sdc sdd -.Ed +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: online, degraded, -or faulted. +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 mirror or raidz device, is -potentially impacted by the state of its associated vdevs, or component -devices. +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 +.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 +.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). +(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 +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 -to put the device online automatically. -Device attach detection is hardware-dependent and might not be supported on all -platforms. +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, -.Bd -literal -# zpool create pool mirror sda sdb spare sdc sdd -.Ed +.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. +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 ( -.Qq draid1-2-3 specifies spare 3 of vdev 2, which is a single parity dRAID -) and may only be used by that dRAID vdev. +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: -.Bd -literal -# zpool create pool sda sdb log sdc -.Ed +.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 +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 allow much more of this +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: -.Bd -literal -# zpool create pool sda sdb cache sdc sdd -.Ed +.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 = 0 . -For cache devices smaller than 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_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 (512 bytes) is updated even if no metadata structures -are written. Setting -.Sy l2arc_headroom = 0 +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 +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 +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 +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/online the cache device when there is less memory pressure +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 (e.g -.Nm zfs Cm destroy -), an administrator can checkpoint the pool's state and in the case of a +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, while a pool has a checkpoint certain operations are not allowed. +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 +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: -.Bd -literal -# zpool checkpoint pool -.Ed +.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: -.Bd -literal -# zpool export pool -# zpool import --rewind-to-checkpoint pool -.Ed +.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: -.Bd -literal -# zpool checkpoint -d pool -.Ed +.Dl # Nm zpool Cm checkpoint Fl d Ar pool .Pp Dataset reservations (controlled by the -.Nm reservation -or -.Nm refreservation -zfs properties) may be unenforceable while a checkpoint exists, because 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 -The allocations in the special class are dedicated to specific block types. +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 (non-dedup/special) vdev before -other devices can be assigned to the special class. If the special class -becomes full, then allocations intended for it will spill back into the -normal class. +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 setting the +Deduplication tables can be excluded from the special class by unsetting the .Sy zfs_ddt_data_is_special -zfs module parameter to false (0). +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 +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 -dataset property. It defaults to zero, so you must opt-in by setting it to a -non-zero value. See -.Xr zfs 8 -for more info on setting this property. +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 index d6dc18a56c2d..050a0507288e 100644 --- a/man/man8/zpoolprops.8 +++ b/man/man8/zpoolprops.8 @@ -1,390 +1,412 @@ .\" .\" 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 .\" -.Dd August 9, 2019 +.Dd May 27, 2021 .Dt ZPOOLPROPS 8 .Os +. .Sh NAME .Nm zpoolprops -.Nd available properties for ZFS storage pools +.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 Ds +.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 +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 +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 +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 (e.g. does +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 feature_guid +.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) +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 +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=12 -(which is 1<<12 = 4096). When set, this property is +.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 +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 +vdev_id.conf. +See the .Xr vdev_id 8 -man page for more details. +manual page for more details. Autoreplace and autoonline require the ZFS Event Daemon be configured and -running. See the +running. +See the .Xr zed 8 -man page for more details. +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 +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 setting for -this property is +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 in to -a few larger ones. These can then be issued more efficiently to the storage. +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 +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 / 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. +.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 Ar off | legacy | file Bq , Ns Ar file Ns ... +.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 are enabled); when set to -.Sy legacy Ns ; -no features are 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 Ns ) +(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 are enabled. - +whitespace and/or commas. +Only features present in all files may be enabled. +.Pp See -.Xr zpool-features 5 Ns , +.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 +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 +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 -.Sy zpool create. +.Nm zpool Cm create . .Pp When this property is on, periodic writes to storage occur to show the pool is -in use. See +in use. +See .Sy zfs_multihost_interval in the .Xr zfs-module-parameters 5 -man page. In order to enable this property each host must set a unique hostid. +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 +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 diff --git a/man/man8/zstream.8 b/man/man8/zstream.8 index 0536a23f04b7..c0322ee3ace0 100644 --- a/man/man8/zstream.8 +++ b/man/man8/zstream.8 @@ -1,117 +1,117 @@ .\" .\" 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) 2020 by Delphix. All rights reserved. +.\" .Dd May 8, 2021 .Dt ZSTREAM 8 .Os +. .Sh NAME .Nm zstream -.Nd manipulate zfs send streams +.Nd manipulate ZFS send streams .Sh SYNOPSIS .Nm .Cm dump .Op Fl Cvd .Op Ar file .Nm .Cm redup .Op Fl v .Ar file .Nm .Cm token .Ar resume_token +. .Sh DESCRIPTION -.sp The .Sy zstream -utility manipulates zfs send streams, which are the output of the +utility manipulates ZFS send streams output by the .Sy zfs send command. .Bl -tag -width "" .It Xo .Nm .Cm dump .Op Fl Cvd .Op Ar file .Xc Print information about the specified send stream, including headers and record counts. The send stream may either be in the specified .Ar file , or provided on standard input. .Bl -tag -width "-D" .It Fl C Suppress the validation of checksums. .It Fl v Verbose. Print metadata for each record. .It Fl d Dump data contained in each record. Implies verbose. .El .Pp The .Nm zstreamdump alias is provided for compatibility and is equivalent to running .Nm .Cm dump . .It Xo .Nm .Cm token .Ar resume_token .Xc Dumps zfs resume token information .It Xo .Nm .Cm redup .Op Fl v .Ar file .Xc Deduplicated send streams can be generated by using the .Nm zfs Cm send Fl D command. The ability to send deduplicated send streams is deprecated. In the future, the ability to receive a deduplicated send stream with .Nm zfs Cm receive will be removed. However, deduplicated send streams can still be received by utilizing .Nm zstream Cm redup . .Pp The .Nm zstream Cm redup command is provided a .Ar file containing a deduplicated send stream, and outputs an equivalent non-deduplicated send stream on standard output. Therefore, a deduplicated send stream can be received by running: -.Bd -literal -# zstream redup DEDUP_STREAM_FILE | zfs receive ... -.Ed +.Dl # Nm zstream Cm redup Pa DEDUP_STREAM_FILE | Nm zfs Cm receive No … .Bl -tag -width "-D" .It Fl v Verbose. Print summary of converted records. .El .El +. .Sh SEE ALSO .Xr zfs 8 , -.Xr zfs-send 8 , -.Xr zfs-receive 8 +.Xr zfs-receive 8 , +.Xr zfs-send 8