| blob | cd074eaa1d1a89ea744d64ef18f8839558c7443e |
1 .\"
2 .\" CDDL HEADER START
3 .\"
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\"
22 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
23 .\" Copyright (c) 2012, 2017 by Delphix. All rights reserved.
24 .\" Copyright 2017 Nexenta Systems, Inc.
25 .\" Copyright (c) 2017 Datto Inc.
26 .\" Copyright (c) 2017 George Melikov. All Rights Reserved.
27 .\"
28 .Dd December 6, 2017
29 .Dt ZPOOL 1M
30 .Os
31 .Sh NAME
32 .Nm zpool
33 .Nd configure ZFS storage pools
34 .Sh SYNOPSIS
35 .Nm
36 .Fl \?
37 .Nm
38 .Cm add
39 .Op Fl fn
40 .Ar pool vdev Ns ...
41 .Nm
42 .Cm attach
43 .Op Fl f
44 .Ar pool device new_device
45 .Nm
46 .Cm checkpoint
47 .Op Fl d, -discard
48 .Ar pool
49 .Nm
50 .Cm clear
51 .Ar pool
52 .Op Ar device
53 .Nm
54 .Cm create
55 .Op Fl dfn
56 .Op Fl B
57 .Op Fl m Ar mountpoint
58 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
59 .Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ...
60 .Op Fl R Ar root
61 .Ar pool vdev Ns ...
62 .Nm
63 .Cm destroy
64 .Op Fl f
65 .Ar pool
66 .Nm
67 .Cm detach
68 .Ar pool device
69 .Nm
70 .Cm export
71 .Op Fl f
72 .Ar pool Ns ...
73 .Nm
74 .Cm get
75 .Op Fl Hp
76 .Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
77 .Sy all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns ...
78 .Ar pool Ns ...
79 .Nm
80 .Cm history
81 .Op Fl il
82 .Oo Ar pool Oc Ns ...
83 .Nm
84 .Cm import
85 .Op Fl D
86 .Op Fl d Ar dir
87 .Nm
88 .Cm import
89 .Fl a
90 .Op Fl DfmN
91 .Op Fl F Op Fl n
92 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
93 .Op Fl o Ar mntopts
94 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
95 .Op Fl R Ar root
96 .Nm
97 .Cm import
98 .Op Fl Dfm
99 .Op Fl F Op Fl n
100 .Op Fl -rewind-to-checkpoint
101 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
102 .Op Fl o Ar mntopts
103 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
104 .Op Fl R Ar root
105 .Ar pool Ns | Ns Ar id
106 .Op Ar newpool
107 .Nm
108 .Cm iostat
109 .Op Fl v
110 .Op Fl T Sy u Ns | Ns Sy d
111 .Oo Ar pool Oc Ns ...
112 .Op Ar interval Op Ar count
113 .Nm
114 .Cm labelclear
115 .Op Fl f
116 .Ar device
117 .Nm
118 .Cm list
119 .Op Fl Hpv
120 .Op Fl o Ar property Ns Oo , Ns Ar property Oc Ns ...
121 .Op Fl T Sy u Ns | Ns Sy d
122 .Oo Ar pool Oc Ns ...
123 .Op Ar interval Op Ar count
124 .Nm
125 .Cm offline
126 .Op Fl t
127 .Ar pool Ar device Ns ...
128 .Nm
129 .Cm online
130 .Op Fl e
131 .Ar pool Ar device Ns ...
132 .Nm
133 .Cm reguid
134 .Ar pool
135 .Nm
136 .Cm reopen
137 .Ar pool
138 .Nm
139 .Cm remove
140 .Op Fl np
141 .Ar pool Ar device Ns ...
142 .Nm
143 .Cm remove
144 .Fl s
145 .Ar pool
146 .Nm
147 .Cm replace
148 .Op Fl f
149 .Ar pool Ar device Op Ar new_device
150 .Nm
151 .Cm scrub
152 .Op Fl s | Fl p
153 .Ar pool Ns ...
154 .Nm
155 .Cm set
156 .Ar property Ns = Ns Ar value
157 .Ar pool
158 .Nm
159 .Cm split
160 .Op Fl n
161 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
162 .Op Fl R Ar root
163 .Ar pool newpool
164 .Nm
165 .Cm status
166 .Op Fl Dvx
167 .Op Fl T Sy u Ns | Ns Sy d
168 .Oo Ar pool Oc Ns ...
169 .Op Ar interval Op Ar count
170 .Nm
171 .Cm upgrade
172 .Nm
173 .Cm upgrade
174 .Fl v
175 .Nm
176 .Cm upgrade
177 .Op Fl V Ar version
178 .Fl a Ns | Ns Ar pool Ns ...
179 .Sh DESCRIPTION
180 The
181 .Nm
182 command configures ZFS storage pools.
183 A storage pool is a collection of devices that provides physical storage and
184 data replication for ZFS datasets.
185 All datasets within a storage pool share the same space.
186 See
187 .Xr zfs 1M
188 for information on managing datasets.
189 .Ss Virtual Devices (vdevs)
190 A "virtual device" describes a single device or a collection of devices
191 organized according to certain performance and fault characteristics.
192 The following virtual devices are supported:
193 .Bl -tag -width Ds
194 .It Sy disk
195 A block device, typically located under
196 .Pa /dev/dsk .
197 ZFS can use individual slices or partitions, though the recommended mode of
198 operation is to use whole disks.
199 A disk can be specified by a full path, or it can be a shorthand name
200 .Po the relative portion of the path under
201 .Pa /dev/dsk
202 .Pc .
203 A whole disk can be specified by omitting the slice or partition designation.
204 For example,
205 .Pa c0t0d0
206 is equivalent to
207 .Pa /dev/dsk/c0t0d0s2 .
208 When given a whole disk, ZFS automatically labels the disk, if necessary.
209 .It Sy file
210 A regular file.
211 The use of files as a backing store is strongly discouraged.
212 It is designed primarily for experimental purposes, as the fault tolerance of a
213 file is only as good as the file system of which it is a part.
214 A file must be specified by a full path.
215 .It Sy mirror
216 A mirror of two or more devices.
217 Data is replicated in an identical fashion across all components of a mirror.
218 A mirror with N disks of size X can hold X bytes and can withstand (N-1) devices
219 failing before data integrity is compromised.
220 .It Sy raidz , raidz1 , raidz2 , raidz3
221 A variation on RAID-5 that allows for better distribution of parity and
222 eliminates the RAID-5
223 .Qq write hole
224 .Pq in which data and parity become inconsistent after a power loss .
225 Data and parity is striped across all disks within a raidz group.
226 .Pp
227 A raidz group can have single-, double-, or triple-parity, meaning that the
228 raidz group can sustain one, two, or three failures, respectively, without
229 losing any data.
230 The
231 .Sy raidz1
232 vdev type specifies a single-parity raidz group; the
233 .Sy raidz2
234 vdev type specifies a double-parity raidz group; and the
235 .Sy raidz3
236 vdev type specifies a triple-parity raidz group.
237 The
238 .Sy raidz
239 vdev type is an alias for
240 .Sy raidz1 .
241 .Pp
242 A raidz group with N disks of size X with P parity disks can hold approximately
243 (N-P)*X bytes and can withstand P device(s) failing before data integrity is
244 compromised.
245 The minimum number of devices in a raidz group is one more than the number of
246 parity disks.
247 The recommended number is between 3 and 9 to help increase performance.
248 .It Sy spare
249 A special pseudo-vdev which keeps track of available hot spares for a pool.
250 For more information, see the
251 .Sx Hot Spares
252 section.
253 .It Sy log
254 A separate intent log device.
255 If more than one log device is specified, then writes are load-balanced between
256 devices.
257 Log devices can be mirrored.
258 However, raidz vdev types are not supported for the intent log.
259 For more information, see the
260 .Sx Intent Log
261 section.
262 .It Sy cache
263 A device used to cache storage pool data.
264 A cache device cannot be configured as a mirror or raidz group.
265 For more information, see the
266 .Sx Cache Devices
267 section.
268 .El
269 .Pp
270 Virtual devices cannot be nested, so a mirror or raidz virtual device can only
271 contain files or disks.
272 Mirrors of mirrors
273 .Pq or other combinations
274 are not allowed.
275 .Pp
276 A pool can have any number of virtual devices at the top of the configuration
277 .Po known as
278 .Qq root vdevs
279 .Pc .
280 Data is dynamically distributed across all top-level devices to balance data
281 among devices.
282 As new virtual devices are added, ZFS automatically places data on the newly
283 available devices.
284 .Pp
285 Virtual devices are specified one at a time on the command line, separated by
286 whitespace.
287 The keywords
288 .Sy mirror
289 and
290 .Sy raidz
291 are used to distinguish where a group ends and another begins.
292 For example, the following creates two root vdevs, each a mirror of two disks:
293 .Bd -literal
294 # zpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0
295 .Ed
296 .Ss Device Failure and Recovery
297 ZFS supports a rich set of mechanisms for handling device failure and data
298 corruption.
299 All metadata and data is checksummed, and ZFS automatically repairs bad data
300 from a good copy when corruption is detected.
301 .Pp
302 In order to take advantage of these features, a pool must make use of some form
303 of redundancy, using either mirrored or raidz groups.
304 While ZFS supports running in a non-redundant configuration, where each root
305 vdev is simply a disk or file, this is strongly discouraged.
306 A single case of bit corruption can render some or all of your data unavailable.
307 .Pp
308 A pool's health status is described by one of three states: online, degraded,
309 or faulted.
310 An online pool has all devices operating normally.
311 A degraded pool is one in which one or more devices have failed, but the data is
312 still available due to a redundant configuration.
313 A faulted pool has corrupted metadata, or one or more faulted devices, and
314 insufficient replicas to continue functioning.
315 .Pp
316 The health of the top-level vdev, such as mirror or raidz device, is
317 potentially impacted by the state of its associated vdevs, or component
318 devices.
319 A top-level vdev or component device is in one of the following states:
320 .Bl -tag -width "DEGRADED"
321 .It Sy DEGRADED
322 One or more top-level vdevs is in the degraded state because one or more
323 component devices are offline.
324 Sufficient replicas exist to continue functioning.
325 .Pp
326 One or more component devices is in the degraded or faulted state, but
327 sufficient replicas exist to continue functioning.
328 The underlying conditions are as follows:
329 .Bl -bullet
330 .It
331 The number of checksum errors exceeds acceptable levels and the device is
332 degraded as an indication that something may be wrong.
333 ZFS continues to use the device as necessary.
334 .It
335 The number of I/O errors exceeds acceptable levels.
336 The device could not be marked as faulted because there are insufficient
337 replicas to continue functioning.
338 .El
339 .It Sy FAULTED
340 One or more top-level vdevs is in the faulted state because one or more
341 component devices are offline.
342 Insufficient replicas exist to continue functioning.
343 .Pp
344 One or more component devices is in the faulted state, and insufficient
345 replicas exist to continue functioning.
346 The underlying conditions are as follows:
347 .Bl -bullet
348 .It
349 The device could be opened, but the contents did not match expected values.
350 .It
351 The number of I/O errors exceeds acceptable levels and the device is faulted to
352 prevent further use of the device.
353 .El
354 .It Sy OFFLINE
355 The device was explicitly taken offline by the
356 .Nm zpool Cm offline
357 command.
358 .It Sy ONLINE
359 The device is online and functioning.
360 .It Sy REMOVED
361 The device was physically removed while the system was running.
362 Device removal detection is hardware-dependent and may not be supported on all
363 platforms.
364 .It Sy UNAVAIL
365 The device could not be opened.
366 If a pool is imported when a device was unavailable, then the device will be
367 identified by a unique identifier instead of its path since the path was never
368 correct in the first place.
369 .El
370 .Pp
371 If a device is removed and later re-attached to the system, ZFS attempts
372 to put the device online automatically.
373 Device attach detection is hardware-dependent and might not be supported on all
374 platforms.
375 .Ss Hot Spares
376 ZFS allows devices to be associated with pools as
377 .Qq hot spares .
378 These devices are not actively used in the pool, but when an active device
379 fails, it is automatically replaced by a hot spare.
380 To create a pool with hot spares, specify a
381 .Sy spare
382 vdev with any number of devices.
383 For example,
384 .Bd -literal
385 # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0
386 .Ed
387 .Pp
388 Spares can be shared across multiple pools, and can be added with the
389 .Nm zpool Cm add
390 command and removed with the
391 .Nm zpool Cm remove
392 command.
393 Once a spare replacement is initiated, a new
394 .Sy spare
395 vdev is created within the configuration that will remain there until the
396 original device is replaced.
397 At this point, the hot spare becomes available again if another device fails.
398 .Pp
399 If a pool has a shared spare that is currently being used, the pool can not be
400 exported since other pools may use this shared spare, which may lead to
401 potential data corruption.
402 .Pp
403 An in-progress spare replacement can be cancelled by detaching the hot spare.
404 If the original faulted device is detached, then the hot spare assumes its
405 place in the configuration, and is removed from the spare list of all active
406 pools.
407 .Pp
408 Spares cannot replace log devices.
409 .Ss Intent Log
410 The ZFS Intent Log (ZIL) satisfies POSIX requirements for synchronous
411 transactions.
412 For instance, databases often require their transactions to be on stable storage
413 devices when returning from a system call.
414 NFS and other applications can also use
415 .Xr fsync 3C
416 to ensure data stability.
417 By default, the intent log is allocated from blocks within the main pool.
418 However, it might be possible to get better performance using separate intent
419 log devices such as NVRAM or a dedicated disk.
420 For example:
421 .Bd -literal
422 # zpool create pool c0d0 c1d0 log c2d0
423 .Ed
424 .Pp
425 Multiple log devices can also be specified, and they can be mirrored.
426 See the
427 .Sx EXAMPLES
428 section for an example of mirroring multiple log devices.
429 .Pp
430 Log devices can be added, replaced, attached, detached, and imported and
431 exported as part of the larger pool.
432 Mirrored devices can be removed by specifying the top-level mirror vdev.
433 .Ss Cache Devices
434 Devices can be added to a storage pool as
435 .Qq cache devices .
436 These devices provide an additional layer of caching between main memory and
437 disk.
438 For read-heavy workloads, where the working set size is much larger than what
439 can be cached in main memory, using cache devices allow much more of this
440 working set to be served from low latency media.
441 Using cache devices provides the greatest performance improvement for random
442 read-workloads of mostly static content.
443 .Pp
444 To create a pool with cache devices, specify a
445 .Sy cache
446 vdev with any number of devices.
447 For example:
448 .Bd -literal
449 # zpool create pool c0d0 c1d0 cache c2d0 c3d0
450 .Ed
451 .Pp
452 Cache devices cannot be mirrored or part of a raidz configuration.
453 If a read error is encountered on a cache device, that read I/O is reissued to
454 the original storage pool device, which might be part of a mirrored or raidz
455 configuration.
456 .Pp
457 The content of the cache devices is considered volatile, as is the case with
458 other system caches.
459 .Ss Pool checkpoint
460 Before starting critical procedures that include destructive actions (e.g
461 .Nm zfs Cm destroy
462 ), an administrator can checkpoint the pool's state and in the case of a
463 mistake or failure, rewind the entire pool back to the checkpoint.
464 Otherwise, the checkpoint can be discarded when the procedure has completed
465 successfully.
466 .Pp
467 A pool checkpoint can be thought of as a pool-wide snapshot and should be used
468 with care as it contains every part of the pool's state, from properties to vdev
469 configuration.
470 Thus, while a pool has a checkpoint certain operations are not allowed.
471 Specifically, vdev removal/attach/detach, mirror splitting, and
472 changing the pool's guid.
473 Adding a new vdev is supported but in the case of a rewind it will have to be
474 added again.
475 Finally, users of this feature should keep in mind that scrubs in a pool that
476 has a checkpoint do not repair checkpointed data.
477 .Pp
478 To create a checkpoint for a pool:
479 .Bd -literal
480 # zpool checkpoint pool
481 .Ed
482 .Pp
483 To later rewind to its checkpointed state, you need to first export it and
484 then rewind it during import:
485 .Bd -literal
486 # zpool export pool
487 # zpool import --rewind-to-checkpoint pool
488 .Ed
489 .Pp
490 To discard the checkpoint from a pool:
491 .Bd -literal
492 # zpool checkpoint -d pool
493 .Ed
494 .Pp
495 Dataset reservations (controlled by the
496 .Nm reservation
497 or
498 .Nm refreservation
499 zfs properties) may be unenforceable while a checkpoint exists, because the
500 checkpoint is allowed to consume the dataset's reservation.
501 Finally, data that is part of the checkpoint but has been freed in the
502 current state of the pool won't be scanned during a scrub.
503 .Ss Properties
504 Each pool has several properties associated with it.
505 Some properties are read-only statistics while others are configurable and
506 change the behavior of the pool.
507 .Pp
508 The following are read-only properties:
509 .Bl -tag -width Ds
510 .It Cm allocated
511 Amount of storage space used within the pool.
512 .It Sy bootsize
513 The size of the system boot partition.
514 This property can only be set at pool creation time and is read-only once pool
515 is created.
516 Setting this property implies using the
517 .Fl B
518 option.
519 .It Sy capacity
520 Percentage of pool space used.
521 This property can also be referred to by its shortened column name,
522 .Sy cap .
523 .It Sy expandsize
524 Amount of uninitialized space within the pool or device that can be used to
525 increase the total capacity of the pool.
526 Uninitialized space consists of any space on an EFI labeled vdev which has not
527 been brought online
528 .Po e.g, using
529 .Nm zpool Cm online Fl e
530 .Pc .
531 This space occurs when a LUN is dynamically expanded.
532 .It Sy fragmentation
533 The amount of fragmentation in the pool.
534 .It Sy free
535 The amount of free space available in the pool.
536 .It Sy freeing
537 After a file system or snapshot is destroyed, the space it was using is
538 returned to the pool asynchronously.
539 .Sy freeing
540 is the amount of space remaining to be reclaimed.
541 Over time
542 .Sy freeing
543 will decrease while
544 .Sy free
545 increases.
546 .It Sy health
547 The current health of the pool.
548 Health can be one of
549 .Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL .
550 .It Sy guid
551 A unique identifier for the pool.
552 .It Sy size
553 Total size of the storage pool.
554 .It Sy unsupported@ Ns Em feature_guid
555 Information about unsupported features that are enabled on the pool.
556 See
557 .Xr zpool-features 5
558 for details.
559 .El
560 .Pp
561 The space usage properties report actual physical space available to the
562 storage pool.
563 The physical space can be different from the total amount of space that any
564 contained datasets can actually use.
565 The amount of space used in a raidz configuration depends on the characteristics
566 of the data being written.
567 In addition, ZFS reserves some space for internal accounting that the
568 .Xr zfs 1M
569 command takes into account, but the
570 .Nm
571 command does not.
572 For non-full pools of a reasonable size, these effects should be invisible.
573 For small pools, or pools that are close to being completely full, these
574 discrepancies may become more noticeable.
575 .Pp
576 The following property can be set at creation time and import time:
577 .Bl -tag -width Ds
578 .It Sy altroot
579 Alternate root directory.
580 If set, this directory is prepended to any mount points within the pool.
581 This can be used when examining an unknown pool where the mount points cannot be
582 trusted, or in an alternate boot environment, where the typical paths are not
583 valid.
584 .Sy altroot
585 is not a persistent property.
586 It is valid only while the system is up.
587 Setting
588 .Sy altroot
589 defaults to using
590 .Sy cachefile Ns = Ns Sy none ,
591 though this may be overridden using an explicit setting.
592 .El
593 .Pp
594 The following property can be set only at import time:
595 .Bl -tag -width Ds
596 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
597 If set to
598 .Sy on ,
599 the pool will be imported in read-only mode.
600 This property can also be referred to by its shortened column name,
601 .Sy rdonly .
602 .El
603 .Pp
604 The following properties can be set at creation time and import time, and later
605 changed with the
606 .Nm zpool Cm set
607 command:
608 .Bl -tag -width Ds
609 .It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off
610 Controls automatic pool expansion when the underlying LUN is grown.
611 If set to
612 .Sy on ,
613 the pool will be resized according to the size of the expanded device.
614 If the device is part of a mirror or raidz then all devices within that
615 mirror/raidz group must be expanded before the new space is made available to
616 the pool.
617 The default behavior is
618 .Sy off .
619 This property can also be referred to by its shortened column name,
620 .Sy expand .
621 .It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off
622 Controls automatic device replacement.
623 If set to
624 .Sy off ,
625 device replacement must be initiated by the administrator by using the
626 .Nm zpool Cm replace
627 command.
628 If set to
629 .Sy on ,
630 any new device, found in the same physical location as a device that previously
631 belonged to the pool, is automatically formatted and replaced.
632 The default behavior is
633 .Sy off .
634 This property can also be referred to by its shortened column name,
635 .Sy replace .
636 .It Sy bootfs Ns = Ns Ar pool Ns / Ns Ar dataset
637 Identifies the default bootable dataset for the root pool.
638 This property is expected to be set mainly by the installation and upgrade
639 programs.
640 .It Sy cachefile Ns = Ns Ar path Ns | Ns Sy none
641 Controls the location of where the pool configuration is cached.
642 Discovering all pools on system startup requires a cached copy of the
643 configuration data that is stored on the root file system.
644 All pools in this cache are automatically imported when the system boots.
645 Some environments, such as install and clustering, need to cache this
646 information in a different location so that pools are not automatically
647 imported.
648 Setting this property caches the pool configuration in a different location that
649 can later be imported with
650 .Nm zpool Cm import Fl c .
651 Setting it to the special value
652 .Sy none
653 creates a temporary pool that is never cached, and the special value
654 .Qq
655 .Pq empty string
656 uses the default location.
657 .Pp
658 Multiple pools can share the same cache file.
659 Because the kernel destroys and recreates this file when pools are added and
660 removed, care should be taken when attempting to access this file.
661 When the last pool using a
662 .Sy cachefile
663 is exported or destroyed, the file is removed.
664 .It Sy comment Ns = Ns Ar text
665 A text string consisting of printable ASCII characters that will be stored
666 such that it is available even if the pool becomes faulted.
667 An administrator can provide additional information about a pool using this
668 property.
669 .It Sy dedupditto Ns = Ns Ar number
670 Threshold for the number of block ditto copies.
671 If the reference count for a deduplicated block increases above this number, a
672 new ditto copy of this block is automatically stored.
673 The default setting is
674 .Sy 0
675 which causes no ditto copies to be created for deduplicated blocks.
676 The minimum legal nonzero setting is
677 .Sy 100 .
678 .It Sy delegation Ns = Ns Sy on Ns | Ns Sy off
679 Controls whether a non-privileged user is granted access based on the dataset
680 permissions defined on the dataset.
681 See
682 .Xr zfs 1M
683 for more information on ZFS delegated administration.
684 .It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy panic
685 Controls the system behavior in the event of catastrophic pool failure.
686 This condition is typically a result of a loss of connectivity to the underlying
687 storage device(s) or a failure of all devices within the pool.
688 The behavior of such an event is determined as follows:
689 .Bl -tag -width "continue"
690 .It Sy wait
691 Blocks all I/O access until the device connectivity is recovered and the errors
692 are cleared.
693 This is the default behavior.
694 .It Sy continue
695 Returns
696 .Er EIO
697 to any new write I/O requests but allows reads to any of the remaining healthy
698 devices.
699 Any write requests that have yet to be committed to disk would be blocked.
700 .It Sy panic
701 Prints out a message to the console and generates a system crash dump.
702 .El
703 .It Sy feature@ Ns Ar feature_name Ns = Ns Sy enabled
704 The value of this property is the current state of
705 .Ar feature_name .
706 The only valid value when setting this property is
707 .Sy enabled
708 which moves
709 .Ar feature_name
710 to the enabled state.
711 See
712 .Xr zpool-features 5
713 for details on feature states.
714 .It Sy listsnapshots Ns = Ns Sy on Ns | Ns Sy off
715 Controls whether information about snapshots associated with this pool is
716 output when
717 .Nm zfs Cm list
718 is run without the
719 .Fl t
720 option.
721 The default value is
722 .Sy off .
723 This property can also be referred to by its shortened name,
724 .Sy listsnaps .
725 .It Sy version Ns = Ns Ar version
726 The current on-disk version of the pool.
727 This can be increased, but never decreased.
728 The preferred method of updating pools is with the
729 .Nm zpool Cm upgrade
730 command, though this property can be used when a specific version is needed for
731 backwards compatibility.
732 Once feature flags are enabled on a pool this property will no longer have a
733 value.
734 .El
735 .Ss Subcommands
736 All subcommands that modify state are logged persistently to the pool in their
737 original form.
738 .Pp
739 The
740 .Nm
741 command provides subcommands to create and destroy storage pools, add capacity
742 to storage pools, and provide information about the storage pools.
743 The following subcommands are supported:
744 .Bl -tag -width Ds
745 .It Xo
746 .Nm
747 .Fl \?
748 .Xc
749 Displays a help message.
750 .It Xo
751 .Nm
752 .Cm add
753 .Op Fl fn
754 .Ar pool vdev Ns ...
755 .Xc
756 Adds the specified virtual devices to the given pool.
757 The
758 .Ar vdev
759 specification is described in the
760 .Sx Virtual Devices
761 section.
762 The behavior of the
763 .Fl f
764 option, and the device checks performed are described in the
765 .Nm zpool Cm create
766 subcommand.
767 .Bl -tag -width Ds
768 .It Fl f
769 Forces use of
770 .Ar vdev Ns s ,
771 even if they appear in use or specify a conflicting replication level.
772 Not all devices can be overridden in this manner.
773 .It Fl n
774 Displays the configuration that would be used without actually adding the
775 .Ar vdev Ns s .
776 The actual pool creation can still fail due to insufficient privileges or
777 device sharing.
778 .El
779 .It Xo
780 .Nm
781 .Cm attach
782 .Op Fl f
783 .Ar pool device new_device
784 .Xc
785 Attaches
786 .Ar new_device
787 to the existing
788 .Ar device .
789 The existing device cannot be part of a raidz configuration.
790 If
791 .Ar device
792 is not currently part of a mirrored configuration,
793 .Ar device
794 automatically transforms into a two-way mirror of
795 .Ar device
796 and
797 .Ar new_device .
798 If
799 .Ar device
800 is part of a two-way mirror, attaching
801 .Ar new_device
802 creates a three-way mirror, and so on.
803 In either case,
804 .Ar new_device
805 begins to resilver immediately.
806 .Bl -tag -width Ds
807 .It Fl f
808 Forces use of
809 .Ar new_device ,
810 even if its appears to be in use.
811 Not all devices can be overridden in this manner.
812 .El
813 .It Xo
814 .Nm
815 .Cm checkpoint
816 .Op Fl d, -discard
817 .Ar pool
818 .Xc
819 Checkpoints the current state of
820 .Ar pool
821 , which can be later restored by
822 .Nm zpool Cm import --rewind-to-checkpoint .
823 The existence of a checkpoint in a pool prohibits the following
824 .Nm zpool
825 commands:
826 .Cm remove ,
827 .Cm attach ,
828 .Cm detach ,
829 .Cm split ,
830 and
831 .Cm reguid .
832 In addition, it may break reservation boundaries if the pool lacks free
833 space.
834 The
835 .Nm zpool Cm status
836 command indicates the existence of a checkpoint or the progress of discarding a
837 checkpoint from a pool.
838 The
839 .Nm zpool Cm list
840 command reports how much space the checkpoint takes from the pool.
841 .Bl -tag -width Ds
842 .It Fl d, -discard
843 Discards an existing checkpoint from
844 .Ar pool .
845 .El
846 .It Xo
847 .Nm
848 .Cm clear
849 .Ar pool
850 .Op Ar device
851 .Xc
852 Clears device errors in a pool.
853 If no arguments are specified, all device errors within the pool are cleared.
854 If one or more devices is specified, only those errors associated with the
855 specified device or devices are cleared.
856 .It Xo
857 .Nm
858 .Cm create
859 .Op Fl dfn
860 .Op Fl B
861 .Op Fl m Ar mountpoint
862 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
863 .Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ...
864 .Op Fl R Ar root
865 .Ar pool vdev Ns ...
866 .Xc
867 Creates a new storage pool containing the virtual devices specified on the
868 command line.
869 The pool name must begin with a letter, and can only contain
870 alphanumeric characters as well as underscore
871 .Pq Qq Sy _ ,
872 dash
873 .Pq Qq Sy - ,
874 and period
875 .Pq Qq Sy \&. .
876 The pool names
877 .Sy mirror ,
878 .Sy raidz ,
879 .Sy spare
880 and
881 .Sy log
882 are reserved, as are names beginning with the pattern
883 .Sy c[0-9] .
884 The
885 .Ar vdev
886 specification is described in the
887 .Sx Virtual Devices
888 section.
889 .Pp
890 The command verifies that each device specified is accessible and not currently
891 in use by another subsystem.
892 There are some uses, such as being currently mounted, or specified as the
893 dedicated dump device, that prevents a device from ever being used by ZFS.
894 Other uses, such as having a preexisting UFS file system, can be overridden with
895 the
896 .Fl f
897 option.
898 .Pp
899 The command also checks that the replication strategy for the pool is
900 consistent.
901 An attempt to combine redundant and non-redundant storage in a single pool, or
902 to mix disks and files, results in an error unless
903 .Fl f
904 is specified.
905 The use of differently sized devices within a single raidz or mirror group is
906 also flagged as an error unless
907 .Fl f
908 is specified.
909 .Pp
910 Unless the
911 .Fl R
912 option is specified, the default mount point is
913 .Pa / Ns Ar pool .
914 The mount point must not exist or must be empty, or else the root dataset
915 cannot be mounted.
916 This can be overridden with the
917 .Fl m
918 option.
919 .Pp
920 By default all supported features are enabled on the new pool unless the
921 .Fl d
922 option is specified.
923 .Bl -tag -width Ds
924 .It Fl B
925 Create whole disk pool with EFI System partition to support booting system
926 with UEFI firmware.
927 Default size is 256MB.
928 To create boot partition with custom size, set the
929 .Sy bootsize
930 property with the
931 .Fl o
932 option.
933 See the
934 .Sx Properties
935 section for details.
936 .It Fl d
937 Do not enable any features on the new pool.
938 Individual features can be enabled by setting their corresponding properties to
939 .Sy enabled
940 with the
941 .Fl o
942 option.
943 See
944 .Xr zpool-features 5
945 for details about feature properties.
946 .It Fl f
947 Forces use of
948 .Ar vdev Ns s ,
949 even if they appear in use or specify a conflicting replication level.
950 Not all devices can be overridden in this manner.
951 .It Fl m Ar mountpoint
952 Sets the mount point for the root dataset.
953 The default mount point is
954 .Pa /pool
955 or
956 .Pa altroot/pool
957 if
958 .Ar altroot
959 is specified.
960 The mount point must be an absolute path,
961 .Sy legacy ,
962 or
963 .Sy none .
964 For more information on dataset mount points, see
965 .Xr zfs 1M .
966 .It Fl n
967 Displays the configuration that would be used without actually creating the
968 pool.
969 The actual pool creation can still fail due to insufficient privileges or
970 device sharing.
971 .It Fl o Ar property Ns = Ns Ar value
972 Sets the given pool properties.
973 See the
974 .Sx Properties
975 section for a list of valid properties that can be set.
976 .It Fl O Ar file-system-property Ns = Ns Ar value
977 Sets the given file system properties in the root file system of the pool.
978 See the
979 .Sx Properties
980 section of
981 .Xr zfs 1M
982 for a list of valid properties that can be set.
983 .It Fl R Ar root
984 Equivalent to
985 .Fl o Sy cachefile Ns = Ns Sy none Fl o Sy altroot Ns = Ns Ar root
986 .El
987 .It Xo
988 .Nm
989 .Cm destroy
990 .Op Fl f
991 .Ar pool
992 .Xc
993 Destroys the given pool, freeing up any devices for other use.
994 This command tries to unmount any active datasets before destroying the pool.
995 .Bl -tag -width Ds
996 .It Fl f
997 Forces any active datasets contained within the pool to be unmounted.
998 .El
999 .It Xo
1000 .Nm
1001 .Cm detach
1002 .Ar pool device
1003 .Xc
1004 Detaches
1005 .Ar device
1006 from a mirror.
1007 The operation is refused if there are no other valid replicas of the data.
1008 .It Xo
1009 .Nm
1010 .Cm export
1011 .Op Fl f
1012 .Ar pool Ns ...
1013 .Xc
1014 Exports the given pools from the system.
1015 All devices are marked as exported, but are still considered in use by other
1016 subsystems.
1017 The devices can be moved between systems
1018 .Pq even those of different endianness
1019 and imported as long as a sufficient number of devices are present.
1020 .Pp
1021 Before exporting the pool, all datasets within the pool are unmounted.
1022 A pool can not be exported if it has a shared spare that is currently being
1023 used.
1024 .Pp
1025 For pools to be portable, you must give the
1026 .Nm
1027 command whole disks, not just slices, so that ZFS can label the disks with
1028 portable EFI labels.
1029 Otherwise, disk drivers on platforms of different endianness will not recognize
1030 the disks.
1031 .Bl -tag -width Ds
1032 .It Fl f
1033 Forcefully unmount all datasets, using the
1034 .Nm unmount Fl f
1035 command.
1036 .Pp
1037 This command will forcefully export the pool even if it has a shared spare that
1038 is currently being used.
1039 This may lead to potential data corruption.
1040 .El
1041 .It Xo
1042 .Nm
1043 .Cm get
1044 .Op Fl Hp
1045 .Op Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
1046 .Sy all Ns | Ns Ar property Ns Oo , Ns Ar property Oc Ns ...
1047 .Ar pool Ns ...
1048 .Xc
1049 Retrieves the given list of properties
1050 .Po
1051 or all properties if
1052 .Sy all
1053 is used
1054 .Pc
1055 for the specified storage pool(s).
1056 These properties are displayed with the following fields:
1057 .Bd -literal
1058 name Name of storage pool
1059 property Property name
1060 value Property value
1061 source Property source, either 'default' or 'local'.
1062 .Ed
1063 .Pp
1064 See the
1065 .Sx Properties
1066 section for more information on the available pool properties.
1067 .Bl -tag -width Ds
1068 .It Fl H
1069 Scripted mode.
1070 Do not display headers, and separate fields by a single tab instead of arbitrary
1071 space.
1072 .It Fl o Ar field
1073 A comma-separated list of columns to display.
1074 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
1075 is the default value.
1076 .It Fl p
1077 Display numbers in parsable (exact) values.
1078 .El
1079 .It Xo
1080 .Nm
1081 .Cm history
1082 .Op Fl il
1083 .Oo Ar pool Oc Ns ...
1084 .Xc
1085 Displays the command history of the specified pool(s) or all pools if no pool is
1086 specified.
1087 .Bl -tag -width Ds
1088 .It Fl i
1089 Displays internally logged ZFS events in addition to user initiated events.
1090 .It Fl l
1091 Displays log records in long format, which in addition to standard format
1092 includes, the user name, the hostname, and the zone in which the operation was
1093 performed.
1094 .El
1095 .It Xo
1096 .Nm
1097 .Cm import
1098 .Op Fl D
1099 .Op Fl d Ar dir
1100 .Xc
1101 Lists pools available to import.
1102 If the
1103 .Fl d
1104 option is not specified, this command searches for devices in
1105 .Pa /dev/dsk .
1106 The
1107 .Fl d
1108 option can be specified multiple times, and all directories are searched.
1109 If the device appears to be part of an exported pool, this command displays a
1110 summary of the pool with the name of the pool, a numeric identifier, as well as
1111 the vdev layout and current health of the device for each device or file.
1112 Destroyed pools, pools that were previously destroyed with the
1113 .Nm zpool Cm destroy
1114 command, are not listed unless the
1115 .Fl D
1116 option is specified.
1117 .Pp
1118 The numeric identifier is unique, and can be used instead of the pool name when
1119 multiple exported pools of the same name are available.
1120 .Bl -tag -width Ds
1121 .It Fl c Ar cachefile
1122 Reads configuration from the given
1123 .Ar cachefile
1124 that was created with the
1125 .Sy cachefile
1126 pool property.
1127 This
1128 .Ar cachefile
1129 is used instead of searching for devices.
1130 .It Fl d Ar dir
1131 Searches for devices or files in
1132 .Ar dir .
1133 The
1134 .Fl d
1135 option can be specified multiple times.
1136 .It Fl D
1137 Lists destroyed pools only.
1138 .El
1139 .It Xo
1140 .Nm
1141 .Cm import
1142 .Fl a
1143 .Op Fl DfmN
1144 .Op Fl F Op Fl n
1145 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
1146 .Op Fl o Ar mntopts
1147 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1148 .Op Fl R Ar root
1149 .Xc
1150 Imports all pools found in the search directories.
1151 Identical to the previous command, except that all pools with a sufficient
1152 number of devices available are imported.
1153 Destroyed pools, pools that were previously destroyed with the
1154 .Nm zpool Cm destroy
1155 command, will not be imported unless the
1156 .Fl D
1157 option is specified.
1158 .Bl -tag -width Ds
1159 .It Fl a
1160 Searches for and imports all pools found.
1161 .It Fl c Ar cachefile
1162 Reads configuration from the given
1163 .Ar cachefile
1164 that was created with the
1165 .Sy cachefile
1166 pool property.
1167 This
1168 .Ar cachefile
1169 is used instead of searching for devices.
1170 .It Fl d Ar dir
1171 Searches for devices or files in
1172 .Ar dir .
1173 The
1174 .Fl d
1175 option can be specified multiple times.
1176 This option is incompatible with the
1177 .Fl c
1178 option.
1179 .It Fl D
1180 Imports destroyed pools only.
1181 The
1182 .Fl f
1183 option is also required.
1184 .It Fl f
1185 Forces import, even if the pool appears to be potentially active.
1186 .It Fl F
1187 Recovery mode for a non-importable pool.
1188 Attempt to return the pool to an importable state by discarding the last few
1189 transactions.
1190 Not all damaged pools can be recovered by using this option.
1191 If successful, the data from the discarded transactions is irretrievably lost.
1192 This option is ignored if the pool is importable or already imported.
1193 .It Fl m
1194 Allows a pool to import when there is a missing log device.
1195 Recent transactions can be lost because the log device will be discarded.
1196 .It Fl n
1197 Used with the
1198 .Fl F
1199 recovery option.
1200 Determines whether a non-importable pool can be made importable again, but does
1201 not actually perform the pool recovery.
1202 For more details about pool recovery mode, see the
1203 .Fl F
1204 option, above.
1205 .It Fl N
1206 Import the pool without mounting any file systems.
1207 .It Fl o Ar mntopts
1208 Comma-separated list of mount options to use when mounting datasets within the
1209 pool.
1210 See
1211 .Xr zfs 1M
1212 for a description of dataset properties and mount options.
1213 .It Fl o Ar property Ns = Ns Ar value
1214 Sets the specified property on the imported pool.
1215 See the
1216 .Sx Properties
1217 section for more information on the available pool properties.
1218 .It Fl R Ar root
1219 Sets the
1220 .Sy cachefile
1221 property to
1222 .Sy none
1223 and the
1224 .Sy altroot
1225 property to
1226 .Ar root .
1227 .El
1228 .It Xo
1229 .Nm
1230 .Cm import
1231 .Op Fl Dfm
1232 .Op Fl F Op Fl n
1233 .Op Fl -rewind-to-checkpoint
1234 .Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
1235 .Op Fl o Ar mntopts
1236 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1237 .Op Fl R Ar root
1238 .Ar pool Ns | Ns Ar id
1239 .Op Ar newpool
1240 .Xc
1241 Imports a specific pool.
1242 A pool can be identified by its name or the numeric identifier.
1243 If
1244 .Ar newpool
1245 is specified, the pool is imported using the name
1246 .Ar newpool .
1247 Otherwise, it is imported with the same name as its exported name.
1248 .Pp
1249 If a device is removed from a system without running
1250 .Nm zpool Cm export
1251 first, the device appears as potentially active.
1252 It cannot be determined if this was a failed export, or whether the device is
1253 really in use from another host.
1254 To import a pool in this state, the
1255 .Fl f
1256 option is required.
1257 .Bl -tag -width Ds
1258 .It Fl c Ar cachefile
1259 Reads configuration from the given
1260 .Ar cachefile
1261 that was created with the
1262 .Sy cachefile
1263 pool property.
1264 This
1265 .Ar cachefile
1266 is used instead of searching for devices.
1267 .It Fl d Ar dir
1268 Searches for devices or files in
1269 .Ar dir .
1270 The
1271 .Fl d
1272 option can be specified multiple times.
1273 This option is incompatible with the
1274 .Fl c
1275 option.
1276 .It Fl D
1277 Imports destroyed pool.
1278 The
1279 .Fl f
1280 option is also required.
1281 .It Fl f
1282 Forces import, even if the pool appears to be potentially active.
1283 .It Fl F
1284 Recovery mode for a non-importable pool.
1285 Attempt to return the pool to an importable state by discarding the last few
1286 transactions.
1287 Not all damaged pools can be recovered by using this option.
1288 If successful, the data from the discarded transactions is irretrievably lost.
1289 This option is ignored if the pool is importable or already imported.
1290 .It Fl m
1291 Allows a pool to import when there is a missing log device.
1292 Recent transactions can be lost because the log device will be discarded.
1293 .It Fl n
1294 Used with the
1295 .Fl F
1296 recovery option.
1297 Determines whether a non-importable pool can be made importable again, but does
1298 not actually perform the pool recovery.
1299 For more details about pool recovery mode, see the
1300 .Fl F
1301 option, above.
1302 .It Fl o Ar mntopts
1303 Comma-separated list of mount options to use when mounting datasets within the
1304 pool.
1305 See
1306 .Xr zfs 1M
1307 for a description of dataset properties and mount options.
1308 .It Fl o Ar property Ns = Ns Ar value
1309 Sets the specified property on the imported pool.
1310 See the
1311 .Sx Properties
1312 section for more information on the available pool properties.
1313 .It Fl R Ar root
1314 Sets the
1315 .Sy cachefile
1316 property to
1317 .Sy none
1318 and the
1319 .Sy altroot
1320 property to
1321 .Ar root .
1322 .It Fl -rewind-to-checkpoint
1323 Rewinds pool to the checkpointed state.
1324 Once the pool is imported with this flag there is no way to undo the rewind.
1325 All changes and data that were written after the checkpoint are lost!
1326 The only exception is when the
1327 .Sy readonly
1328 mounting option is enabled.
1329 In this case, the checkpointed state of the pool is opened and an
1330 administrator can see how the pool would look like if they were
1331 to fully rewind.
1332 .El
1333 .It Xo
1334 .Nm
1335 .Cm iostat
1336 .Op Fl v
1337 .Op Fl T Sy u Ns | Ns Sy d
1338 .Oo Ar pool Oc Ns ...
1339 .Op Ar interval Op Ar count
1340 .Xc
1341 Displays I/O statistics for the given pools.
1342 When given an
1343 .Ar interval ,
1344 the statistics are printed every
1345 .Ar interval
1346 seconds until ^C is pressed.
1347 If no
1348 .Ar pool Ns s
1349 are specified, statistics for every pool in the system is shown.
1350 If
1351 .Ar count
1352 is specified, the command exits after
1353 .Ar count
1354 reports are printed.
1355 .Bl -tag -width Ds
1356 .It Fl T Sy u Ns | Ns Sy d
1357 Display a time stamp.
1358 Specify
1359 .Sy u
1360 for a printed representation of the internal representation of time.
1361 See
1362 .Xr time 2 .
1363 Specify
1364 .Sy d
1365 for standard date format.
1366 See
1367 .Xr date 1 .
1368 .It Fl v
1369 Verbose statistics Reports usage statistics for individual vdevs within the
1370 pool, in addition to the pool-wide statistics.
1371 .El
1372 .It Xo
1373 .Nm
1374 .Cm labelclear
1375 .Op Fl f
1376 .Ar device
1377 .Xc
1378 Removes ZFS label information from the specified
1379 .Ar device .
1380 The
1381 .Ar device
1382 must not be part of an active pool configuration.
1383 .Bl -tag -width Ds
1384 .It Fl f
1385 Treat exported or foreign devices as inactive.
1386 .El
1387 .It Xo
1388 .Nm
1389 .Cm list
1390 .Op Fl Hpv
1391 .Op Fl o Ar property Ns Oo , Ns Ar property Oc Ns ...
1392 .Op Fl T Sy u Ns | Ns Sy d
1393 .Oo Ar pool Oc Ns ...
1394 .Op Ar interval Op Ar count
1395 .Xc
1396 Lists the given pools along with a health status and space usage.
1397 If no
1398 .Ar pool Ns s
1399 are specified, all pools in the system are listed.
1400 When given an
1401 .Ar interval ,
1402 the information is printed every
1403 .Ar interval
1404 seconds until ^C is pressed.
1405 If
1406 .Ar count
1407 is specified, the command exits after
1408 .Ar count
1409 reports are printed.
1410 .Bl -tag -width Ds
1411 .It Fl H
1412 Scripted mode.
1413 Do not display headers, and separate fields by a single tab instead of arbitrary
1414 space.
1415 .It Fl o Ar property
1416 Comma-separated list of properties to display.
1417 See the
1418 .Sx Properties
1419 section for a list of valid properties.
1420 The default list is
1421 .Cm name , size , allocated , free , expandsize , fragmentation , capacity ,
1422 .Cm dedupratio , health , altroot .
1423 .It Fl p
1424 Display numbers in parsable
1425 .Pq exact
1426 values.
1427 .It Fl T Sy u Ns | Ns Sy d
1428 Display a time stamp.
1429 Specify
1430 .Fl u
1431 for a printed representation of the internal representation of time.
1432 See
1433 .Xr time 2 .
1434 Specify
1435 .Fl d
1436 for standard date format.
1437 See
1438 .Xr date 1 .
1439 .It Fl v
1440 Verbose statistics.
1441 Reports usage statistics for individual vdevs within the pool, in addition to
1442 the pool-wise statistics.
1443 .El
1444 .It Xo
1445 .Nm
1446 .Cm offline
1447 .Op Fl t
1448 .Ar pool Ar device Ns ...
1449 .Xc
1450 Takes the specified physical device offline.
1451 While the
1452 .Ar device
1453 is offline, no attempt is made to read or write to the device.
1454 This command is not applicable to spares.
1455 .Bl -tag -width Ds
1456 .It Fl t
1457 Temporary.
1458 Upon reboot, the specified physical device reverts to its previous state.
1459 .El
1460 .It Xo
1461 .Nm
1462 .Cm online
1463 .Op Fl e
1464 .Ar pool Ar device Ns ...
1465 .Xc
1466 Brings the specified physical device online.
1467 This command is not applicable to spares.
1468 .Bl -tag -width Ds
1469 .It Fl e
1470 Expand the device to use all available space.
1471 If the device is part of a mirror or raidz then all devices must be expanded
1472 before the new space will become available to the pool.
1473 .El
1474 .It Xo
1475 .Nm
1476 .Cm reguid
1477 .Ar pool
1478 .Xc
1479 Generates a new unique identifier for the pool.
1480 You must ensure that all devices in this pool are online and healthy before
1481 performing this action.
1482 .It Xo
1483 .Nm
1484 .Cm reopen
1485 .Ar pool
1486 .Xc
1487 Reopen all the vdevs associated with the pool.
1488 .It Xo
1489 .Nm
1490 .Cm remove
1491 .Op Fl np
1492 .Ar pool Ar device Ns ...
1493 .Xc
1494 Removes the specified device from the pool.
1495 This command currently only supports removing hot spares, cache, log
1496 devices and mirrored top-level vdevs (mirror of leaf devices); but not raidz.
1497 .sp
1498 Removing a top-level vdev reduces the total amount of space in the storage pool.
1499 The specified device will be evacuated by copying all allocated space from it to
1500 the other devices in the pool.
1501 In this case, the
1502 .Nm zpool Cm remove
1503 command initiates the removal and returns, while the evacuation continues in
1504 the background.
1505 The removal progress can be monitored with
1506 .Nm zpool Cm status.
1507 This feature must be enabled to be used, see
1508 .Xr zpool-features 5
1509 .Pp
1510 A mirrored top-level device (log or data) can be removed by specifying the top-level mirror for the
1511 same.
1512 Non-log devices or data devices that are part of a mirrored configuration can be removed using
1513 the
1514 .Nm zpool Cm detach
1515 command.
1516 .Bl -tag -width Ds
1517 .It Fl n
1518 Do not actually perform the removal ("no-op").
1519 Instead, print the estimated amount of memory that will be used by the
1520 mapping table after the removal completes.
1521 This is nonzero only for top-level vdevs.
1522 .El
1523 .Bl -tag -width Ds
1524 .It Fl p
1525 Used in conjunction with the
1526 .Fl n
1527 flag, displays numbers as parsable (exact) values.
1528 .El
1529 .It Xo
1530 .Nm
1531 .Cm remove
1532 .Fl s
1533 .Ar pool
1534 .Xc
1535 Stops and cancels an in-progress removal of a top-level vdev.
1536 .It Xo
1537 .Nm
1538 .Cm replace
1539 .Op Fl f
1540 .Ar pool Ar device Op Ar new_device
1541 .Xc
1542 Replaces
1543 .Ar old_device
1544 with
1545 .Ar new_device .
1546 This is equivalent to attaching
1547 .Ar new_device ,
1548 waiting for it to resilver, and then detaching
1549 .Ar old_device .
1550 .Pp
1551 The size of
1552 .Ar new_device
1553 must be greater than or equal to the minimum size of all the devices in a mirror
1554 or raidz configuration.
1555 .Pp
1556 .Ar new_device
1557 is required if the pool is not redundant.
1558 If
1559 .Ar new_device
1560 is not specified, it defaults to
1561 .Ar old_device .
1562 This form of replacement is useful after an existing disk has failed and has
1563 been physically replaced.
1564 In this case, the new disk may have the same
1565 .Pa /dev/dsk
1566 path as the old device, even though it is actually a different disk.
1567 ZFS recognizes this.
1568 .Bl -tag -width Ds
1569 .It Fl f
1570 Forces use of
1571 .Ar new_device ,
1572 even if its appears to be in use.
1573 Not all devices can be overridden in this manner.
1574 .El
1575 .It Xo
1576 .Nm
1577 .Cm scrub
1578 .Op Fl s | Fl p
1579 .Ar pool Ns ...
1580 .Xc
1581 Begins a scrub or resumes a paused scrub.
1582 The scrub examines all data in the specified pools to verify that it checksums
1583 correctly.
1584 For replicated
1585 .Pq mirror or raidz
1586 devices, ZFS automatically repairs any damage discovered during the scrub.
1587 The
1588 .Nm zpool Cm status
1589 command reports the progress of the scrub and summarizes the results of the
1590 scrub upon completion.
1591 .Pp
1592 Scrubbing and resilvering are very similar operations.
1593 The difference is that resilvering only examines data that ZFS knows to be out
1594 of date
1595 .Po
1596 for example, when attaching a new device to a mirror or replacing an existing
1597 device
1598 .Pc ,
1599 whereas scrubbing examines all data to discover silent errors due to hardware
1600 faults or disk failure.
1601 .Pp
1602 Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows
1603 one at a time.
1604 If a scrub is paused, the
1605 .Nm zpool Cm scrub
1606 resumes it.
1607 If a resilver is in progress, ZFS does not allow a scrub to be started until the
1608 resilver completes.
1609 .Bl -tag -width Ds
1610 .It Fl s
1611 Stop scrubbing.
1612 .El
1613 .Bl -tag -width Ds
1614 .It Fl p
1615 Pause scrubbing.
1616 Scrub pause state and progress are periodically synced to disk.
1617 If the system is restarted or pool is exported during a paused scrub,
1618 even after import, scrub will remain paused until it is resumed.
1619 Once resumed the scrub will pick up from the place where it was last
1620 checkpointed to disk.
1621 To resume a paused scrub issue
1622 .Nm zpool Cm scrub
1623 again.
1624 .El
1625 .It Xo
1626 .Nm
1627 .Cm set
1628 .Ar property Ns = Ns Ar value
1629 .Ar pool
1630 .Xc
1631 Sets the given property on the specified pool.
1632 See the
1633 .Sx Properties
1634 section for more information on what properties can be set and acceptable
1635 values.
1636 .It Xo
1637 .Nm
1638 .Cm split
1639 .Op Fl n
1640 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1641 .Op Fl R Ar root
1642 .Ar pool newpool
1643 .Xc
1644 Splits devices off
1645 .Ar pool
1646 creating
1647 .Ar newpool .
1648 All vdevs in
1649 .Ar pool
1650 must be mirrors.
1651 At the time of the split,
1652 .Ar newpool
1653 will be a replica of
1654 .Ar pool .
1655 .Bl -tag -width Ds
1656 .It Fl n
1657 Do dry run, do not actually perform the split.
1658 Print out the expected configuration of
1659 .Ar newpool .
1660 .It Fl o Ar property Ns = Ns Ar value
1661 Sets the specified property for
1662 .Ar newpool .
1663 See the
1664 .Sx Properties
1665 section for more information on the available pool properties.
1666 .It Fl R Ar root
1667 Set
1668 .Sy altroot
1669 for
1670 .Ar newpool
1671 to
1672 .Ar root
1673 and automatically import it.
1674 .El
1675 .It Xo
1676 .Nm
1677 .Cm status
1678 .Op Fl Dvx
1679 .Op Fl T Sy u Ns | Ns Sy d
1680 .Oo Ar pool Oc Ns ...
1681 .Op Ar interval Op Ar count
1682 .Xc
1683 Displays the detailed health status for the given pools.
1684 If no
1685 .Ar pool
1686 is specified, then the status of each pool in the system is displayed.
1687 For more information on pool and device health, see the
1688 .Sx Device Failure and Recovery
1689 section.
1690 .Pp
1691 If a scrub or resilver is in progress, this command reports the percentage done
1692 and the estimated time to completion.
1693 Both of these are only approximate, because the amount of data in the pool and
1694 the other workloads on the system can change.
1695 .Bl -tag -width Ds
1696 .It Fl D
1697 Display a histogram of deduplication statistics, showing the allocated
1698 .Pq physically present on disk
1699 and referenced
1700 .Pq logically referenced in the pool
1701 block counts and sizes by reference count.
1702 .It Fl T Sy u Ns | Ns Sy d
1703 Display a time stamp.
1704 Specify
1705 .Fl u
1706 for a printed representation of the internal representation of time.
1707 See
1708 .Xr time 2 .
1709 Specify
1710 .Fl d
1711 for standard date format.
1712 See
1713 .Xr date 1 .
1714 .It Fl v
1715 Displays verbose data error information, printing out a complete list of all
1716 data errors since the last complete pool scrub.
1717 .It Fl x
1718 Only display status for pools that are exhibiting errors or are otherwise
1719 unavailable.
1720 Warnings about pools not using the latest on-disk format will not be included.
1721 .El
1722 .It Xo
1723 .Nm
1724 .Cm upgrade
1725 .Xc
1726 Displays pools which do not have all supported features enabled and pools
1727 formatted using a legacy ZFS version number.
1728 These pools can continue to be used, but some features may not be available.
1729 Use
1730 .Nm zpool Cm upgrade Fl a
1731 to enable all features on all pools.
1732 .It Xo
1733 .Nm
1734 .Cm upgrade
1735 .Fl v
1736 .Xc
1737 Displays legacy ZFS versions supported by the current software.
1738 See
1739 .Xr zpool-features 5
1740 for a description of feature flags features supported by the current software.
1741 .It Xo
1742 .Nm
1743 .Cm upgrade
1744 .Op Fl V Ar version
1745 .Fl a Ns | Ns Ar pool Ns ...
1746 .Xc
1747 Enables all supported features on the given pool.
1748 Once this is done, the pool will no longer be accessible on systems that do not
1749 support feature flags.
1750 See
1751 .Xr zpool-features 5
1752 for details on compatibility with systems that support feature flags, but do not
1753 support all features enabled on the pool.
1754 .Bl -tag -width Ds
1755 .It Fl a
1756 Enables all supported features on all pools.
1757 .It Fl V Ar version
1758 Upgrade to the specified legacy version.
1759 If the
1760 .Fl V
1761 flag is specified, no features will be enabled on the pool.
1762 This option can only be used to increase the version number up to the last
1763 supported legacy version number.
1764 .El
1765 .El
1766 .Sh EXIT STATUS
1767 The following exit values are returned:
1768 .Bl -tag -width Ds
1769 .It Sy 0
1770 Successful completion.
1771 .It Sy 1
1772 An error occurred.
1773 .It Sy 2
1774 Invalid command line options were specified.
1775 .El
1776 .Sh EXAMPLES
1777 .Bl -tag -width Ds
1778 .It Sy Example 1 No Creating a RAID-Z Storage Pool
1779 The following command creates a pool with a single raidz root vdev that
1780 consists of six disks.
1781 .Bd -literal
1782 # zpool create tank raidz c0t0d0 c0t1d0 c0t2d0 c0t3d0 c0t4d0 c0t5d0
1783 .Ed
1784 .It Sy Example 2 No Creating a Mirrored Storage Pool
1785 The following command creates a pool with two mirrors, where each mirror
1786 contains two disks.
1787 .Bd -literal
1788 # zpool create tank mirror c0t0d0 c0t1d0 mirror c0t2d0 c0t3d0
1789 .Ed
1790 .It Sy Example 3 No Creating a ZFS Storage Pool by Using Slices
1791 The following command creates an unmirrored pool using two disk slices.
1792 .Bd -literal
1793 # zpool create tank /dev/dsk/c0t0d0s1 c0t1d0s4
1794 .Ed
1795 .It Sy Example 4 No Creating a ZFS Storage Pool by Using Files
1796 The following command creates an unmirrored pool using files.
1797 While not recommended, a pool based on files can be useful for experimental
1798 purposes.
1799 .Bd -literal
1800 # zpool create tank /path/to/file/a /path/to/file/b
1801 .Ed
1802 .It Sy Example 5 No Adding a Mirror to a ZFS Storage Pool
1803 The following command adds two mirrored disks to the pool
1804 .Em tank ,
1805 assuming the pool is already made up of two-way mirrors.
1806 The additional space is immediately available to any datasets within the pool.
1807 .Bd -literal
1808 # zpool add tank mirror c1t0d0 c1t1d0
1809 .Ed
1810 .It Sy Example 6 No Listing Available ZFS Storage Pools
1811 The following command lists all available pools on the system.
1812 In this case, the pool
1813 .Em zion
1814 is faulted due to a missing device.
1815 The results from this command are similar to the following:
1816 .Bd -literal
1817 # zpool list
1818 NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT
1819 rpool 19.9G 8.43G 11.4G 33% - 42% 1.00x ONLINE -
1820 tank 61.5G 20.0G 41.5G 48% - 32% 1.00x ONLINE -
1821 zion - - - - - - - FAULTED -
1822 .Ed
1823 .It Sy Example 7 No Destroying a ZFS Storage Pool
1824 The following command destroys the pool
1825 .Em tank
1826 and any datasets contained within.
1827 .Bd -literal
1828 # zpool destroy -f tank
1829 .Ed
1830 .It Sy Example 8 No Exporting a ZFS Storage Pool
1831 The following command exports the devices in pool
1832 .Em tank
1833 so that they can be relocated or later imported.
1834 .Bd -literal
1835 # zpool export tank
1836 .Ed
1837 .It Sy Example 9 No Importing a ZFS Storage Pool
1838 The following command displays available pools, and then imports the pool
1839 .Em tank
1840 for use on the system.
1841 The results from this command are similar to the following:
1842 .Bd -literal
1843 # zpool import
1844 pool: tank
1845 id: 15451357997522795478
1846 state: ONLINE
1847 action: The pool can be imported using its name or numeric identifier.
1848 config:
1850 tank ONLINE
1851 mirror ONLINE
1852 c1t2d0 ONLINE
1853 c1t3d0 ONLINE
1855 # zpool import tank
1856 .Ed
1857 .It Sy Example 10 No Upgrading All ZFS Storage Pools to the Current Version
1858 The following command upgrades all ZFS Storage pools to the current version of
1859 the software.
1860 .Bd -literal
1861 # zpool upgrade -a
1862 This system is currently running ZFS version 2.
1863 .Ed
1864 .It Sy Example 11 No Managing Hot Spares
1865 The following command creates a new pool with an available hot spare:
1866 .Bd -literal
1867 # zpool create tank mirror c0t0d0 c0t1d0 spare c0t2d0
1868 .Ed
1869 .Pp
1870 If one of the disks were to fail, the pool would be reduced to the degraded
1871 state.
1872 The failed device can be replaced using the following command:
1873 .Bd -literal
1874 # zpool replace tank c0t0d0 c0t3d0
1875 .Ed
1876 .Pp
1877 Once the data has been resilvered, the spare is automatically removed and is
1878 made available for use should another device fail.
1879 The hot spare can be permanently removed from the pool using the following
1880 command:
1881 .Bd -literal
1882 # zpool remove tank c0t2d0
1883 .Ed
1884 .It Sy Example 12 No Creating a ZFS Pool with Mirrored Separate Intent Logs
1885 The following command creates a ZFS storage pool consisting of two, two-way
1886 mirrors and mirrored log devices:
1887 .Bd -literal
1888 # zpool create pool mirror c0d0 c1d0 mirror c2d0 c3d0 log mirror \e
1889 c4d0 c5d0
1890 .Ed
1891 .It Sy Example 13 No Adding Cache Devices to a ZFS Pool
1892 The following command adds two disks for use as cache devices to a ZFS storage
1893 pool:
1894 .Bd -literal
1895 # zpool add pool cache c2d0 c3d0
1896 .Ed
1897 .Pp
1898 Once added, the cache devices gradually fill with content from main memory.
1899 Depending on the size of your cache devices, it could take over an hour for
1900 them to fill.
1901 Capacity and reads can be monitored using the
1902 .Cm iostat
1903 option as follows:
1904 .Bd -literal
1905 # zpool iostat -v pool 5
1906 .Ed
1907 .It Sy Example 14 No Removing a Mirrored top-level (Log or Data) Device
1908 The following commands remove the mirrored log device
1909 .Sy mirror-2
1910 and mirrored top-level data device
1911 .Sy mirror-1 .
1912 .Pp
1913 Given this configuration:
1914 .Bd -literal
1915 pool: tank
1916 state: ONLINE
1917 scrub: none requested
1918 config:
1920 NAME STATE READ WRITE CKSUM
1921 tank ONLINE 0 0 0
1922 mirror-0 ONLINE 0 0 0
1923 c6t0d0 ONLINE 0 0 0
1924 c6t1d0 ONLINE 0 0 0
1925 mirror-1 ONLINE 0 0 0
1926 c6t2d0 ONLINE 0 0 0
1927 c6t3d0 ONLINE 0 0 0
1928 logs
1929 mirror-2 ONLINE 0 0 0
1930 c4t0d0 ONLINE 0 0 0
1931 c4t1d0 ONLINE 0 0 0
1932 .Ed
1933 .Pp
1934 The command to remove the mirrored log
1935 .Sy mirror-2
1936 is:
1937 .Bd -literal
1938 # zpool remove tank mirror-2
1939 .Ed
1940 .Pp
1941 The command to remove the mirrored data
1942 .Sy mirror-1
1943 is:
1944 .Bd -literal
1945 # zpool remove tank mirror-1
1946 .Ed
1947 .It Sy Example 15 No Displaying expanded space on a device
1948 The following command displays the detailed information for the pool
1949 .Em data .
1950 This pool is comprised of a single raidz vdev where one of its devices
1951 increased its capacity by 10GB.
1952 In this example, the pool will not be able to utilize this extra capacity until
1953 all the devices under the raidz vdev have been expanded.
1954 .Bd -literal
1955 # zpool list -v data
1956 NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT
1957 data 23.9G 14.6G 9.30G 48% - 61% 1.00x ONLINE -
1958 raidz1 23.9G 14.6G 9.30G 48% -
1959 c1t1d0 - - - - -
1960 c1t2d0 - - - - 10G
1961 c1t3d0 - - - - -
1962 .Ed
1963 .El
1964 .Sh INTERFACE STABILITY
1965 .Sy Evolving
1966 .Sh SEE ALSO
1967 .Xr zfs 1M ,
1968 .Xr attributes 5 ,
1969 .Xr zpool-features 5