diff options
Diffstat (limited to 'sys/contrib/openzfs/man/man8/zpool.8')
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zpool.8 | 657 |
1 files changed, 657 insertions, 0 deletions
diff --git a/sys/contrib/openzfs/man/man8/zpool.8 b/sys/contrib/openzfs/man/man8/zpool.8 new file mode 100644 index 000000000000..3bfef780b298 --- /dev/null +++ b/sys/contrib/openzfs/man/man8/zpool.8 @@ -0,0 +1,657 @@ +.\" SPDX-License-Identifier: CDDL-1.0 +.\" +.\" CDDL HEADER START +.\" +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or https://opensource.org/licenses/CDDL-1.0. +.\" 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 November 19, 2024 +.Dt ZPOOL 8 +.Os +. +.Sh NAME +.Nm zpool +.Nd configure ZFS storage pools +.Sh SYNOPSIS +.Nm +.Fl ?V +.Nm +.Cm version +.Op Fl j +.Nm +.Cm subcommand +.Op Ar arguments +. +.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 7 +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 ?\& +.Xc +Displays a help message. +.It Xo +.Nm +.Fl V , -version +.Xc +.It Xo +.Nm +.Cm version +.Op Fl j +.Xc +Displays the software version of the +.Nm +userland utility and the ZFS kernel module. +Use +.Fl j +option to output in JSON format. +.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 Ns / Ns Xr zpool-detach 8 +.Xc +Converts a non-redundant disk into a mirror, or increases +the redundancy level of an existing mirror +.Cm ( attach Ns ), or performs the inverse operation ( +.Cm detach Ns ). +.It Xo +.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 7 +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 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/O operations 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 +.Xr zed 8 +and used to automate administrative tasks such as replacing a failed device +with a hot spare. +That manual page also describes the subclasses and event payloads +that can be generated. +.It Xr zpool-history 8 +Displays the command history of the specified pool(s) or all pools if no pool is +specified. +.El +. +.Ss Maintenance +.Bl -tag -width Ds +.It Xr zpool-prefetch 8 +Prefetches specific types of pool data. +.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 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 +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, +.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 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. +.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 -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 +.\" Examples 1, 2, 3, 4, 12, 13 are shared with zpool-create.8. +.\" Examples 6, 14 are shared with zpool-add.8. +.\" Examples 7, 16 are shared with zpool-list.8. +.\" Examples 8 are shared with zpool-destroy.8. +.\" Examples 9 are shared with zpool-export.8. +.\" Examples 10 are shared with zpool-import.8. +.\" Examples 11 are shared with zpool-upgrade.8. +.\" Examples 15 are shared with zpool-remove.8. +.\" Examples 17 are shared with zpool-status.8. +.\" Examples 14, 17 are also shared with zpool-iostat.8. +.\" Make sure to update them omnidirectionally +.Ss 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: +.Dl # Nm zpool Cm create Ar tank Sy raidz Pa sda sdb sdc sdd sde sdf +. +.Ss Example 2 : No Creating a Mirrored Storage Pool +The following command creates a pool with two mirrors, where each mirror +contains two disks: +.Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy mirror Pa sdc sdd +. +.Ss Example 3 : No Creating a ZFS Storage Pool by Using Partitions +The following command creates a non-redundant pool using two disk partitions: +.Dl # Nm zpool Cm create Ar tank Pa sda1 sdb2 +. +.Ss Example 4 : No Creating a ZFS Storage Pool by Using Files +The following command creates a non-redundant pool using files. +While not recommended, a pool based on files can be useful for experimental +purposes. +.Dl # Nm zpool Cm create Ar tank Pa /path/to/file/a /path/to/file/b +. +.Ss Example 5 : No Making a non-mirrored ZFS Storage Pool mirrored +The following command converts an existing single device +.Ar sda +into a mirror by attaching a second device to it, +.Ar sdb . +.Dl # Nm zpool Cm attach Ar tank Pa sda sdb +. +.Ss Example 6 : No Adding a Mirror to a ZFS Storage Pool +The following command adds two mirrored disks to the pool +.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. +.Dl # Nm zpool Cm add Ar tank Sy mirror Pa sda sdb +. +.Ss Example 7 : No Listing Available ZFS Storage Pools +The following command lists all available pools on the system. +In this case, the pool +.Ar zion +is faulted due to a missing device. +The results from this command are similar to the following: +.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 +. +.Ss Example 8 : No Destroying a ZFS Storage Pool +The following command destroys the pool +.Ar tank +and any datasets contained within: +.Dl # Nm zpool Cm destroy Fl f Ar tank +. +.Ss Example 9 : No Exporting a ZFS Storage Pool +The following command exports the devices in pool +.Ar tank +so that they can be relocated or later imported: +.Dl # Nm zpool Cm export Ar tank +. +.Ss Example 10 : No Importing a ZFS Storage Pool +The following command displays available pools, and then imports the pool +.Ar tank +for use on the system. +The results from this command are similar to the following: +.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 + +.No # Nm zpool Cm import Ar tank +.Ed +. +.Ss Example 11 : 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 -compact -offset Ds +.No # Nm zpool Cm upgrade Fl a +This system is currently running ZFS version 2. +.Ed +. +.Ss Example 12 : No Managing Hot Spares +The following command creates a new pool with an available hot spare: +.Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy spare Pa 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: +.Dl # Nm zpool Cm replace Ar tank Pa 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: +.Dl # Nm zpool Cm remove Ar tank Pa sdc +. +.Ss Example 13 : 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: +.Dl # Nm zpool Cm create Ar pool Sy mirror Pa sda sdb Sy mirror Pa sdc sdd Sy log mirror Pa sde sdf +. +.Ss Example 14 : No Adding Cache Devices to a ZFS Pool +The following command adds two disks for use as cache devices to a ZFS storage +pool: +.Dl # Nm zpool Cm add Ar pool Sy cache Pa 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 +subcommand as follows: +.Dl # Nm zpool Cm iostat Fl v Ar pool 5 +. +.Ss Example 15 : 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 -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 +.Ar mirror-2 No is : +.Dl # Nm zpool Cm remove Ar tank mirror-2 +.Pp +At this point, the log device no longer exists +(both sides of the mirror have been removed): +.Bd -literal -compact -offset Ds + pool: tank + state: ONLINE + scan: 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 +.Ed +.Pp +The command to remove the mirrored data +.Ar mirror-1 No is : +.Dl # Nm zpool Cm remove Ar tank mirror-1 +.Pp +After +.Ar mirror-1 No has been evacuated, the pool remains redundant, but +the total amount of space is reduced: +.Bd -literal -compact -offset Ds + pool: tank + state: ONLINE + scan: 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 +.Ed +. +.Ss Example 16 : No Displaying expanded space on a device +The following command displays the detailed information for the pool +.Ar data . +This pool is comprised of a single raidz vdev where one of its devices +increased its capacity by 10 GiB. +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 -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 +. +.Ss Example 17 : No Adding output columns +Additional columns can be added to the +.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 Pa vendor , Ns Pa model , Ns Pa 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 + +.No # Nm zpool Cm iostat Fl vc Pa 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 +. +.Sh ENVIRONMENT VARIABLES +.Bl -tag -compact -width "ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE" +.It Sy ZFS_ABORT +Cause +.Nm +to dump core on exit for the purposes of running +.Sy ::findleaks . +.It Sy ZFS_COLOR +Use ANSI color in +.Nm zpool Cm status +and +.Nm zpool Cm iostat +output. +.It Sy ZPOOL_AUTO_POWER_ON_SLOT +Automatically attempt to turn on the drives enclosure slot power to a drive when +running the +.Nm zpool Cm online +or +.Nm zpool Cm clear +commands. +This has the same effect as passing the +.Fl -power +option to those commands. +.It Sy ZPOOL_POWER_ON_SLOT_TIMEOUT_MS +The maximum time in milliseconds to wait for a slot power sysfs value +to return the correct value after writing it. +For example, after writing "on" to the sysfs enclosure slot power_control file, +it can take some time for the enclosure to power down the slot and return +"on" if you read back the 'power_control' value. +Defaults to 30 seconds (30000ms) if not set. +.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 . +.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. +.It Sy ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE +If set, suppress warning about non-native vdev ashift in +.Nm zpool Cm status . +The value is not used, only the presence or absence of the variable matters. +.It Sy ZPOOL_VDEV_NAME_GUID +Cause +.Nm +subcommands to output vdev GUIDs by default. +This behavior is identical to the +.Nm zpool Cm status Fl g +command line option. +.It Sy ZPOOL_VDEV_NAME_FOLLOW_LINKS +Cause +.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. +.It Sy ZPOOL_VDEV_NAME_PATH +Cause +.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. +.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 +.Sy devid +value in the config and +.Nm zpool Cm status +would fail when listing the config. +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 Cm create +or +.Nm zpool Cm add +by setting +.Sy ZFS_VDEV_DEVID_OPT_OUT . +.Pp +.It Sy ZPOOL_SCRIPTS_AS_ROOT +Allow a privileged user to run +.Nm zpool Cm status Ns / Ns Cm iostat Fl c . +Normally, only unprivileged users are allowed to run +.Fl c . +.It Sy ZPOOL_SCRIPTS_PATH +The search path for scripts when running +.Nm zpool Cm status Ns / Ns Cm 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. +.It Sy ZPOOL_SCRIPTS_ENABLED +Allow a user to run +.Nm zpool Cm status Ns / Ns Cm 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 Ns / Ns Cm iostat Fl c . +.\" Shared with zfs.8 +.It Sy ZFS_MODULE_TIMEOUT +Time, in seconds, to wait for +.Pa /dev/zfs +to appear. +Defaults to +.Sy 10 , +max +.Sy 600 Pq 10 minutes . +If +.Pf < Sy 0 , +wait forever; if +.Sy 0 , +don't wait. +.El +. +.Sh INTERFACE STABILITY +.Sy Evolving +. +.Sh SEE ALSO +.Xr zfs 4 , +.Xr zpool-features 7 , +.Xr zpoolconcepts 7 , +.Xr zpoolprops 7 , +.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-ddtprune 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-prefetch 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 |