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