1.\" SPDX-License-Identifier: CDDL-1.0 2.\" 3.\" CDDL HEADER START 4.\" 5.\" The contents of this file are subject to the terms of the 6.\" Common Development and Distribution License (the "License"). 7.\" You may not use this file except in compliance with the License. 8.\" 9.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10.\" or https://opensource.org/licenses/CDDL-1.0. 11.\" See the License for the specific language governing permissions 12.\" and limitations under the License. 13.\" 14.\" When distributing Covered Code, include this CDDL HEADER in each 15.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16.\" If applicable, add the following below this CDDL HEADER, with the 17.\" fields enclosed by brackets "[]" replaced with your own identifying 18.\" information: Portions Copyright [yyyy] [name of copyright owner] 19.\" 20.\" CDDL HEADER END 21.\" 22.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. 23.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved. 24.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved. 25.\" Copyright (c) 2017 Datto Inc. 26.\" Copyright (c) 2018 George Melikov. All Rights Reserved. 27.\" Copyright 2017 Nexenta Systems, Inc. 28.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved. 29.\" 30.Dd February 14, 2024 31.Dt ZPOOL 8 32.Os 33. 34.Sh NAME 35.Nm zpool 36.Nd configure ZFS storage pools 37.Sh SYNOPSIS 38.Nm 39.Fl ?V 40.Nm 41.Cm version 42.Op Fl j 43.Nm 44.Cm subcommand 45.Op Ar arguments 46. 47.Sh DESCRIPTION 48The 49.Nm 50command configures ZFS storage pools. 51A storage pool is a collection of devices that provides physical storage and 52data replication for ZFS datasets. 53All datasets within a storage pool share the same space. 54See 55.Xr zfs 8 56for information on managing datasets. 57.Pp 58For an overview of creating and managing ZFS storage pools see the 59.Xr zpoolconcepts 7 60manual page. 61. 62.Sh SUBCOMMANDS 63All subcommands that modify state are logged persistently to the pool in their 64original form. 65.Pp 66The 67.Nm 68command provides subcommands to create and destroy storage pools, add capacity 69to storage pools, and provide information about the storage pools. 70The following subcommands are supported: 71.Bl -tag -width Ds 72.It Xo 73.Nm 74.Fl ?\& 75.Xc 76Displays a help message. 77.It Xo 78.Nm 79.Fl V , -version 80.Xc 81.It Xo 82.Nm 83.Cm version 84.Op Fl j 85.Xc 86Displays the software version of the 87.Nm 88userland utility and the ZFS kernel module. 89Use 90.Fl j 91option to output in JSON format. 92.El 93. 94.Ss Creation 95.Bl -tag -width Ds 96.It Xr zpool-create 8 97Creates a new storage pool containing the virtual devices specified on the 98command line. 99.It Xr zpool-initialize 8 100Begins initializing by writing to all unallocated regions on the specified 101devices, or all eligible devices in the pool if no individual devices are 102specified. 103.El 104. 105.Ss Destruction 106.Bl -tag -width Ds 107.It Xr zpool-destroy 8 108Destroys the given pool, freeing up any devices for other use. 109.It Xr zpool-labelclear 8 110Removes ZFS label information from the specified 111.Ar device . 112.El 113. 114.Ss Virtual Devices 115.Bl -tag -width Ds 116.It Xo 117.Xr zpool-attach 8 Ns / Ns Xr zpool-detach 8 118.Xc 119Converts a non-redundant disk into a mirror, or increases 120the redundancy level of an existing mirror 121.Cm ( attach Ns ), or performs the inverse operation ( 122.Cm detach Ns ). 123.It Xo 124.Xr zpool-add 8 Ns / Ns Xr zpool-remove 8 125.Xc 126Adds the specified virtual devices to the given pool, 127or removes the specified device from the pool. 128.It Xr zpool-replace 8 129Replaces an existing device (which may be faulted) with a new one. 130.It Xr zpool-split 8 131Creates a new pool by splitting all mirrors in an existing pool (which decreases 132its redundancy). 133.El 134. 135.Ss Properties 136Available pool properties listed in the 137.Xr zpoolprops 7 138manual page. 139.Bl -tag -width Ds 140.It Xr zpool-list 8 141Lists the given pools along with a health status and space usage. 142.It Xo 143.Xr zpool-get 8 Ns / Ns Xr zpool-set 8 144.Xc 145Retrieves the given list of properties 146.Po 147or all properties if 148.Sy all 149is used 150.Pc 151for the specified storage pool(s). 152.El 153. 154.Ss Monitoring 155.Bl -tag -width Ds 156.It Xr zpool-status 8 157Displays the detailed health status for the given pools. 158.It Xr zpool-iostat 8 159Displays logical I/O statistics for the given pools/vdevs. 160Physical I/O operations may be observed via 161.Xr iostat 1 . 162.It Xr zpool-events 8 163Lists all recent events generated by the ZFS kernel modules. 164These events are consumed by the 165.Xr zed 8 166and used to automate administrative tasks such as replacing a failed device 167with a hot spare. 168That manual page also describes the subclasses and event payloads 169that can be generated. 170.It Xr zpool-history 8 171Displays the command history of the specified pool(s) or all pools if no pool is 172specified. 173.El 174. 175.Ss Maintenance 176.Bl -tag -width Ds 177.It Xr zpool-prefetch 8 178Prefetches specific types of pool data. 179.It Xr zpool-scrub 8 180Begins a scrub or resumes a paused scrub. 181.It Xr zpool-checkpoint 8 182Checkpoints the current state of 183.Ar pool , 184which can be later restored by 185.Nm zpool Cm import Fl -rewind-to-checkpoint . 186.It Xr zpool-trim 8 187Initiates an immediate on-demand TRIM operation for all of the free space in a 188pool. 189This operation informs the underlying storage devices of all blocks 190in the pool which are no longer allocated and allows thinly provisioned 191devices to reclaim the space. 192.It Xr zpool-sync 8 193This command forces all in-core dirty data to be written to the primary 194pool storage and not the ZIL. 195It will also update administrative information including quota reporting. 196Without arguments, 197.Nm zpool Cm sync 198will sync all pools on the system. 199Otherwise, it will sync only the specified pool(s). 200.It Xr zpool-upgrade 8 201Manage the on-disk format version of storage pools. 202.It Xr zpool-wait 8 203Waits until all background activity of the given types has ceased in the given 204pool. 205.El 206. 207.Ss Fault Resolution 208.Bl -tag -width Ds 209.It Xo 210.Xr zpool-offline 8 Ns / Ns Xr zpool-online 8 211.Xc 212Takes the specified physical device offline or brings it online. 213.It Xr zpool-resilver 8 214Starts a resilver. 215If an existing resilver is already running it will be restarted from the 216beginning. 217.It Xr zpool-reopen 8 218Reopen all the vdevs associated with the pool. 219.It Xr zpool-clear 8 220Clears device errors in a pool. 221.El 222. 223.Ss Import & Export 224.Bl -tag -width Ds 225.It Xr zpool-import 8 226Make disks containing ZFS storage pools available for use on the system. 227.It Xr zpool-export 8 228Exports the given pools from the system. 229.It Xr zpool-reguid 8 230Generates a new unique identifier for the pool. 231.El 232. 233.Sh EXIT STATUS 234The following exit values are returned: 235.Bl -tag -compact -offset 4n -width "a" 236.It Sy 0 237Successful completion. 238.It Sy 1 239An error occurred. 240.It Sy 2 241Invalid command line options were specified. 242.El 243. 244.Sh EXAMPLES 245.\" Examples 1, 2, 3, 4, 12, 13 are shared with zpool-create.8. 246.\" Examples 6, 14 are shared with zpool-add.8. 247.\" Examples 7, 16 are shared with zpool-list.8. 248.\" Examples 8 are shared with zpool-destroy.8. 249.\" Examples 9 are shared with zpool-export.8. 250.\" Examples 10 are shared with zpool-import.8. 251.\" Examples 11 are shared with zpool-upgrade.8. 252.\" Examples 15 are shared with zpool-remove.8. 253.\" Examples 17 are shared with zpool-status.8. 254.\" Examples 14, 17 are also shared with zpool-iostat.8. 255.\" Make sure to update them omnidirectionally 256.Ss Example 1 : No Creating a RAID-Z Storage Pool 257The following command creates a pool with a single raidz root vdev that 258consists of six disks: 259.Dl # Nm zpool Cm create Ar tank Sy raidz Pa sda sdb sdc sdd sde sdf 260. 261.Ss Example 2 : No Creating a Mirrored Storage Pool 262The following command creates a pool with two mirrors, where each mirror 263contains two disks: 264.Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy mirror Pa sdc sdd 265. 266.Ss Example 3 : No Creating a ZFS Storage Pool by Using Partitions 267The following command creates a non-redundant pool using two disk partitions: 268.Dl # Nm zpool Cm create Ar tank Pa sda1 sdb2 269. 270.Ss Example 4 : No Creating a ZFS Storage Pool by Using Files 271The following command creates a non-redundant pool using files. 272While not recommended, a pool based on files can be useful for experimental 273purposes. 274.Dl # Nm zpool Cm create Ar tank Pa /path/to/file/a /path/to/file/b 275. 276.Ss Example 5 : No Making a non-mirrored ZFS Storage Pool mirrored 277The following command converts an existing single device 278.Ar sda 279into a mirror by attaching a second device to it, 280.Ar sdb . 281.Dl # Nm zpool Cm attach Ar tank Pa sda sdb 282. 283.Ss Example 6 : No Adding a Mirror to a ZFS Storage Pool 284The following command adds two mirrored disks to the pool 285.Ar tank , 286assuming the pool is already made up of two-way mirrors. 287The additional space is immediately available to any datasets within the pool. 288.Dl # Nm zpool Cm add Ar tank Sy mirror Pa sda sdb 289. 290.Ss Example 7 : No Listing Available ZFS Storage Pools 291The following command lists all available pools on the system. 292In this case, the pool 293.Ar zion 294is faulted due to a missing device. 295The results from this command are similar to the following: 296.Bd -literal -compact -offset Ds 297.No # Nm zpool Cm list 298NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT 299rpool 19.9G 8.43G 11.4G - 33% 42% 1.00x ONLINE - 300tank 61.5G 20.0G 41.5G - 48% 32% 1.00x ONLINE - 301zion - - - - - - - FAULTED - 302.Ed 303. 304.Ss Example 8 : No Destroying a ZFS Storage Pool 305The following command destroys the pool 306.Ar tank 307and any datasets contained within: 308.Dl # Nm zpool Cm destroy Fl f Ar tank 309. 310.Ss Example 9 : No Exporting a ZFS Storage Pool 311The following command exports the devices in pool 312.Ar tank 313so that they can be relocated or later imported: 314.Dl # Nm zpool Cm export Ar tank 315. 316.Ss Example 10 : No Importing a ZFS Storage Pool 317The following command displays available pools, and then imports the pool 318.Ar tank 319for use on the system. 320The results from this command are similar to the following: 321.Bd -literal -compact -offset Ds 322.No # Nm zpool Cm import 323 pool: tank 324 id: 15451357997522795478 325 state: ONLINE 326action: The pool can be imported using its name or numeric identifier. 327config: 328 329 tank ONLINE 330 mirror ONLINE 331 sda ONLINE 332 sdb ONLINE 333 334.No # Nm zpool Cm import Ar tank 335.Ed 336. 337.Ss Example 11 : No Upgrading All ZFS Storage Pools to the Current Version 338The following command upgrades all ZFS Storage pools to the current version of 339the software: 340.Bd -literal -compact -offset Ds 341.No # Nm zpool Cm upgrade Fl a 342This system is currently running ZFS version 2. 343.Ed 344. 345.Ss Example 12 : No Managing Hot Spares 346The following command creates a new pool with an available hot spare: 347.Dl # Nm zpool Cm create Ar tank Sy mirror Pa sda sdb Sy spare Pa sdc 348.Pp 349If one of the disks were to fail, the pool would be reduced to the degraded 350state. 351The failed device can be replaced using the following command: 352.Dl # Nm zpool Cm replace Ar tank Pa sda sdd 353.Pp 354Once the data has been resilvered, the spare is automatically removed and is 355made available for use should another device fail. 356The hot spare can be permanently removed from the pool using the following 357command: 358.Dl # Nm zpool Cm remove Ar tank Pa sdc 359. 360.Ss Example 13 : No Creating a ZFS Pool with Mirrored Separate Intent Logs 361The following command creates a ZFS storage pool consisting of two, two-way 362mirrors and mirrored log devices: 363.Dl # Nm zpool Cm create Ar pool Sy mirror Pa sda sdb Sy mirror Pa sdc sdd Sy log mirror Pa sde sdf 364. 365.Ss Example 14 : No Adding Cache Devices to a ZFS Pool 366The following command adds two disks for use as cache devices to a ZFS storage 367pool: 368.Dl # Nm zpool Cm add Ar pool Sy cache Pa sdc sdd 369.Pp 370Once added, the cache devices gradually fill with content from main memory. 371Depending on the size of your cache devices, it could take over an hour for 372them to fill. 373Capacity and reads can be monitored using the 374.Cm iostat 375subcommand as follows: 376.Dl # Nm zpool Cm iostat Fl v Ar pool 5 377. 378.Ss Example 15 : No Removing a Mirrored top-level (Log or Data) Device 379The following commands remove the mirrored log device 380.Sy mirror-2 381and mirrored top-level data device 382.Sy mirror-1 . 383.Pp 384Given this configuration: 385.Bd -literal -compact -offset Ds 386 pool: tank 387 state: ONLINE 388 scrub: none requested 389config: 390 391 NAME STATE READ WRITE CKSUM 392 tank ONLINE 0 0 0 393 mirror-0 ONLINE 0 0 0 394 sda ONLINE 0 0 0 395 sdb ONLINE 0 0 0 396 mirror-1 ONLINE 0 0 0 397 sdc ONLINE 0 0 0 398 sdd ONLINE 0 0 0 399 logs 400 mirror-2 ONLINE 0 0 0 401 sde ONLINE 0 0 0 402 sdf ONLINE 0 0 0 403.Ed 404.Pp 405The command to remove the mirrored log 406.Ar mirror-2 No is : 407.Dl # Nm zpool Cm remove Ar tank mirror-2 408.Pp 409At this point, the log device no longer exists 410(both sides of the mirror have been removed): 411.Bd -literal -compact -offset Ds 412 pool: tank 413 state: ONLINE 414 scan: none requested 415config: 416 417 NAME STATE READ WRITE CKSUM 418 tank ONLINE 0 0 0 419 mirror-0 ONLINE 0 0 0 420 sda ONLINE 0 0 0 421 sdb ONLINE 0 0 0 422 mirror-1 ONLINE 0 0 0 423 sdc ONLINE 0 0 0 424 sdd ONLINE 0 0 0 425.Ed 426.Pp 427The command to remove the mirrored data 428.Ar mirror-1 No is : 429.Dl # Nm zpool Cm remove Ar tank mirror-1 430.Pp 431After 432.Ar mirror-1 No has been evacuated, the pool remains redundant, but 433the total amount of space is reduced: 434.Bd -literal -compact -offset Ds 435 pool: tank 436 state: ONLINE 437 scan: none requested 438config: 439 440 NAME STATE READ WRITE CKSUM 441 tank ONLINE 0 0 0 442 mirror-0 ONLINE 0 0 0 443 sda ONLINE 0 0 0 444 sdb ONLINE 0 0 0 445.Ed 446. 447.Ss Example 16 : No Displaying expanded space on a device 448The following command displays the detailed information for the pool 449.Ar data . 450This pool is comprised of a single raidz vdev where one of its devices 451increased its capacity by 10 GiB. 452In this example, the pool will not be able to utilize this extra capacity until 453all the devices under the raidz vdev have been expanded. 454.Bd -literal -compact -offset Ds 455.No # Nm zpool Cm list Fl v Ar data 456NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT 457data 23.9G 14.6G 9.30G - 48% 61% 1.00x ONLINE - 458 raidz1 23.9G 14.6G 9.30G - 48% 459 sda - - - - - 460 sdb - - - 10G - 461 sdc - - - - - 462.Ed 463. 464.Ss Example 17 : No Adding output columns 465Additional columns can be added to the 466.Nm zpool Cm status No and Nm zpool Cm iostat No output with Fl c . 467.Bd -literal -compact -offset Ds 468.No # Nm zpool Cm status Fl c Pa vendor , Ns Pa model , Ns Pa size 469 NAME STATE READ WRITE CKSUM vendor model size 470 tank ONLINE 0 0 0 471 mirror-0 ONLINE 0 0 0 472 U1 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T 473 U10 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T 474 U11 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T 475 U12 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T 476 U13 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T 477 U14 ONLINE 0 0 0 SEAGATE ST8000NM0075 7.3T 478 479.No # Nm zpool Cm iostat Fl vc Pa size 480 capacity operations bandwidth 481pool alloc free read write read write size 482---------- ----- ----- ----- ----- ----- ----- ---- 483rpool 14.6G 54.9G 4 55 250K 2.69M 484 sda1 14.6G 54.9G 4 55 250K 2.69M 70G 485---------- ----- ----- ----- ----- ----- ----- ---- 486.Ed 487. 488.Sh ENVIRONMENT VARIABLES 489.Bl -tag -compact -width "ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE" 490.It Sy ZFS_ABORT 491Cause 492.Nm 493to dump core on exit for the purposes of running 494.Sy ::findleaks . 495.It Sy ZFS_COLOR 496Use ANSI color in 497.Nm zpool Cm status 498and 499.Nm zpool Cm iostat 500output. 501.It Sy ZPOOL_AUTO_POWER_ON_SLOT 502Automatically attempt to turn on the drives enclosure slot power to a drive when 503running the 504.Nm zpool Cm online 505or 506.Nm zpool Cm clear 507commands. 508This has the same effect as passing the 509.Fl -power 510option to those commands. 511.It Sy ZPOOL_POWER_ON_SLOT_TIMEOUT_MS 512The maximum time in milliseconds to wait for a slot power sysfs value 513to return the correct value after writing it. 514For example, after writing "on" to the sysfs enclosure slot power_control file, 515it can take some time for the enclosure to power down the slot and return 516"on" if you read back the 'power_control' value. 517Defaults to 30 seconds (30000ms) if not set. 518.It Sy ZPOOL_IMPORT_PATH 519The search path for devices or files to use with the pool. 520This is a colon-separated list of directories in which 521.Nm 522looks for device nodes and files. 523Similar to the 524.Fl d 525option in 526.Nm zpool import . 527.It Sy ZPOOL_IMPORT_UDEV_TIMEOUT_MS 528The maximum time in milliseconds that 529.Nm zpool import 530will wait for an expected device to be available. 531.It Sy ZPOOL_STATUS_NON_NATIVE_ASHIFT_IGNORE 532If set, suppress warning about non-native vdev ashift in 533.Nm zpool Cm status . 534The value is not used, only the presence or absence of the variable matters. 535.It Sy ZPOOL_VDEV_NAME_GUID 536Cause 537.Nm 538subcommands to output vdev GUIDs by default. 539This behavior is identical to the 540.Nm zpool Cm status Fl g 541command line option. 542.It Sy ZPOOL_VDEV_NAME_FOLLOW_LINKS 543Cause 544.Nm 545subcommands to follow links for vdev names by default. 546This behavior is identical to the 547.Nm zpool Cm status Fl L 548command line option. 549.It Sy ZPOOL_VDEV_NAME_PATH 550Cause 551.Nm 552subcommands to output full vdev path names by default. 553This behavior is identical to the 554.Nm zpool Cm status Fl P 555command line option. 556.It Sy ZFS_VDEV_DEVID_OPT_OUT 557Older OpenZFS implementations had issues when attempting to display pool 558config vdev names if a 559.Sy devid 560NVP value is present in the pool's config. 561.Pp 562For example, a pool that originated on illumos platform would have a 563.Sy devid 564value in the config and 565.Nm zpool Cm status 566would fail when listing the config. 567This would also be true for future Linux-based pools. 568.Pp 569A pool can be stripped of any 570.Sy devid 571values on import or prevented from adding 572them on 573.Nm zpool Cm create 574or 575.Nm zpool Cm add 576by setting 577.Sy ZFS_VDEV_DEVID_OPT_OUT . 578.Pp 579.It Sy ZPOOL_SCRIPTS_AS_ROOT 580Allow a privileged user to run 581.Nm zpool Cm status Ns / Ns Cm iostat Fl c . 582Normally, only unprivileged users are allowed to run 583.Fl c . 584.It Sy ZPOOL_SCRIPTS_PATH 585The search path for scripts when running 586.Nm zpool Cm status Ns / Ns Cm iostat Fl c . 587This is a colon-separated list of directories and overrides the default 588.Pa ~/.zpool.d 589and 590.Pa /etc/zfs/zpool.d 591search paths. 592.It Sy ZPOOL_SCRIPTS_ENABLED 593Allow a user to run 594.Nm zpool Cm status Ns / Ns Cm iostat Fl c . 595If 596.Sy ZPOOL_SCRIPTS_ENABLED 597is not set, it is assumed that the user is allowed to run 598.Nm zpool Cm status Ns / Ns Cm iostat Fl c . 599.\" Shared with zfs.8 600.It Sy ZFS_MODULE_TIMEOUT 601Time, in seconds, to wait for 602.Pa /dev/zfs 603to appear. 604Defaults to 605.Sy 10 , 606max 607.Sy 600 Pq 10 minutes . 608If 609.Pf < Sy 0 , 610wait forever; if 611.Sy 0 , 612don't wait. 613.El 614. 615.Sh INTERFACE STABILITY 616.Sy Evolving 617. 618.Sh SEE ALSO 619.Xr zfs 4 , 620.Xr zpool-features 7 , 621.Xr zpoolconcepts 7 , 622.Xr zpoolprops 7 , 623.Xr zed 8 , 624.Xr zfs 8 , 625.Xr zpool-add 8 , 626.Xr zpool-attach 8 , 627.Xr zpool-checkpoint 8 , 628.Xr zpool-clear 8 , 629.Xr zpool-create 8 , 630.Xr zpool-ddtprune 8 , 631.Xr zpool-destroy 8 , 632.Xr zpool-detach 8 , 633.Xr zpool-events 8 , 634.Xr zpool-export 8 , 635.Xr zpool-get 8 , 636.Xr zpool-history 8 , 637.Xr zpool-import 8 , 638.Xr zpool-initialize 8 , 639.Xr zpool-iostat 8 , 640.Xr zpool-labelclear 8 , 641.Xr zpool-list 8 , 642.Xr zpool-offline 8 , 643.Xr zpool-online 8 , 644.Xr zpool-prefetch 8 , 645.Xr zpool-reguid 8 , 646.Xr zpool-remove 8 , 647.Xr zpool-reopen 8 , 648.Xr zpool-replace 8 , 649.Xr zpool-resilver 8 , 650.Xr zpool-scrub 8 , 651.Xr zpool-set 8 , 652.Xr zpool-split 8 , 653.Xr zpool-status 8 , 654.Xr zpool-sync 8 , 655.Xr zpool-trim 8 , 656.Xr zpool-upgrade 8 , 657.Xr zpool-wait 8 658