| blob | 90c2da4459d481b214cba4510f8d40d44bfc479a |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 2011, Nexenta Systems, Inc. All Rights Reserved.
4 .\" Copyright (c) 2012 by Delphix. All rights reserved.
5 .\" The contents of this file are subject to the terms of the Common Development
6 .\" and Distribution License (the "License"). You may not use this file except
7 .\" in compliance with the License. You can obtain a copy of the license at
8 .\" usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
9 .\"
10 .\" See the License for the specific language governing permissions and
11 .\" limitations under the License. When distributing Covered Code, include this
12 .\" CDDL HEADER in each file and include the License file at
13 .\" usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this
14 .\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your
15 .\" own identifying information:
16 .\" Portions Copyright [yyyy] [name of copyright owner]
17 .TH ZPOOL 1M "Mar 16, 2012"
18 .SH NAME
19 zpool \- configures ZFS storage pools
20 .SH SYNOPSIS
21 .LP
22 .nf
23 \fBzpool\fR [\fB-?\fR]
24 .fi
26 .LP
27 .nf
28 \fBzpool add\fR [\fB-fn\fR] \fIpool\fR \fIvdev\fR ...
29 .fi
31 .LP
32 .nf
33 \fBzpool attach\fR [\fB-f\fR] \fIpool\fR \fIdevice\fR \fInew_device\fR
34 .fi
36 .LP
37 .nf
38 \fBzpool clear\fR \fIpool\fR [\fIdevice\fR]
39 .fi
41 .LP
42 .nf
43 \fBzpool create\fR [\fB-fnd\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-O\fR \fIfile-system-property=value\fR]
44 ... [\fB-m\fR \fImountpoint\fR] [\fB-R\fR \fIroot\fR] \fIpool\fR \fIvdev\fR ...
45 .fi
47 .LP
48 .nf
49 \fBzpool destroy\fR [\fB-f\fR] \fIpool\fR
50 .fi
52 .LP
53 .nf
54 \fBzpool detach\fR \fIpool\fR \fIdevice\fR
55 .fi
57 .LP
58 .nf
59 \fBzpool export\fR [\fB-f\fR] \fIpool\fR ...
60 .fi
62 .LP
63 .nf
64 \fBzpool get\fR "\fIall\fR" | \fIproperty\fR[,...] \fIpool\fR ...
65 .fi
67 .LP
68 .nf
69 \fBzpool history\fR [\fB-il\fR] [\fIpool\fR] ...
70 .fi
72 .LP
73 .nf
74 \fBzpool import\fR [\fB-d\fR \fIdir\fR] [\fB-D\fR]
75 .fi
77 .LP
78 .nf
79 \fBzpool import\fR [\fB-o \fImntopts\fR\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]
80 [\fB-D\fR] [\fB-f\fR] [\fB-R\fR \fIroot\fR] \fB-a\fR
81 .fi
83 .LP
84 .nf
85 \fBzpool import\fR [\fB-o \fImntopts\fR\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]
86 [\fB-D\fR] [\fB-f\fR] [\fB-R\fR \fIroot\fR] \fIpool\fR |\fIid\fR [\fInewpool\fR]
87 .fi
89 .LP
90 .nf
91 \fBzpool iostat\fR [\fB-T\fR u | d ] [\fB-v\fR] [\fIpool\fR] ... [\fIinterval\fR[\fIcount\fR]]
92 .fi
94 .LP
95 .nf
96 \fBzpool list\fR [\fB-Hv\fR] [\fB-o\fR \fIproperty\fR[,...]] [\fIpool\fR] ...
97 .fi
99 .LP
100 .nf
101 \fBzpool offline\fR [\fB-t\fR] \fIpool\fR \fIdevice\fR ...
102 .fi
104 .LP
105 .nf
106 \fBzpool online\fR \fIpool\fR \fIdevice\fR ...
107 .fi
109 .LP
110 .nf
111 \fBzpool reguid\fR \fIpool\fR
112 .fi
114 .LP
115 .nf
116 \fBzpool reopen\fR \fIpool\fR
117 .fi
119 .LP
120 .nf
121 \fBzpool remove\fR \fIpool\fR \fIdevice\fR ...
122 .fi
124 .LP
125 .nf
126 \fBzpool replace\fR [\fB-f\fR] \fIpool\fR \fIdevice\fR [\fInew_device\fR]
127 .fi
129 .LP
130 .nf
131 \fBzpool scrub\fR [\fB-s\fR] \fIpool\fR ...
132 .fi
134 .LP
135 .nf
136 \fBzpool set\fR \fIproperty\fR=\fIvalue\fR \fIpool\fR
137 .fi
139 .LP
140 .nf
141 \fBzpool status\fR [\fB-xv\fR] [\fIpool\fR] ...
142 .fi
144 .LP
145 .nf
146 \fBzpool upgrade\fR
147 .fi
149 .LP
150 .nf
151 \fBzpool upgrade\fR \fB-v\fR
152 .fi
154 .LP
155 .nf
156 \fBzpool upgrade\fR [\fB-V\fR \fIversion\fR] \fB-a\fR | \fIpool\fR ...
157 .fi
159 .SH DESCRIPTION
160 .sp
161 .LP
162 The \fBzpool\fR command configures \fBZFS\fR storage pools. A storage pool is a
163 collection of devices that provides physical storage and data replication for
164 \fBZFS\fR datasets.
165 .sp
166 .LP
167 All datasets within a storage pool share the same space. See \fBzfs\fR(1M) for
168 information on managing datasets.
169 .SS "Virtual Devices (\fBvdev\fRs)"
170 .sp
171 .LP
172 A "virtual device" describes a single device or a collection of devices
173 organized according to certain performance and fault characteristics. The
174 following virtual devices are supported:
175 .sp
176 .ne 2
177 .na
178 \fB\fBdisk\fR\fR
179 .ad
180 .RS 10n
181 A block device, typically located under \fB/dev/dsk\fR. \fBZFS\fR can use
182 individual slices or partitions, though the recommended mode of operation is to
183 use whole disks. A disk can be specified by a full path, or it can be a
184 shorthand name (the relative portion of the path under "/dev/dsk"). A whole
185 disk can be specified by omitting the slice or partition designation. For
186 example, "c0t0d0" is equivalent to "/dev/dsk/c0t0d0s2". When given a whole
187 disk, \fBZFS\fR automatically labels the disk, if necessary.
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fBfile\fR\fR
194 .ad
195 .RS 10n
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 .RE
202 .sp
203 .ne 2
204 .na
205 \fB\fBmirror\fR\fR
206 .ad
207 .RS 10n
208 A mirror of two or more devices. Data is replicated in an identical fashion
209 across all components of a mirror. A mirror with \fIN\fR disks of size \fIX\fR
210 can hold \fIX\fR bytes and can withstand (\fIN-1\fR) devices failing before
211 data integrity is compromised.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fBraidz\fR\fR
218 .ad
219 .br
220 .na
221 \fB\fBraidz1\fR\fR
222 .ad
223 .br
224 .na
225 \fB\fBraidz2\fR\fR
226 .ad
227 .br
228 .na
229 \fB\fBraidz3\fR\fR
230 .ad
231 .RS 10n
232 A variation on \fBRAID-5\fR that allows for better distribution of parity and
233 eliminates the "\fBRAID-5\fR write hole" (in which data and parity become
234 inconsistent after a power loss). Data and parity is striped across all disks
235 within a \fBraidz\fR group.
236 .sp
237 A \fBraidz\fR group can have single-, double- , or triple parity, meaning that
238 the \fBraidz\fR group can sustain one, two, or three failures, respectively,
239 without losing any data. The \fBraidz1\fR \fBvdev\fR type specifies a
240 single-parity \fBraidz\fR group; the \fBraidz2\fR \fBvdev\fR type specifies a
241 double-parity \fBraidz\fR group; and the \fBraidz3\fR \fBvdev\fR type specifies
242 a triple-parity \fBraidz\fR group. The \fBraidz\fR \fBvdev\fR type is an alias
243 for \fBraidz1\fR.
244 .sp
245 A \fBraidz\fR group with \fIN\fR disks of size \fIX\fR with \fIP\fR parity
246 disks can hold approximately (\fIN-P\fR)*\fIX\fR bytes and can withstand
247 \fIP\fR device(s) failing before data integrity is compromised. The minimum
248 number of devices in a \fBraidz\fR group is one more than the number of parity
249 disks. The recommended number is between 3 and 9 to help increase performance.
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB\fBspare\fR\fR
256 .ad
257 .RS 10n
258 A special pseudo-\fBvdev\fR which keeps track of available hot spares for a
259 pool. For more information, see the "Hot Spares" section.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBlog\fR\fR
266 .ad
267 .RS 10n
268 A separate-intent log device. If more than one log device is specified, then
269 writes are load-balanced between devices. Log devices can be mirrored. However,
270 \fBraidz\fR \fBvdev\fR types are not supported for the intent log. For more
271 information, see the "Intent Log" section.
272 .RE
274 .sp
275 .ne 2
276 .na
277 \fB\fBcache\fR\fR
278 .ad
279 .RS 10n
280 A device used to cache storage pool data. A cache device cannot be cannot be
281 configured as a mirror or \fBraidz\fR group. For more information, see the
282 "Cache Devices" section.
283 .RE
285 .sp
286 .LP
287 Virtual devices cannot be nested, so a mirror or \fBraidz\fR virtual device can
288 only contain files or disks. Mirrors of mirrors (or other combinations) are not
289 allowed.
290 .sp
291 .LP
292 A pool can have any number of virtual devices at the top of the configuration
293 (known as "root vdevs"). Data is dynamically distributed across all top-level
294 devices to balance data among devices. As new virtual devices are added,
295 \fBZFS\fR automatically places data on the newly available devices.
296 .sp
297 .LP
298 Virtual devices are specified one at a time on the command line, separated by
299 whitespace. The keywords "mirror" and "raidz" are used to distinguish where a
300 group ends and another begins. For example, the following creates two root
301 vdevs, each a mirror of two disks:
302 .sp
303 .in +2
304 .nf
305 # \fBzpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0\fR
306 .fi
307 .in -2
308 .sp
310 .SS "Device Failure and Recovery"
311 .sp
312 .LP
313 \fBZFS\fR supports a rich set of mechanisms for handling device failure and
314 data corruption. All metadata and data is checksummed, and \fBZFS\fR
315 automatically repairs bad data from a good copy when corruption is detected.
316 .sp
317 .LP
318 In order to take advantage of these features, a pool must make use of some form
319 of redundancy, using either mirrored or \fBraidz\fR groups. While \fBZFS\fR
320 supports running in a non-redundant configuration, where each root vdev is
321 simply a disk or file, this is strongly discouraged. A single case of bit
322 corruption can render some or all of your data unavailable.
323 .sp
324 .LP
325 A pool's health status is described by one of three states: online, degraded,
326 or faulted. An online pool has all devices operating normally. A degraded pool
327 is one in which one or more devices have failed, but the data is still
328 available due to a redundant configuration. A faulted pool has corrupted
329 metadata, or one or more faulted devices, and insufficient replicas to continue
330 functioning.
331 .sp
332 .LP
333 The health of the top-level vdev, such as mirror or \fBraidz\fR device, is
334 potentially impacted by the state of its associated vdevs, or component
335 devices. A top-level vdev or component device is in one of the following
336 states:
337 .sp
338 .ne 2
339 .na
340 \fB\fBDEGRADED\fR\fR
341 .ad
342 .RS 12n
343 One or more top-level vdevs is in the degraded state because one or more
344 component devices are offline. Sufficient replicas exist to continue
345 functioning.
346 .sp
347 One or more component devices is in the degraded or faulted state, but
348 sufficient replicas exist to continue functioning. The underlying conditions
349 are as follows:
350 .RS +4
351 .TP
352 .ie t \(bu
353 .el o
354 The number of checksum errors exceeds acceptable levels and the device is
355 degraded as an indication that something may be wrong. \fBZFS\fR continues to
356 use the device as necessary.
357 .RE
358 .RS +4
359 .TP
360 .ie t \(bu
361 .el o
362 The number of I/O errors exceeds acceptable levels. The device could not be
363 marked as faulted because there are insufficient replicas to continue
364 functioning.
365 .RE
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBFAULTED\fR\fR
372 .ad
373 .RS 12n
374 One or more top-level vdevs is in the faulted state because one or more
375 component devices are offline. Insufficient replicas exist to continue
376 functioning.
377 .sp
378 One or more component devices is in the faulted state, and insufficient
379 replicas exist to continue functioning. The underlying conditions are as
380 follows:
381 .RS +4
382 .TP
383 .ie t \(bu
384 .el o
385 The device could be opened, but the contents did not match expected values.
386 .RE
387 .RS +4
388 .TP
389 .ie t \(bu
390 .el o
391 The number of I/O errors exceeds acceptable levels and the device is faulted to
392 prevent further use of the device.
393 .RE
394 .RE
396 .sp
397 .ne 2
398 .na
399 \fB\fBOFFLINE\fR\fR
400 .ad
401 .RS 12n
402 The device was explicitly taken offline by the "\fBzpool offline\fR" command.
403 .RE
405 .sp
406 .ne 2
407 .na
408 \fB\fBONLINE\fR\fR
409 .ad
410 .RS 12n
411 The device is online and functioning.
412 .RE
414 .sp
415 .ne 2
416 .na
417 \fB\fBREMOVED\fR\fR
418 .ad
419 .RS 12n
420 The device was physically removed while the system was running. Device removal
421 detection is hardware-dependent and may not be supported on all platforms.
422 .RE
424 .sp
425 .ne 2
426 .na
427 \fB\fBUNAVAIL\fR\fR
428 .ad
429 .RS 12n
430 The device could not be opened. If a pool is imported when a device was
431 unavailable, then the device will be identified by a unique identifier instead
432 of its path since the path was never correct in the first place.
433 .RE
435 .sp
436 .LP
437 If a device is removed and later re-attached to the system, \fBZFS\fR attempts
438 to put the device online automatically. Device attach detection is
439 hardware-dependent and might not be supported on all platforms.
440 .SS "Hot Spares"
441 .sp
442 .LP
443 \fBZFS\fR allows devices to be associated with pools as "hot spares". These
444 devices are not actively used in the pool, but when an active device fails, it
445 is automatically replaced by a hot spare. To create a pool with hot spares,
446 specify a "spare" \fBvdev\fR with any number of devices. For example,
447 .sp
448 .in +2
449 .nf
450 # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0
451 .fi
452 .in -2
453 .sp
455 .sp
456 .LP
457 Spares can be shared across multiple pools, and can be added with the "\fBzpool
458 add\fR" command and removed with the "\fBzpool remove\fR" command. Once a spare
459 replacement is initiated, a new "spare" \fBvdev\fR is created within the
460 configuration that will remain there until the original device is replaced. At
461 this point, the hot spare becomes available again if another device fails.
462 .sp
463 .LP
464 If a pool has a shared spare that is currently being used, the pool can not be
465 exported since other pools may use this shared spare, which may lead to
466 potential data corruption.
467 .sp
468 .LP
469 An in-progress spare replacement can be cancelled by detaching the hot spare.
470 If the original faulted device is detached, then the hot spare assumes its
471 place in the configuration, and is removed from the spare list of all active
472 pools.
473 .sp
474 .LP
475 Spares cannot replace log devices.
476 .SS "Intent Log"
477 .sp
478 .LP
479 The \fBZFS\fR Intent Log (\fBZIL\fR) satisfies \fBPOSIX\fR requirements for
480 synchronous transactions. For instance, databases often require their
481 transactions to be on stable storage devices when returning from a system call.
482 \fBNFS\fR and other applications can also use \fBfsync\fR() to ensure data
483 stability. By default, the intent log is allocated from blocks within the main
484 pool. However, it might be possible to get better performance using separate
485 intent log devices such as \fBNVRAM\fR or a dedicated disk. For example:
486 .sp
487 .in +2
488 .nf
489 \fB# zpool create pool c0d0 c1d0 log c2d0\fR
490 .fi
491 .in -2
492 .sp
494 .sp
495 .LP
496 Multiple log devices can also be specified, and they can be mirrored. See the
497 EXAMPLES section for an example of mirroring multiple log devices.
498 .sp
499 .LP
500 Log devices can be added, replaced, attached, detached, and imported and
501 exported as part of the larger pool. Mirrored log devices can be removed by
502 specifying the top-level mirror for the log.
503 .SS "Cache Devices"
504 .sp
505 .LP
506 Devices can be added to a storage pool as "cache devices." These devices
507 provide an additional layer of caching between main memory and disk. For
508 read-heavy workloads, where the working set size is much larger than what can
509 be cached in main memory, using cache devices allow much more of this working
510 set to be served from low latency media. Using cache devices provides the
511 greatest performance improvement for random read-workloads of mostly static
512 content.
513 .sp
514 .LP
515 To create a pool with cache devices, specify a "cache" \fBvdev\fR with any
516 number of devices. For example:
517 .sp
518 .in +2
519 .nf
520 \fB# zpool create pool c0d0 c1d0 cache c2d0 c3d0\fR
521 .fi
522 .in -2
523 .sp
525 .sp
526 .LP
527 Cache devices cannot be mirrored or part of a \fBraidz\fR configuration. If a
528 read error is encountered on a cache device, that read \fBI/O\fR is reissued to
529 the original storage pool device, which might be part of a mirrored or
530 \fBraidz\fR configuration.
531 .sp
532 .LP
533 The content of the cache devices is considered volatile, as is the case with
534 other system caches.
535 .SS "Properties"
536 .sp
537 .LP
538 Each pool has several properties associated with it. Some properties are
539 read-only statistics while others are configurable and change the behavior of
540 the pool. The following are read-only properties:
541 .sp
542 .ne 2
543 .na
544 \fB\fBavailable\fR\fR
545 .ad
546 .RS 20n
547 Amount of storage available within the pool. This property can also be referred
548 to by its shortened column name, "avail".
549 .RE
551 .sp
552 .ne 2
553 .na
554 \fB\fBcapacity\fR\fR
555 .ad
556 .RS 20n
557 Percentage of pool space used. This property can also be referred to by its
558 shortened column name, "cap".
559 .RE
561 .sp
562 .ne 2
563 .na
564 \fB\fBexpandsize\fR\fR
565 .ad
566 .RS 20n
567 Amount of uninitialized space within the pool or device that can be used to
568 increase the total capacity of the pool. Uninitialized space consists of
569 any space on an EFI labeled vdev which has not been brought online
570 (i.e. zpool online -e). This space occurs when a LUN is dynamically expanded.
571 .RE
573 .sp
574 .ne 2
575 .na
576 \fB\fBfree\fR\fR
577 .ad
578 .RS 20n
579 The amount of free space available in the pool.
580 .RE
582 .sp
583 .ne 2
584 .na
585 \fB\fBfreeing\fR\fR
586 .ad
587 .RS 20n
588 After a file system or snapshot is destroyed, the space it was using is
589 returned to the pool asynchronously. \fB\fBfreeing\fR\fR is the amount of
590 space remaining to be reclaimed. Over time \fB\fBfreeing\fR\fR will decrease
591 while \fB\fBfree\fR\fR increases.
592 .RE
594 .sp
595 .ne 2
596 .na
597 \fB\fBhealth\fR\fR
598 .ad
599 .RS 20n
600 The current health of the pool. Health can be "\fBONLINE\fR", "\fBDEGRADED\fR",
601 "\fBFAULTED\fR", " \fBOFFLINE\fR", "\fBREMOVED\fR", or "\fBUNAVAIL\fR".
602 .RE
604 .sp
605 .ne 2
606 .na
607 \fB\fBguid\fR\fR
608 .ad
609 .RS 20n
610 A unique identifier for the pool.
611 .RE
613 .sp
614 .ne 2
615 .na
616 \fB\fBsize\fR\fR
617 .ad
618 .RS 20n
619 Total size of the storage pool.
620 .RE
622 .sp
623 .ne 2
624 .na
625 \fB\fBunsupported@\fR\fIfeature_guid\fR\fR
626 .ad
627 .RS 20n
628 Information about unsupported features that are enabled on the pool. See
629 \fBzpool-features\fR(5) for details.
630 .RE
632 .sp
633 .ne 2
634 .na
635 \fB\fBused\fR\fR
636 .ad
637 .RS 20n
638 Amount of storage space used within the pool.
639 .RE
641 .sp
642 .LP
643 The space usage properties report actual physical space available to the
644 storage pool. The physical space can be different from the total amount of
645 space that any contained datasets can actually use. The amount of space used in
646 a \fBraidz\fR configuration depends on the characteristics of the data being
647 written. In addition, \fBZFS\fR reserves some space for internal accounting
648 that the \fBzfs\fR(1M) command takes into account, but the \fBzpool\fR command
649 does not. For non-full pools of a reasonable size, these effects should be
650 invisible. For small pools, or pools that are close to being completely full,
651 these discrepancies may become more noticeable.
652 .sp
653 .LP
654 The following property can be set at creation time and import time:
655 .sp
656 .ne 2
657 .na
658 \fB\fBaltroot\fR\fR
659 .ad
660 .sp .6
661 .RS 4n
662 Alternate root directory. If set, this directory is prepended to any mount
663 points within the pool. This can be used when examining an unknown pool where
664 the mount points cannot be trusted, or in an alternate boot environment, where
665 the typical paths are not valid. \fBaltroot\fR is not a persistent property. It
666 is valid only while the system is up. Setting \fBaltroot\fR defaults to using
667 \fBcachefile\fR=none, though this may be overridden using an explicit setting.
668 .RE
670 .sp
671 .LP
672 The following properties can be set at creation time and import time, and later
673 changed with the \fBzpool set\fR command:
674 .sp
675 .ne 2
676 .na
677 \fB\fBautoexpand\fR=\fBon\fR | \fBoff\fR\fR
678 .ad
679 .sp .6
680 .RS 4n
681 Controls automatic pool expansion when the underlying LUN is grown. If set to
682 \fBon\fR, the pool will be resized according to the size of the expanded
683 device. If the device is part of a mirror or \fBraidz\fR then all devices
684 within that mirror/\fBraidz\fR group must be expanded before the new space is
685 made available to the pool. The default behavior is \fBoff\fR. This property
686 can also be referred to by its shortened column name, \fBexpand\fR.
687 .RE
689 .sp
690 .ne 2
691 .na
692 \fB\fBautoreplace\fR=\fBon\fR | \fBoff\fR\fR
693 .ad
694 .sp .6
695 .RS 4n
696 Controls automatic device replacement. If set to "\fBoff\fR", device
697 replacement must be initiated by the administrator by using the "\fBzpool
698 replace\fR" command. If set to "\fBon\fR", any new device, found in the same
699 physical location as a device that previously belonged to the pool, is
700 automatically formatted and replaced. The default behavior is "\fBoff\fR". This
701 property can also be referred to by its shortened column name, "replace".
702 .RE
704 .sp
705 .ne 2
706 .na
707 \fB\fBbootfs\fR=\fIpool\fR/\fIdataset\fR\fR
708 .ad
709 .sp .6
710 .RS 4n
711 Identifies the default bootable dataset for the root pool. This property is
712 expected to be set mainly by the installation and upgrade programs.
713 .RE
715 .sp
716 .ne 2
717 .na
718 \fB\fBcachefile\fR=\fIpath\fR | \fBnone\fR\fR
719 .ad
720 .sp .6
721 .RS 4n
722 Controls the location of where the pool configuration is cached. Discovering
723 all pools on system startup requires a cached copy of the configuration data
724 that is stored on the root file system. All pools in this cache are
725 automatically imported when the system boots. Some environments, such as
726 install and clustering, need to cache this information in a different location
727 so that pools are not automatically imported. Setting this property caches the
728 pool configuration in a different location that can later be imported with
729 "\fBzpool import -c\fR". Setting it to the special value "\fBnone\fR" creates a
730 temporary pool that is never cached, and the special value \fB\&''\fR (empty
731 string) uses the default location.
732 .sp
733 Multiple pools can share the same cache file. Because the kernel destroys and
734 recreates this file when pools are added and removed, care should be taken when
735 attempting to access this file. When the last pool using a \fBcachefile\fR is
736 exported or destroyed, the file is removed.
737 .RE
739 .sp
740 .ne 2
741 .na
742 \fB\fBcomment\fR=\fB\fItext\fR\fR
743 .ad
744 .RS 4n
745 A text string consisting of printable ASCII characters that will be stored
746 such that it is available even if the pool becomes faulted. An administrator
747 can provide additional information about a pool using this property.
748 .RE
750 .sp
751 .ne 2
752 .na
753 \fB\fBdelegation\fR=\fBon\fR | \fBoff\fR\fR
754 .ad
755 .sp .6
756 .RS 4n
757 Controls whether a non-privileged user is granted access based on the dataset
758 permissions defined on the dataset. See \fBzfs\fR(1M) for more information on
759 \fBZFS\fR delegated administration.
760 .RE
762 .sp
763 .ne 2
764 .na
765 \fB\fBfailmode\fR=\fBwait\fR | \fBcontinue\fR | \fBpanic\fR\fR
766 .ad
767 .sp .6
768 .RS 4n
769 Controls the system behavior in the event of catastrophic pool failure. This
770 condition is typically a result of a loss of connectivity to the underlying
771 storage device(s) or a failure of all devices within the pool. The behavior of
772 such an event is determined as follows:
773 .sp
774 .ne 2
775 .na
776 \fB\fBwait\fR\fR
777 .ad
778 .RS 12n
779 Blocks all \fBI/O\fR access until the device connectivity is recovered and the
780 errors are cleared. This is the default behavior.
781 .RE
783 .sp
784 .ne 2
785 .na
786 \fB\fBcontinue\fR\fR
787 .ad
788 .RS 12n
789 Returns \fBEIO\fR to any new write \fBI/O\fR requests but allows reads to any
790 of the remaining healthy devices. Any write requests that have yet to be
791 committed to disk would be blocked.
792 .RE
794 .sp
795 .ne 2
796 .na
797 \fB\fBpanic\fR\fR
798 .ad
799 .RS 12n
800 Prints out a message to the console and generates a system crash dump.
801 .RE
803 .RE
805 .sp
806 .ne 2
807 .na
808 \fB\fBfeature@\fR\fIfeature_name\fR=\fBenabled\fR\fR
809 .ad
810 .RS 4n
811 The value of this property is the current state of \fIfeature_name\fR. The
812 only valid value when setting this property is \fBenabled\fR which moves
813 \fIfeature_name\fR to the enabled state. See \fBzpool-features\fR(5) for
814 details on feature states.
815 .RE
817 .sp
818 .ne 2
819 .na
820 \fB\fBlistsnaps\fR=on | off\fR
821 .ad
822 .sp .6
823 .RS 4n
824 Controls whether information about snapshots associated with this pool is
825 output when "\fBzfs list\fR" is run without the \fB-t\fR option. The default
826 value is "off".
827 .RE
829 .sp
830 .ne 2
831 .na
832 \fB\fBversion\fR=\fIversion\fR\fR
833 .ad
834 .sp .6
835 .RS 4n
836 The current on-disk version of the pool. This can be increased, but never
837 decreased. The preferred method of updating pools is with the "\fBzpool
838 upgrade\fR" command, though this property can be used when a specific version
839 is needed for backwards compatibility. Once feature flags is enabled on a
840 pool this property will no longer have a value.
841 .RE
843 .SS "Subcommands"
844 .sp
845 .LP
846 All subcommands that modify state are logged persistently to the pool in their
847 original form.
848 .sp
849 .LP
850 The \fBzpool\fR command provides subcommands to create and destroy storage
851 pools, add capacity to storage pools, and provide information about the storage
852 pools. The following subcommands are supported:
853 .sp
854 .ne 2
855 .na
856 \fB\fBzpool\fR \fB-?\fR\fR
857 .ad
858 .sp .6
859 .RS 4n
860 Displays a help message.
861 .RE
863 .sp
864 .ne 2
865 .na
866 \fB\fBzpool add\fR [\fB-fn\fR] \fIpool\fR \fIvdev\fR ...\fR
867 .ad
868 .sp .6
869 .RS 4n
870 Adds the specified virtual devices to the given pool. The \fIvdev\fR
871 specification is described in the "Virtual Devices" section. The behavior of
872 the \fB-f\fR option, and the device checks performed are described in the
873 "zpool create" subcommand.
874 .sp
875 .ne 2
876 .na
877 \fB\fB-f\fR\fR
878 .ad
879 .RS 6n
880 Forces use of \fBvdev\fRs, even if they appear in use or specify a conflicting
881 replication level. Not all devices can be overridden in this manner.
882 .RE
884 .sp
885 .ne 2
886 .na
887 \fB\fB-n\fR\fR
888 .ad
889 .RS 6n
890 Displays the configuration that would be used without actually adding the
891 \fBvdev\fRs. The actual pool creation can still fail due to insufficient
892 privileges or device sharing.
893 .RE
895 Do not add a disk that is currently configured as a quorum device to a zpool.
896 After a disk is in the pool, that disk can then be configured as a quorum
897 device.
898 .RE
900 .sp
901 .ne 2
902 .na
903 \fB\fBzpool attach\fR [\fB-f\fR] \fIpool\fR \fIdevice\fR \fInew_device\fR\fR
904 .ad
905 .sp .6
906 .RS 4n
907 Attaches \fInew_device\fR to an existing \fBzpool\fR device. The existing
908 device cannot be part of a \fBraidz\fR configuration. If \fIdevice\fR is not
909 currently part of a mirrored configuration, \fIdevice\fR automatically
910 transforms into a two-way mirror of \fIdevice\fR and \fInew_device\fR. If
911 \fIdevice\fR is part of a two-way mirror, attaching \fInew_device\fR creates a
912 three-way mirror, and so on. In either case, \fInew_device\fR begins to
913 resilver immediately.
914 .sp
915 .ne 2
916 .na
917 \fB\fB-f\fR\fR
918 .ad
919 .RS 6n
920 Forces use of \fInew_device\fR, even if its appears to be in use. Not all
921 devices can be overridden in this manner.
922 .RE
924 .RE
926 .sp
927 .ne 2
928 .na
929 \fB\fBzpool clear\fR \fIpool\fR [\fIdevice\fR] ...\fR
930 .ad
931 .sp .6
932 .RS 4n
933 Clears device errors in a pool. If no arguments are specified, all device
934 errors within the pool are cleared. If one or more devices is specified, only
935 those errors associated with the specified device or devices are cleared.
936 .RE
938 .sp
939 .ne 2
940 .na
941 \fB\fBzpool create\fR [\fB-fnd\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-O\fR
942 \fIfile-system-property=value\fR] ... [\fB-m\fR \fImountpoint\fR] [\fB-R\fR
943 \fIroot\fR] \fIpool\fR \fIvdev\fR ...\fR
944 .ad
945 .sp .6
946 .RS 4n
947 Creates a new storage pool containing the virtual devices specified on the
948 command line. The pool name must begin with a letter, and can only contain
949 alphanumeric characters as well as underscore ("_"), dash ("-"), and period
950 ("."). The pool names "mirror", "raidz", "spare" and "log" are reserved, as are
951 names beginning with the pattern "c[0-9]". The \fBvdev\fR specification is
952 described in the "Virtual Devices" section.
953 .sp
954 The command verifies that each device specified is accessible and not currently
955 in use by another subsystem. There are some uses, such as being currently
956 mounted, or specified as the dedicated dump device, that prevents a device from
957 ever being used by \fBZFS\fR. Other uses, such as having a preexisting
958 \fBUFS\fR file system, can be overridden with the \fB-f\fR option.
959 .sp
960 The command also checks that the replication strategy for the pool is
961 consistent. An attempt to combine redundant and non-redundant storage in a
962 single pool, or to mix disks and files, results in an error unless \fB-f\fR is
963 specified. The use of differently sized devices within a single \fBraidz\fR or
964 mirror group is also flagged as an error unless \fB-f\fR is specified.
965 .sp
966 Unless the \fB-R\fR option is specified, the default mount point is
967 "/\fIpool\fR". The mount point must not exist or must be empty, or else the
968 root dataset cannot be mounted. This can be overridden with the \fB-m\fR
969 option.
970 .sp
971 By default all supported features are enabled on the new pool unless the
972 \fB-d\fR option is specified.
973 .sp
974 .ne 2
975 .na
976 \fB\fB-f\fR\fR
977 .ad
978 .sp .6
979 .RS 4n
980 Forces use of \fBvdev\fRs, even if they appear in use or specify a conflicting
981 replication level. Not all devices can be overridden in this manner.
982 .RE
984 .sp
985 .ne 2
986 .na
987 \fB\fB-n\fR\fR
988 .ad
989 .sp .6
990 .RS 4n
991 Displays the configuration that would be used without actually creating the
992 pool. The actual pool creation can still fail due to insufficient privileges or
993 device sharing.
994 .RE
996 .sp
997 .ne 2
998 .na
999 \fB\fB-d\fR\fR
1000 .ad
1001 .sp .6
1002 .RS 4n
1003 Do not enable any features on the new pool. Individual features can be enabled
1004 by setting their corresponding properties to \fBenabled\fR with the \fB-o\fR
1005 option. See \fBzpool-features\fR(5) for details about feature properties.
1006 .RE
1008 .sp
1009 .ne 2
1010 .na
1011 \fB\fB-o\fR \fIproperty=value\fR [\fB-o\fR \fIproperty=value\fR] ...\fR
1012 .ad
1013 .sp .6
1014 .RS 4n
1015 Sets the given pool properties. See the "Properties" section for a list of
1016 valid properties that can be set.
1017 .RE
1019 .sp
1020 .ne 2
1021 .na
1022 \fB\fB-O\fR \fIfile-system-property=value\fR\fR
1023 .ad
1024 .br
1025 .na
1026 \fB[\fB-O\fR \fIfile-system-property=value\fR] ...\fR
1027 .ad
1028 .sp .6
1029 .RS 4n
1030 Sets the given file system properties in the root file system of the pool. See
1031 the "Properties" section of \fBzfs\fR(1M) for a list of valid properties that
1032 can be set.
1033 .RE
1035 .sp
1036 .ne 2
1037 .na
1038 \fB\fB-R\fR \fIroot\fR\fR
1039 .ad
1040 .sp .6
1041 .RS 4n
1042 Equivalent to "-o cachefile=none,altroot=\fIroot\fR"
1043 .RE
1045 .sp
1046 .ne 2
1047 .na
1048 \fB\fB-m\fR \fImountpoint\fR\fR
1049 .ad
1050 .sp .6
1051 .RS 4n
1052 Sets the mount point for the root dataset. The default mount point is
1053 "/\fIpool\fR" or "\fBaltroot\fR/\fIpool\fR" if \fBaltroot\fR is specified. The
1054 mount point must be an absolute path, "\fBlegacy\fR", or "\fBnone\fR". For more
1055 information on dataset mount points, see \fBzfs\fR(1M).
1056 .RE
1058 .RE
1060 .sp
1061 .ne 2
1062 .na
1063 \fB\fBzpool destroy\fR [\fB-f\fR] \fIpool\fR\fR
1064 .ad
1065 .sp .6
1066 .RS 4n
1067 Destroys the given pool, freeing up any devices for other use. This command
1068 tries to unmount any active datasets before destroying the pool.
1069 .sp
1070 .ne 2
1071 .na
1072 \fB\fB-f\fR\fR
1073 .ad
1074 .RS 6n
1075 Forces any active datasets contained within the pool to be unmounted.
1076 .RE
1078 .RE
1080 .sp
1081 .ne 2
1082 .na
1083 \fB\fBzpool detach\fR \fIpool\fR \fIdevice\fR\fR
1084 .ad
1085 .sp .6
1086 .RS 4n
1087 Detaches \fIdevice\fR from a mirror. The operation is refused if there are no
1088 other valid replicas of the data.
1089 .RE
1091 .sp
1092 .ne 2
1093 .na
1094 \fB\fBzpool export\fR [\fB-f\fR] \fIpool\fR ...\fR
1095 .ad
1096 .sp .6
1097 .RS 4n
1098 Exports the given pools from the system. All devices are marked as exported,
1099 but are still considered in use by other subsystems. The devices can be moved
1100 between systems (even those of different endianness) and imported as long as a
1101 sufficient number of devices are present.
1102 .sp
1103 Before exporting the pool, all datasets within the pool are unmounted. A pool
1104 can not be exported if it has a shared spare that is currently being used.
1105 .sp
1106 For pools to be portable, you must give the \fBzpool\fR command whole disks,
1107 not just slices, so that \fBZFS\fR can label the disks with portable \fBEFI\fR
1108 labels. Otherwise, disk drivers on platforms of different endianness will not
1109 recognize the disks.
1110 .sp
1111 .ne 2
1112 .na
1113 \fB\fB-f\fR\fR
1114 .ad
1115 .RS 6n
1116 Forcefully unmount all datasets, using the "\fBunmount -f\fR" command.
1117 .sp
1118 This command will forcefully export the pool even if it has a shared spare that
1119 is currently being used. This may lead to potential data corruption.
1120 .RE
1122 .RE
1124 .sp
1125 .ne 2
1126 .na
1127 \fB\fBzpool get\fR "\fIall\fR" | \fIproperty\fR[,...] \fIpool\fR ...\fR
1128 .ad
1129 .sp .6
1130 .RS 4n
1131 Retrieves the given list of properties (or all properties if "\fBall\fR" is
1132 used) for the specified storage pool(s). These properties are displayed with
1133 the following fields:
1134 .sp
1135 .in +2
1136 .nf
1137 name Name of storage pool
1138 property Property name
1139 value Property value
1140 source Property source, either 'default' or 'local'.
1141 .fi
1142 .in -2
1143 .sp
1145 See the "Properties" section for more information on the available pool
1146 properties.
1147 .RE
1149 .sp
1150 .ne 2
1151 .na
1152 \fB\fBzpool history\fR [\fB-il\fR] [\fIpool\fR] ...\fR
1153 .ad
1154 .sp .6
1155 .RS 4n
1156 Displays the command history of the specified pools or all pools if no pool is
1157 specified.
1158 .sp
1159 .ne 2
1160 .na
1161 \fB\fB-i\fR\fR
1162 .ad
1163 .RS 6n
1164 Displays internally logged \fBZFS\fR events in addition to user initiated
1165 events.
1166 .RE
1168 .sp
1169 .ne 2
1170 .na
1171 \fB\fB-l\fR\fR
1172 .ad
1173 .RS 6n
1174 Displays log records in long format, which in addition to standard format
1175 includes, the user name, the hostname, and the zone in which the operation was
1176 performed.
1177 .RE
1179 .RE
1181 .sp
1182 .ne 2
1183 .na
1184 \fB\fBzpool import\fR [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]
1185 [\fB-D\fR]\fR
1186 .ad
1187 .sp .6
1188 .RS 4n
1189 Lists pools available to import. If the \fB-d\fR option is not specified, this
1190 command searches for devices in "/dev/dsk". The \fB-d\fR option can be
1191 specified multiple times, and all directories are searched. If the device
1192 appears to be part of an exported pool, this command displays a summary of the
1193 pool with the name of the pool, a numeric identifier, as well as the \fIvdev\fR
1194 layout and current health of the device for each device or file. Destroyed
1195 pools, pools that were previously destroyed with the "\fBzpool destroy\fR"
1196 command, are not listed unless the \fB-D\fR option is specified.
1197 .sp
1198 The numeric identifier is unique, and can be used instead of the pool name when
1199 multiple exported pools of the same name are available.
1200 .sp
1201 .ne 2
1202 .na
1203 \fB\fB-c\fR \fIcachefile\fR\fR
1204 .ad
1205 .RS 16n
1206 Reads configuration from the given \fBcachefile\fR that was created with the
1207 "\fBcachefile\fR" pool property. This \fBcachefile\fR is used instead of
1208 searching for devices.
1209 .RE
1211 .sp
1212 .ne 2
1213 .na
1214 \fB\fB-d\fR \fIdir\fR\fR
1215 .ad
1216 .RS 16n
1217 Searches for devices or files in \fIdir\fR. The \fB-d\fR option can be
1218 specified multiple times.
1219 .RE
1221 .sp
1222 .ne 2
1223 .na
1224 \fB\fB-D\fR\fR
1225 .ad
1226 .RS 16n
1227 Lists destroyed pools only.
1228 .RE
1230 .RE
1232 .sp
1233 .ne 2
1234 .na
1235 \fB\fBzpool import\fR [\fB-o\fR \fImntopts\fR] [ \fB-o\fR
1236 \fIproperty\fR=\fIvalue\fR] ... [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]
1237 [\fB-D\fR] [\fB-f\fR] [\fB-R\fR \fIroot\fR] \fB-a\fR\fR
1238 .ad
1239 .sp .6
1240 .RS 4n
1241 Imports all pools found in the search directories. Identical to the previous
1242 command, except that all pools with a sufficient number of devices available
1243 are imported. Destroyed pools, pools that were previously destroyed with the
1244 "\fBzpool destroy\fR" command, will not be imported unless the \fB-D\fR option
1245 is specified.
1246 .sp
1247 .ne 2
1248 .na
1249 \fB\fB-o\fR \fImntopts\fR\fR
1250 .ad
1251 .RS 21n
1252 Comma-separated list of mount options to use when mounting datasets within the
1253 pool. See \fBzfs\fR(1M) for a description of dataset properties and mount
1254 options.
1255 .RE
1257 .sp
1258 .ne 2
1259 .na
1260 \fB\fB-o\fR \fIproperty=value\fR\fR
1261 .ad
1262 .RS 21n
1263 Sets the specified property on the imported pool. See the "Properties" section
1264 for more information on the available pool properties.
1265 .RE
1267 .sp
1268 .ne 2
1269 .na
1270 \fB\fB-c\fR \fIcachefile\fR\fR
1271 .ad
1272 .RS 21n
1273 Reads configuration from the given \fBcachefile\fR that was created with the
1274 "\fBcachefile\fR" pool property. This \fBcachefile\fR is used instead of
1275 searching for devices.
1276 .RE
1278 .sp
1279 .ne 2
1280 .na
1281 \fB\fB-d\fR \fIdir\fR\fR
1282 .ad
1283 .RS 21n
1284 Searches for devices or files in \fIdir\fR. The \fB-d\fR option can be
1285 specified multiple times. This option is incompatible with the \fB-c\fR option.
1286 .RE
1288 .sp
1289 .ne 2
1290 .na
1291 \fB\fB-D\fR\fR
1292 .ad
1293 .RS 21n
1294 Imports destroyed pools only. The \fB-f\fR option is also required.
1295 .RE
1297 .sp
1298 .ne 2
1299 .na
1300 \fB\fB-f\fR\fR
1301 .ad
1302 .RS 21n
1303 Forces import, even if the pool appears to be potentially active.
1304 .RE
1306 .sp
1307 .ne 2
1308 .na
1309 \fB\fB-a\fR\fR
1310 .ad
1311 .RS 21n
1312 Searches for and imports all pools found.
1313 .RE
1315 .sp
1316 .ne 2
1317 .na
1318 \fB\fB-R\fR \fIroot\fR\fR
1319 .ad
1320 .RS 21n
1321 Sets the "\fBcachefile\fR" property to "\fBnone\fR" and the "\fIaltroot\fR"
1322 property to "\fIroot\fR".
1323 .RE
1325 .RE
1327 .sp
1328 .ne 2
1329 .na
1330 \fB\fBzpool import\fR [\fB-o\fR \fImntopts\fR] [ \fB-o\fR
1331 \fIproperty\fR=\fIvalue\fR] ... [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]
1332 [\fB-D\fR] [\fB-f\fR] [\fB-R\fR \fIroot\fR] \fIpool\fR | \fIid\fR
1333 [\fInewpool\fR]\fR
1334 .ad
1335 .sp .6
1336 .RS 4n
1337 Imports a specific pool. A pool can be identified by its name or the numeric
1338 identifier. If \fInewpool\fR is specified, the pool is imported using the name
1339 \fInewpool\fR. Otherwise, it is imported with the same name as its exported
1340 name.
1341 .sp
1342 If a device is removed from a system without running "\fBzpool export\fR"
1343 first, the device appears as potentially active. It cannot be determined if
1344 this was a failed export, or whether the device is really in use from another
1345 host. To import a pool in this state, the \fB-f\fR option is required.
1346 .sp
1347 .ne 2
1348 .na
1349 \fB\fB-o\fR \fImntopts\fR\fR
1350 .ad
1351 .sp .6
1352 .RS 4n
1353 Comma-separated list of mount options to use when mounting datasets within the
1354 pool. See \fBzfs\fR(1M) for a description of dataset properties and mount
1355 options.
1356 .RE
1358 .sp
1359 .ne 2
1360 .na
1361 \fB\fB-o\fR \fIproperty=value\fR\fR
1362 .ad
1363 .sp .6
1364 .RS 4n
1365 Sets the specified property on the imported pool. See the "Properties" section
1366 for more information on the available pool properties.
1367 .RE
1369 .sp
1370 .ne 2
1371 .na
1372 \fB\fB-c\fR \fIcachefile\fR\fR
1373 .ad
1374 .sp .6
1375 .RS 4n
1376 Reads configuration from the given \fBcachefile\fR that was created with the
1377 "\fBcachefile\fR" pool property. This \fBcachefile\fR is used instead of
1378 searching for devices.
1379 .RE
1381 .sp
1382 .ne 2
1383 .na
1384 \fB\fB-d\fR \fIdir\fR\fR
1385 .ad
1386 .sp .6
1387 .RS 4n
1388 Searches for devices or files in \fIdir\fR. The \fB-d\fR option can be
1389 specified multiple times. This option is incompatible with the \fB-c\fR option.
1390 .RE
1392 .sp
1393 .ne 2
1394 .na
1395 \fB\fB-D\fR\fR
1396 .ad
1397 .sp .6
1398 .RS 4n
1399 Imports destroyed pool. The \fB-f\fR option is also required.
1400 .RE
1402 .sp
1403 .ne 2
1404 .na
1405 \fB\fB-f\fR\fR
1406 .ad
1407 .sp .6
1408 .RS 4n
1409 Forces import, even if the pool appears to be potentially active.
1410 .RE
1412 .sp
1413 .ne 2
1414 .na
1415 \fB\fB-R\fR \fIroot\fR\fR
1416 .ad
1417 .sp .6
1418 .RS 4n
1419 Sets the "\fBcachefile\fR" property to "\fBnone\fR" and the "\fIaltroot\fR"
1420 property to "\fIroot\fR".
1421 .RE
1423 .RE
1425 .sp
1426 .ne 2
1427 .na
1428 \fB\fBzpool iostat\fR [\fB-T\fR \fBu\fR | \fBd\fR] [\fB-v\fR] [\fIpool\fR] ...
1429 [\fIinterval\fR[\fIcount\fR]]\fR
1430 .ad
1431 .sp .6
1432 .RS 4n
1433 Displays \fBI/O\fR statistics for the given pools. When given an interval, the
1434 statistics are printed every \fIinterval\fR seconds until \fBCtrl-C\fR is
1435 pressed. If no \fIpools\fR are specified, statistics for every pool in the
1436 system is shown. If \fIcount\fR is specified, the command exits after
1437 \fIcount\fR reports are printed.
1438 .sp
1439 .ne 2
1440 .na
1441 \fB\fB-T\fR \fBu\fR | \fBd\fR\fR
1442 .ad
1443 .RS 12n
1444 Display a time stamp.
1445 .sp
1446 Specify \fBu\fR for a printed representation of the internal representation of
1447 time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
1448 \fBdate\fR(1).
1449 .RE
1451 .sp
1452 .ne 2
1453 .na
1454 \fB\fB-v\fR\fR
1455 .ad
1456 .RS 12n
1457 Verbose statistics. Reports usage statistics for individual \fIvdevs\fR within
1458 the pool, in addition to the pool-wide statistics.
1459 .RE
1461 .RE
1463 .sp
1464 .ne 2
1465 .na
1466 \fB\fBzpool list\fR [\fB-Hv\fR] [\fB-o\fR \fIprops\fR[,...]] [\fIpool\fR] ...\fR
1467 .ad
1468 .sp .6
1469 .RS 4n
1470 Lists the given pools along with a health status and space usage. When given no
1471 arguments, all pools in the system are listed.
1472 .sp
1473 .ne 2
1474 .na
1475 \fB\fB-H\fR\fR
1476 .ad
1477 .RS 12n
1478 Scripted mode. Do not display headers, and separate fields by a single tab
1479 instead of arbitrary space.
1480 .RE
1482 .sp
1483 .ne 2
1484 .na
1485 \fB\fB-o\fR \fIprops\fR\fR
1486 .ad
1487 .RS 12n
1488 Comma-separated list of properties to display. See the "Properties" section for
1489 a list of valid properties. The default list is "name, size, used, available,
1490 expandsize, capacity, dedupratio, health, altroot"
1491 .RE
1493 .sp
1494 .ne 2
1495 .na
1496 \fB\fB-v\fR\fR
1497 .ad
1498 .RS 12n
1499 Verbose statistics. Reports usage statistics for individual \fIvdevs\fR within
1500 the pool, in addition to the pool-wise statistics.
1501 .RE
1503 .RE
1505 .sp
1506 .ne 2
1507 .na
1508 \fB\fBzpool offline\fR [\fB-t\fR] \fIpool\fR \fIdevice\fR ...\fR
1509 .ad
1510 .sp .6
1511 .RS 4n
1512 Takes the specified physical device offline. While the \fIdevice\fR is offline,
1513 no attempt is made to read or write to the device.
1514 .sp
1515 This command is not applicable to spares or cache devices.
1516 .sp
1517 .ne 2
1518 .na
1519 \fB\fB-t\fR\fR
1520 .ad
1521 .RS 6n
1522 Temporary. Upon reboot, the specified physical device reverts to its previous
1523 state.
1524 .RE
1526 .RE
1528 .sp
1529 .ne 2
1530 .na
1531 \fB\fBzpool online\fR [\fB-e\fR] \fIpool\fR \fIdevice\fR...\fR
1532 .ad
1533 .sp .6
1534 .RS 4n
1535 Brings the specified physical device online.
1536 .sp
1537 This command is not applicable to spares or cache devices.
1538 .sp
1539 .ne 2
1540 .na
1541 \fB\fB-e\fR\fR
1542 .ad
1543 .RS 6n
1544 Expand the device to use all available space. If the device is part of a mirror
1545 or \fBraidz\fR then all devices must be expanded before the new space will
1546 become available to the pool.
1547 .RE
1549 .RE
1551 .sp
1552 .ne 2
1553 .na
1554 \fB\fBzpool reguid\fR \fIpool\fR
1555 .ad
1556 .sp .6
1557 .RS 4n
1558 Generates a new unique identifier for the pool. You must ensure that all
1559 devices in this pool are online and healthy before performing this action.
1560 .RE
1562 .sp
1563 .ne 2
1564 .na
1565 \fB\fBzpool reopen\fR \fIpool\fR
1566 .ad
1567 .sp .6
1568 .RS 4n
1569 Reopen all the vdevs associated with the pool.
1570 .RE
1572 .sp
1573 .ne 2
1574 .na
1575 \fB\fBzpool remove\fR \fIpool\fR \fIdevice\fR ...\fR
1576 .ad
1577 .sp .6
1578 .RS 4n
1579 Removes the specified device from the pool. This command currently only
1580 supports removing hot spares, cache, and log devices. A mirrored log device can
1581 be removed by specifying the top-level mirror for the log. Non-log devices that
1582 are part of a mirrored configuration can be removed using the \fBzpool
1583 detach\fR command. Non-redundant and \fBraidz\fR devices cannot be removed from
1584 a pool.
1585 .RE
1587 .sp
1588 .ne 2
1589 .na
1590 \fB\fBzpool replace\fR [\fB-f\fR] \fIpool\fR \fIold_device\fR
1591 [\fInew_device\fR]\fR
1592 .ad
1593 .sp .6
1594 .RS 4n
1595 Replaces \fIold_device\fR with \fInew_device\fR. This is equivalent to
1596 attaching \fInew_device\fR, waiting for it to resilver, and then detaching
1597 \fIold_device\fR.
1598 .sp
1599 The size of \fInew_device\fR must be greater than or equal to the minimum size
1600 of all the devices in a mirror or \fBraidz\fR configuration.
1601 .sp
1602 \fInew_device\fR is required if the pool is not redundant. If \fInew_device\fR
1603 is not specified, it defaults to \fIold_device\fR. This form of replacement is
1604 useful after an existing disk has failed and has been physically replaced. In
1605 this case, the new disk may have the same \fB/dev/dsk\fR path as the old
1606 device, even though it is actually a different disk. \fBZFS\fR recognizes this.
1607 .sp
1608 .ne 2
1609 .na
1610 \fB\fB-f\fR\fR
1611 .ad
1612 .RS 6n
1613 Forces use of \fInew_device\fR, even if its appears to be in use. Not all
1614 devices can be overridden in this manner.
1615 .RE
1617 .RE
1619 .sp
1620 .ne 2
1621 .na
1622 \fB\fBzpool scrub\fR [\fB-s\fR] \fIpool\fR ...\fR
1623 .ad
1624 .sp .6
1625 .RS 4n
1626 Begins a scrub. The scrub examines all data in the specified pools to verify
1627 that it checksums correctly. For replicated (mirror or \fBraidz\fR) devices,
1628 \fBZFS\fR automatically repairs any damage discovered during the scrub. The
1629 "\fBzpool status\fR" command reports the progress of the scrub and summarizes
1630 the results of the scrub upon completion.
1631 .sp
1632 Scrubbing and resilvering are very similar operations. The difference is that
1633 resilvering only examines data that \fBZFS\fR knows to be out of date (for
1634 example, when attaching a new device to a mirror or replacing an existing
1635 device), whereas scrubbing examines all data to discover silent errors due to
1636 hardware faults or disk failure.
1637 .sp
1638 Because scrubbing and resilvering are \fBI/O\fR-intensive operations, \fBZFS\fR
1639 only allows one at a time. If a scrub is already in progress, the "\fBzpool
1640 scrub\fR" command terminates it and starts a new scrub. If a resilver is in
1641 progress, \fBZFS\fR does not allow a scrub to be started until the resilver
1642 completes.
1643 .sp
1644 .ne 2
1645 .na
1646 \fB\fB-s\fR\fR
1647 .ad
1648 .RS 6n
1649 Stop scrubbing.
1650 .RE
1652 .RE
1654 .sp
1655 .ne 2
1656 .na
1657 \fB\fBzpool set\fR \fIproperty\fR=\fIvalue\fR \fIpool\fR\fR
1658 .ad
1659 .sp .6
1660 .RS 4n
1661 Sets the given property on the specified pool. See the "Properties" section for
1662 more information on what properties can be set and acceptable values.
1663 .RE
1665 .sp
1666 .ne 2
1667 .na
1668 \fB\fBzpool status\fR [\fB-xv\fR] [\fIpool\fR] ...\fR
1669 .ad
1670 .sp .6
1671 .RS 4n
1672 Displays the detailed health status for the given pools. If no \fIpool\fR is
1673 specified, then the status of each pool in the system is displayed. For more
1674 information on pool and device health, see the "Device Failure and Recovery"
1675 section.
1676 .sp
1677 If a scrub or resilver is in progress, this command reports the percentage done
1678 and the estimated time to completion. Both of these are only approximate,
1679 because the amount of data in the pool and the other workloads on the system
1680 can change.
1681 .sp
1682 .ne 2
1683 .na
1684 \fB\fB-x\fR\fR
1685 .ad
1686 .RS 6n
1687 Only display status for pools that are exhibiting errors or are otherwise
1688 unavailable.
1689 .RE
1691 .sp
1692 .ne 2
1693 .na
1694 \fB\fB-v\fR\fR
1695 .ad
1696 .RS 6n
1697 Displays verbose data error information, printing out a complete list of all
1698 data errors since the last complete pool scrub.
1699 .RE
1701 .RE
1703 .sp
1704 .ne 2
1705 .na
1706 \fB\fBzpool upgrade\fR\fR
1707 .ad
1708 .sp .6
1709 .RS 4n
1710 Displays pools which do not have all supported features enabled and pools
1711 formatted using a legacy ZFS version number. These pools can continue to be
1712 used, but some features may not be available. Use "\fBzpool upgrade -a\fR"
1713 to enable all features on all pools.
1714 .RE
1716 .sp
1717 .ne 2
1718 .na
1719 \fB\fBzpool upgrade\fR \fB-v\fR\fR
1720 .ad
1721 .sp .6
1722 .RS 4n
1723 Displays legacy \fBZFS\fR versions supported by the current software. See
1724 \fBzfs-features\fR(5) for a description of feature flags features supported
1725 by the current software.
1726 .RE
1728 .sp
1729 .ne 2
1730 .na
1731 \fB\fBzpool upgrade\fR [\fB-V\fR \fIversion\fR] \fB-a\fR | \fIpool\fR ...\fR
1732 .ad
1733 .sp .6
1734 .RS 4n
1735 Enables all supported features on the given pool. Once this is done, the
1736 pool will no longer be accessible on systems that do not support feature
1737 flags. See \fBzfs-features\fR(5) for details on compatability with systems
1738 that support feature flags, but do not support all features enabled on the
1739 pool.
1740 .sp
1741 .ne 2
1742 .na
1743 \fB\fB-a\fR\fR
1744 .ad
1745 .RS 14n
1746 Enables all supported features on all pools.
1747 .RE
1749 .sp
1750 .ne 2
1751 .na
1752 \fB\fB-V\fR \fIversion\fR\fR
1753 .ad
1754 .RS 14n
1755 Upgrade to the specified legacy version. If the \fB-V\fR flag is specified, no
1756 features will be enabled on the pool. This option can only be used to increase
1757 the version number up to the last supported legacy version number.
1758 .RE
1760 .RE
1762 .SH EXAMPLES
1763 .LP
1764 \fBExample 1 \fRCreating a RAID-Z Storage Pool
1765 .sp
1766 .LP
1767 The following command creates a pool with a single \fBraidz\fR root \fIvdev\fR
1768 that consists of six disks.
1770 .sp
1771 .in +2
1772 .nf
1773 # \fBzpool create tank raidz c0t0d0 c0t1d0 c0t2d0 c0t3d0 c0t4d0 c0t5d0\fR
1774 .fi
1775 .in -2
1776 .sp
1778 .LP
1779 \fBExample 2 \fRCreating a Mirrored Storage Pool
1780 .sp
1781 .LP
1782 The following command creates a pool with two mirrors, where each mirror
1783 contains two disks.
1785 .sp
1786 .in +2
1787 .nf
1788 # \fBzpool create tank mirror c0t0d0 c0t1d0 mirror c0t2d0 c0t3d0\fR
1789 .fi
1790 .in -2
1791 .sp
1793 .LP
1794 \fBExample 3 \fRCreating a ZFS Storage Pool by Using Slices
1795 .sp
1796 .LP
1797 The following command creates an unmirrored pool using two disk slices.
1799 .sp
1800 .in +2
1801 .nf
1802 # \fBzpool create tank /dev/dsk/c0t0d0s1 c0t1d0s4\fR
1803 .fi
1804 .in -2
1805 .sp
1807 .LP
1808 \fBExample 4 \fRCreating a ZFS Storage Pool by Using Files
1809 .sp
1810 .LP
1811 The following command creates an unmirrored pool using files. While not
1812 recommended, a pool based on files can be useful for experimental purposes.
1814 .sp
1815 .in +2
1816 .nf
1817 # \fBzpool create tank /path/to/file/a /path/to/file/b\fR
1818 .fi
1819 .in -2
1820 .sp
1822 .LP
1823 \fBExample 5 \fRAdding a Mirror to a ZFS Storage Pool
1824 .sp
1825 .LP
1826 The following command adds two mirrored disks to the pool "\fItank\fR",
1827 assuming the pool is already made up of two-way mirrors. The additional space
1828 is immediately available to any datasets within the pool.
1830 .sp
1831 .in +2
1832 .nf
1833 # \fBzpool add tank mirror c1t0d0 c1t1d0\fR
1834 .fi
1835 .in -2
1836 .sp
1838 .LP
1839 \fBExample 6 \fRListing Available ZFS Storage Pools
1840 .sp
1841 .LP
1842 The following command lists all available pools on the system. In this case,
1843 the pool \fIzion\fR is faulted due to a missing device.
1845 .sp
1846 .LP
1847 The results from this command are similar to the following:
1849 .sp
1850 .in +2
1851 .nf
1852 # \fBzpool list\fR
1853 NAME SIZE ALLOC FREE EXPANDSZ CAP DEDUP HEALTH ALTROOT
1854 rpool 19.9G 8.43G 11.4G - 42% 1.00x ONLINE -
1855 tank 61.5G 20.0G 41.5G - 32% 1.00x ONLINE -
1856 zion - - - - - - FAULTED -
1857 .fi
1858 .in -2
1859 .sp
1861 .LP
1862 \fBExample 7 \fRDestroying a ZFS Storage Pool
1863 .sp
1864 .LP
1865 The following command destroys the pool "\fItank\fR" and any datasets contained
1866 within.
1868 .sp
1869 .in +2
1870 .nf
1871 # \fBzpool destroy -f tank\fR
1872 .fi
1873 .in -2
1874 .sp
1876 .LP
1877 \fBExample 8 \fRExporting a ZFS Storage Pool
1878 .sp
1879 .LP
1880 The following command exports the devices in pool \fItank\fR so that they can
1881 be relocated or later imported.
1883 .sp
1884 .in +2
1885 .nf
1886 # \fBzpool export tank\fR
1887 .fi
1888 .in -2
1889 .sp
1891 .LP
1892 \fBExample 9 \fRImporting a ZFS Storage Pool
1893 .sp
1894 .LP
1895 The following command displays available pools, and then imports the pool
1896 "tank" for use on the system.
1898 .sp
1899 .LP
1900 The results from this command are similar to the following:
1902 .sp
1903 .in +2
1904 .nf
1905 # \fBzpool import\fR
1906 pool: tank
1907 id: 15451357997522795478
1908 state: ONLINE
1909 action: The pool can be imported using its name or numeric identifier.
1910 config:
1912 tank ONLINE
1913 mirror ONLINE
1914 c1t2d0 ONLINE
1915 c1t3d0 ONLINE
1917 # \fBzpool import tank\fR
1918 .fi
1919 .in -2
1920 .sp
1922 .LP
1923 \fBExample 10 \fRUpgrading All ZFS Storage Pools to the Current Version
1924 .sp
1925 .LP
1926 The following command upgrades all ZFS Storage pools to the current version of
1927 the software.
1929 .sp
1930 .in +2
1931 .nf
1932 # \fBzpool upgrade -a\fR
1933 This system is currently running ZFS version 2.
1934 .fi
1935 .in -2
1936 .sp
1938 .LP
1939 \fBExample 11 \fRManaging Hot Spares
1940 .sp
1941 .LP
1942 The following command creates a new pool with an available hot spare:
1944 .sp
1945 .in +2
1946 .nf
1947 # \fBzpool create tank mirror c0t0d0 c0t1d0 spare c0t2d0\fR
1948 .fi
1949 .in -2
1950 .sp
1952 .sp
1953 .LP
1954 If one of the disks were to fail, the pool would be reduced to the degraded
1955 state. The failed device can be replaced using the following command:
1957 .sp
1958 .in +2
1959 .nf
1960 # \fBzpool replace tank c0t0d0 c0t3d0\fR
1961 .fi
1962 .in -2
1963 .sp
1965 .sp
1966 .LP
1967 Once the data has been resilvered, the spare is automatically removed and is
1968 made available should another device fails. The hot spare can be permanently
1969 removed from the pool using the following command:
1971 .sp
1972 .in +2
1973 .nf
1974 # \fBzpool remove tank c0t2d0\fR
1975 .fi
1976 .in -2
1977 .sp
1979 .LP
1980 \fBExample 12 \fRCreating a ZFS Pool with Mirrored Separate Intent Logs
1981 .sp
1982 .LP
1983 The following command creates a ZFS storage pool consisting of two, two-way
1984 mirrors and mirrored log devices:
1986 .sp
1987 .in +2
1988 .nf
1989 # \fBzpool create pool mirror c0d0 c1d0 mirror c2d0 c3d0 log mirror \e
1990 c4d0 c5d0\fR
1991 .fi
1992 .in -2
1993 .sp
1995 .LP
1996 \fBExample 13 \fRAdding Cache Devices to a ZFS Pool
1997 .sp
1998 .LP
1999 The following command adds two disks for use as cache devices to a ZFS storage
2000 pool:
2002 .sp
2003 .in +2
2004 .nf
2005 # \fBzpool add pool cache c2d0 c3d0\fR
2006 .fi
2007 .in -2
2008 .sp
2010 .sp
2011 .LP
2012 Once added, the cache devices gradually fill with content from main memory.
2013 Depending on the size of your cache devices, it could take over an hour for
2014 them to fill. Capacity and reads can be monitored using the \fBiostat\fR option
2015 as follows:
2017 .sp
2018 .in +2
2019 .nf
2020 # \fBzpool iostat -v pool 5\fR
2021 .fi
2022 .in -2
2023 .sp
2025 .LP
2026 \fBExample 14 \fRRemoving a Mirrored Log Device
2027 .sp
2028 .LP
2029 The following command removes the mirrored log device \fBmirror-2\fR.
2031 .sp
2032 .LP
2033 Given this configuration:
2035 .sp
2036 .in +2
2037 .nf
2038 pool: tank
2039 state: ONLINE
2040 scrub: none requested
2041 config:
2043 NAME STATE READ WRITE CKSUM
2044 tank ONLINE 0 0 0
2045 mirror-0 ONLINE 0 0 0
2046 c6t0d0 ONLINE 0 0 0
2047 c6t1d0 ONLINE 0 0 0
2048 mirror-1 ONLINE 0 0 0
2049 c6t2d0 ONLINE 0 0 0
2050 c6t3d0 ONLINE 0 0 0
2051 logs
2052 mirror-2 ONLINE 0 0 0
2053 c4t0d0 ONLINE 0 0 0
2054 c4t1d0 ONLINE 0 0 0
2055 .fi
2056 .in -2
2057 .sp
2059 .sp
2060 .LP
2061 The command to remove the mirrored log \fBmirror-2\fR is:
2063 .sp
2064 .in +2
2065 .nf
2066 # \fBzpool remove tank mirror-2\fR
2067 .fi
2068 .in -2
2069 .sp
2071 .LP
2072 \fBExample 15 \fRDisplaying expanded space on a device
2073 .sp
2074 .LP
2075 The following command dipslays the detailed information for the \fIdata\fR
2076 pool. This pool is comprised of a single \fIraidz\fR vdev where one of its
2077 devices increased its capacity by 1GB. In this example, the pool will not
2078 be able to utilized this extra capacity until all the devices under the
2079 \fIraidz\fR vdev have been expanded.
2081 .sp
2082 .in +2
2083 .nf
2084 # \fBzpool list -v data\fR
2085 NAME SIZE ALLOC FREE EXPANDSZ CAP DEDUP HEALTH ALTROOT
2086 data 17.9G 174K 17.9G - 0% 1.00x ONLINE -
2087 raidz1 17.9G 174K 17.9G -
2088 c4t2d0 - - - 1G
2089 c4t3d0 - - - -
2090 c4t4d0 - - - -
2091 .fi
2092 .in -2
2094 .SH EXIT STATUS
2095 .sp
2096 .LP
2097 The following exit values are returned:
2098 .sp
2099 .ne 2
2100 .na
2101 \fB\fB0\fR\fR
2102 .ad
2103 .RS 5n
2104 Successful completion.
2105 .RE
2107 .sp
2108 .ne 2
2109 .na
2110 \fB\fB1\fR\fR
2111 .ad
2112 .RS 5n
2113 An error occurred.
2114 .RE
2116 .sp
2117 .ne 2
2118 .na
2119 \fB\fB2\fR\fR
2120 .ad
2121 .RS 5n
2122 Invalid command line options were specified.
2123 .RE
2125 .SH ATTRIBUTES
2126 .sp
2127 .LP
2128 See \fBattributes\fR(5) for descriptions of the following attributes:
2129 .sp
2131 .sp
2132 .TS
2133 box;
2134 c | c
2135 l | l .
2136 ATTRIBUTE TYPE ATTRIBUTE VALUE
2137 _
2138 Interface Stability Evolving
2139 .TE
2141 .SH SEE ALSO
2142 .sp
2143 .LP
2144 \fBzfs\fR(1M), \fBzpool-features\fR(5), \fBattributes\fR(5)