1zpool(1M) System Administration Commands zpool(1M)
2
6 zpool - configures ZFS storage pools
7
9 zpool [-?]
10 zpool add [-fn] [-o property=value] pool vdev ...
13 zpool attach [-f] [-o property=value] pool device new_device
16 zpool clear [-F [-n]] pool [device]
19 zpool create [-fn] [-o property=value] ... [-O file-system-property=value]
22 ... [-m mountpoint] [-R root] pool vdev ...
23 zpool destroy [-f] pool
26 zpool detach pool device
29 zpool export [-f] pool ...
32 zpool get "all" | property[,...] pool ...
35 zpool history [-il] [pool] ...
38 zpool import [-d dir] [-D]
41 zpool import [-o mntopts] [-o property=value] ... [-d dir | -c cachefile]
44 [-D] [-f] [-R root] [-F [-n]] -a
45 zpool import [-o mntopts] [-o property=value] ... [-d dir | -c cachefile]
48 [-D] [-f] [-R root] [-F [-n]] pool |id [newpool]
49 zpool iostat [-T u | d ] [-v] [pool] ... [interval[count]]
52 zpool list [-H] [-o property[,...]] [pool] ...
55 zpool offline [-t] pool device ...
58 zpool online pool device ...
61 zpool remove pool device ...
64 zpool replace [-f] pool device [new_device]
67 zpool scrub [-s] pool ...
70 zpool set property=value pool
73 zpool split [-R altroot] [-n] [-o mntopts] [-o property=value] pool
76 newpool [device ...]
77 zpool status [-xv] [pool] ...
80 zpool upgrade
83 zpool upgrade -v
86 zpool upgrade [-V version] -a | pool ...
89
92 The zpool command configures ZFS storage pools. A storage pool is a
93 collection of devices that provides physical storage and data replica‐
94 tion for ZFS datasets.
95 All datasets within a storage pool share the same space. See zfs(1M)
98 for information on managing datasets.
99 Virtual Devices (vdevs)
101 A "virtual device" describes a single device or a collection of devices
102 organized according to certain performance and fault characteristics.
103 The following virtual devices are supported:
104 disk
106 A block device, typically located under /dev/dsk. ZFS can use indi‐
108 vidual slices or partitions, though the recommended mode of opera‐
109 tion is to use whole disks. A disk can be specified by a full path,
110 or it can be a shorthand name (the relative portion of the path
111 under "/dev/dsk"). A whole disk can be specified by omitting the
112 slice or partition designation. For example, "c0t0d0" is equivalent
113 to "/dev/dsk/c0t0d0s2". When given a whole disk, ZFS automatically
114 labels the disk, if necessary.
115 file
118 A regular file. The use of files as a backing store is strongly
120 discouraged. It is designed primarily for experimental purposes, as
121 the fault tolerance of a file is only as good as the file system of
122 which it is a part. A file must be specified by a full path.
123 mirror
126 A mirror of two or more devices. Data is replicated in an identical
128 fashion across all components of a mirror. A mirror with N disks of
129 size X can hold X bytes and can withstand (N-1) devices failing
130 before data integrity is compromised.
131 raidz
134 raidz1
135 raidz2
136 raidz3
137 A variation on RAID-5 that allows for better distribution of parity
139 and eliminates the "RAID-5 write hole" (in which data and parity
140 become inconsistent after a power loss). Data and parity is striped
141 across all disks within a raidz group.
142 A raidz group can have single-, double- , or triple parity, meaning
144 that the raidz group can sustain one, two, or three failures,
145 respectively, without losing any data. The raidz1 vdev type speci‐
146 fies a single-parity raidz group; the raidz2 vdev type specifies a
147 double-parity raidz group; and the raidz3 vdev type specifies a
148 triple-parity raidz group. The raidz vdev type is an alias for
149 raidz1.
150 A raidz group with N disks of size X with P parity disks can hold
152 approximately (N-P)*X bytes and can withstand P device(s) failing
153 before data integrity is compromised. The minimum number of devices
154 in a raidz group is one more than the number of parity disks. The
155 recommended number is between 3 and 9 to help increase performance.
156 spare
159 A special pseudo-vdev which keeps track of available hot spares for
161 a pool. For more information, see the "Hot Spares" section.
162 log
165 A separate-intent log device. If more than one log device is speci‐
167 fied, then writes are load-balanced between devices. Log devices
168 can be mirrored. However, raidz vdev types are not supported for
169 the intent log. For more information, see the "Intent Log" section.
170 cache
173 A device used to cache storage pool data. A cache device cannot be
175 configured as a mirror or raidz group. For more information, see
176 the "Cache Devices" section.
177 Virtual devices cannot be nested, so a mirror or raidz virtual device
181 can only contain files or disks. Mirrors of mirrors (or other combina‐
182 tions) are not allowed.
183 A pool can have any number of virtual devices at the top of the config‐
186 uration (known as "root vdevs"). Data is dynamically distributed across
187 all top-level devices to balance data among devices. As new virtual
188 devices are added, ZFS automatically places data on the newly available
189 devices.
190 Virtual devices are specified one at a time on the command line, sepa‐
193 rated by whitespace. The keywords "mirror" and "raidz" are used to dis‐
194 tinguish where a group ends and another begins. For example, the fol‐
195 lowing creates two root vdevs, each a mirror of two disks:
196 # zpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0
198 Device Failure and Recovery
202 ZFS supports a rich set of mechanisms for handling device failure and
203 data corruption. All metadata and data is checksummed, and ZFS automat‐
204 ically repairs bad data from a good copy when corruption is detected.
205 In order to take advantage of these features, a pool must make use of
208 some form of redundancy, using either mirrored or raidz groups. While
209 ZFS supports running in a non-redundant configuration, where each root
210 vdev is simply a disk or file, this is strongly discouraged. A single
211 case of bit corruption can render some or all of your data unavailable.
212 A pool's health status is described by one of three states: online,
215 degraded, or faulted. An online pool has all devices operating nor‐
216 mally. A degraded pool is one in which one or more devices have failed,
217 but the data is still available due to a redundant configuration. A
218 faulted pool has corrupted metadata, or one or more faulted devices,
219 and insufficient replicas to continue functioning.
220 The health of the top-level vdev, such as mirror or raidz device, is
223 potentially impacted by the state of its associated vdevs, or component
224 devices. A top-level vdev or component device is in one of the follow‐
225 ing states:
226 DEGRADED
228 One or more top-level vdevs is in the degraded state because one or
230 more component devices are offline. Sufficient replicas exist to
231 continue functioning.
232 One or more component devices is in the degraded or faulted state,
234 but sufficient replicas exist to continue functioning. The underly‐
235 ing conditions are as follows:
236 o The number of checksum errors exceeds acceptable levels
238 and the device is degraded as an indication that some‐
239 thing may be wrong. ZFS continues to use the device as
240 necessary.
241 o The number of I/O errors exceeds acceptable levels. The
243 device could not be marked as faulted because there are
244 insufficient replicas to continue functioning.
245 FAULTED
248 One or more top-level vdevs is in the faulted state because one or
250 more component devices are offline. Insufficient replicas exist to
251 continue functioning.
252 One or more component devices is in the faulted state, and insuffi‐
254 cient replicas exist to continue functioning. The underlying condi‐
255 tions are as follows:
256 o The device could be opened, but the contents did not
258 match expected values.
259 o The number of I/O errors exceeds acceptable levels and
261 the device is faulted to prevent further use of the
262 device.
263 OFFLINE
266 The device was explicitly taken offline by the "zpool offline" com‐
268 mand.
269 ONLINE
272 The device is online and functioning.
274 REMOVED
277 The device was physically removed while the system was running.
279 Device removal detection is hardware-dependent and may not be sup‐
280 ported on all platforms.
281 UNAVAIL
284 The device could not be opened. If a pool is imported when a device
286 was unavailable, then the device will be identified by a unique
287 identifier instead of its path since the path was never correct in
288 the first place.
289 If a device is removed and later re-attached to the system, ZFS
293 attempts to put the device online automatically. Device attach detec‐
294 tion is hardware-dependent and might not be supported on all platforms.
295 Hot Spares
297 ZFS allows devices to be associated with pools as "hot spares". These
298 devices are not actively used in the pool, but when an active device
299 fails, it is automatically replaced by a hot spare. To create a pool
300 with hot spares, specify a "spare" vdev with any number of devices. For
301 example,
302 # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0
304 Spares can be shared across multiple pools, and can be added with the
309 "zpool add" command and removed with the "zpool remove" command. Once a
310 spare replacement is initiated, a new "spare" vdev is created within
311 the configuration that will remain there until the original device is
312 replaced. At this point, the hot spare becomes available again if
313 another device fails.
314 If a pool has a shared spare that is currently being used, the pool can
317 not be exported since other pools may use this shared spare, which may
318 lead to potential data corruption.
319 An in-progress spare replacement can be cancelled by detaching the hot
322 spare. If the original faulted device is detached, then the hot spare
323 assumes its place in the configuration, and is removed from the spare
324 list of all active pools.
325 Spares cannot replace log devices.
328 Intent Log
330 The ZFS Intent Log (ZIL) satisfies POSIX requirements for synchronous
331 transactions. For instance, databases often require their transactions
332 to be on stable storage devices when returning from a system call. NFS
333 and other applications can also use fsync() to ensure data stability.
334 By default, the intent log is allocated from blocks within the main
335 pool. However, it might be possible to get better performance using
336 separate intent log devices such as NVRAM or a dedicated disk. For
337 example:
338 # zpool create pool c0d0 c1d0 log c2d0
340 Multiple log devices can also be specified, and they can be mirrored.
345 See the EXAMPLES section for an example of mirroring multiple log
346 devices.
347 Log devices can be added, replaced, attached, detached, and imported
350 and exported as part of the larger pool. Mirrored log devices can be
351 removed by specifying the top-level mirror for the log.
352 Cache Devices
354 Devices can be added to a storage pool as "cache devices." These
355 devices provide an additional layer of caching between main memory and
356 disk. For read-heavy workloads, where the working set size is much
357 larger than what can be cached in main memory, using cache devices
358 allow much more of this working set to be served from low latency
359 media. Using cache devices provides the greatest performance improve‐
360 ment for random read-workloads of mostly static content.
361 To create a pool with cache devices, specify a "cache" vdev with any
364 number of devices. For example:
365 # zpool create pool c0d0 c1d0 cache c2d0 c3d0
367 Cache devices cannot be mirrored or part of a raidz configuration. If a
372 read error is encountered on a cache device, that read I/O is reissued
373 to the original storage pool device, which might be part of a mirrored
374 or raidz configuration.
375 The content of the cache devices is considered volatile, as is the case
378 with other system caches.
379 Processes
381 Each imported pool has an associated process, named zpool-poolname. The
382 threads in this process are the pool's I/O processing threads, which
383 handle the compression, checksumming, and other tasks for all I/O asso‐
384 ciated with the pool. This process exists to provides visibility into
385 the CPU utilization of the system's storage pools. The existence of
386 this process is an unstable interface.
387 Properties
389 Each pool has several properties associated with it. Some properties
390 are read-only statistics while others are configurable and change the
391 behavior of the pool. The following are read-only properties:
392 alloc
394 Amount of storage space within the pool that has been physically
396 allocated.
397 capacity
400 Percentage of pool space used. This property can also be referred
402 to by its shortened column name, "cap".
403 dedupratio
406 The deduplication ratio specified for a pool, expressed as a mul‐
408 tiplier. Deduplication can be turned on by entering the command:
409 # zfs set dedup=on dataset
411 The default value is off.
414 dedupratio is expressed as a single decimal number. For example, a
416 dedupratio value of 1.76 indicates that 1.76 units of data were
417 stored but only 1 unit of disk space was actually consumed.
418 free
421 Number of blocks within the pool that are not allocated.
423 guid
426 A unique identifier for the pool.
428 health
431 The current health of the pool. Health can be "ONLINE", "DEGRADED",
433 "FAULTED", " OFFLINE", "REMOVED", or "UNAVAIL".
434 size
437 Total size of the storage pool.
439 These space usage properties report actual physical space available to
443 the storage pool. The physical space can be different from the total
444 amount of space that any contained datasets can actually use. The
445 amount of space used in a raidz configuration depends on the character‐
446 istics of the data being written. In addition, ZFS reserves some space
447 for internal accounting that the zfs(1M) command takes into account,
448 but the zpool command does not. For non-full pools of a reasonable
449 size, these effects should be invisible. For small pools, or pools that
450 are close to being completely full, these discrepancies may become more
451 noticeable. The following property can be set at creation time:
452 ashift
454 Pool sector size exponent, to the power of 2 (internally referred
456 to as "ashift"). I/O operations will be aligned to the specified
457 size boundaries. Additionally, the minimum (disk) write size will
458 be set to the specified size, so this represents a space vs. per‐
459 formance trade-off. The typical case for setting this property is
460 when performance is important and the underlying disks use 4KiB
461 sectors but report 512B sectors to the OS (for compatibility rea‐
462 sons); in that case, set ashift=12 (which is 1<<12 = 4096). Since
463 most large disks have had 4K sectors since 2011, ZFS defaults to
464 ashift=12 for all disks larger than 512 GB.
465 For optimal performance, the pool sector size should be greater
467 than or equal to the sector size of the underlying disks. Since the
468 property cannot be changed after pool creation, if in a given pool,
469 you ever want to use drives that report 4KiB sectors, you must set
470 ashift=12 at pool creation time.
471 The following property can be set at creation time and import time:
475 altroot
477 Alternate root directory. If set, this directory is prepended to
479 any mount points within the pool. This can be used when examining
480 an unknown pool where the mount points cannot be trusted, or in an
481 alternate boot environment, where the typical paths are not valid.
482 altroot is not a persistent property. It is valid only while the
483 system is up. Setting altroot defaults to using cachefile=none,
484 though this may be overridden using an explicit setting.
485 The following properties can be set at creation time and import time,
489 and later changed with the zpool set command:
490 autoexpand=on | off
492 Controls automatic pool expansion when the underlying LUN is grown.
494 If set to on, the pool will be resized according to the size of the
495 expanded device. If the device is part of a mirror or raidz then
496 all devices within that mirror/raidz group must be expanded before
497 the new space is made available to the pool. The default behavior
498 is off. This property can also be referred to by its shortened col‐
499 umn name, expand.
500 autoreplace=on | off
503 Controls automatic device replacement. If set to "off", device
505 replacement must be initiated by the administrator by using the
506 "zpool replace" command. If set to "on", any new device, found in
507 the same physical location as a device that previously belonged to
508 the pool, is automatically formatted and replaced. The default
509 behavior is "off". This property can also be referred to by its
510 shortened column name, "replace".
511 bootfs=pool/dataset
514 Identifies the default bootable dataset for the root pool. This
516 property is expected to be set mainly by the installation and
517 upgrade programs.
518 cachefile=path | none
521 Controls the location of where the pool configuration is cached.
523 Discovering all pools on system startup requires a cached copy of
524 the configuration data that is stored on the root file system. All
525 pools in this cache are automatically imported when the system
526 boots. Some environments, such as install and clustering, need to
527 cache this information in a different location so that pools are
528 not automatically imported. Setting this property caches the pool
529 configuration in a different location that can later be imported
530 with "zpool import -c". Setting it to the special value "none" cre‐
531 ates a temporary pool that is never cached, and the special value
532 '' (empty string) uses the default location.
533 Multiple pools can share the same cache file. Because the kernel
535 destroys and recreates this file when pools are added and removed,
536 care should be taken when attempting to access this file. When the
537 last pool using a cachefile is exported or destroyed, the file is
538 removed.
539 delegation=on | off
542 Controls whether a non-privileged user is granted access based on
544 the dataset permissions defined on the dataset. See zfs(1M) for
545 more information on ZFS delegated administration.
546 failmode=wait | continue | panic
549 Controls the system behavior in the event of catastrophic pool
551 failure. This condition is typically a result of a loss of connec‐
552 tivity to the underlying storage device(s) or a failure of all
553 devices within the pool. The behavior of such an event is deter‐
554 mined as follows:
555 wait
557 Blocks all I/O access to the pool until the device connectivity
559 is recovered and the errors are cleared. A pool remains in the
560 wait state until the device issue is resolved. This is the
561 default behavior.
562 continue
565 Returns EIO to any new write I/O requests but allows reads to
567 any of the remaining healthy devices. Any write requests that
568 have yet to be committed to disk would be blocked.
569 panic
572 Prints out a message to the console and generates a system
574 crash dump.
575 listsnaps=on | off
579 Controls whether information about snapshots associated with this
581 pool is output when "zfs list" is run without the -t option. The
582 default value is "off".
583 version=version
586 The current on-disk version of the pool. This can be increased, but
588 never decreased. The preferred method of updating pools is with the
589 "zpool upgrade" command, though this property can be used when a
590 specific version is needed for backwards compatibility. This prop‐
591 erty can be any number between 1 and the current version reported
592 by "zpool upgrade -v".
593 Subcommands
596 All subcommands that modify state are logged persistently to the pool
597 in their original form.
598 The zpool command provides subcommands to create and destroy storage
601 pools, add capacity to storage pools, and provide information about the
602 storage pools. The following subcommands are supported:
603 zpool -?
605 Displays a help message.
607 zpool add [-fn] [-o property=value] pool vdev ...
610 Adds the specified virtual devices to the given pool. The vdev
612 specification is described in the "Virtual Devices" section. The
613 behavior of the -f option, and the device checks performed are
614 described in the "zpool create" subcommand.
615 -f
617 Forces use of vdevs, even if they appear in use or specify a
619 conflicting replication level. Not all devices can be overrid‐
620 den in this manner.
621 -n
624 Displays the configuration that would be used without actually
626 adding the vdevs. The actual pool creation can still fail due
627 to insufficient privileges or device sharing.
628 -o property=value
631 Sets the given pool properties. See the "Properties" section
633 for a list of valid properties that can be set. The only prop‐
634 erty supported at the moment is "ashift".
635 Do not add a disk that is currently configured as a quorum device
637 to a zpool. After a disk is in the pool, that disk can then be con‐
638 figured as a quorum device.
639 zpool attach [-f] [-o property=value] pool device new_device
642 Attaches new_device to an existing zpool device. The existing
644 device cannot be part of a raidz configuration. If device is not
645 currently part of a mirrored configuration, device automatically
646 transforms into a two-way mirror of device and new_device. If
647 device is part of a two-way mirror, attaching new_device creates a
648 three-way mirror, and so on. In either case, new_device begins to
649 resilver immediately.
650 -f
652 Forces use of new_device, even if its appears to be in use. Not
654 all devices can be overridden in this manner.
655 -o property=value
658 Sets the given pool properties. See the "Properties" section
660 for a list of valid properties that can be set. The only prop‐
661 erty supported at the moment is "ashift".
662 zpool clear [-F [-n]] pool [device] ...
666 Clears device errors in a pool. If no arguments are specified, all
668 device errors within the pool are cleared. If one or more devices
669 is specified, only those errors associated with the specified
670 device or devices are cleared.
671 -F
673 Initiates recovery mode for an unopenable pool. Attempts to
675 discard the last few transactions in the pool to return it to
676 an openable state. Not all damaged pools can be recovered by
677 using this option. If successful, the data from the discarded
678 transactions is irretrievably lost.
679 -n
682 Used in combination with the -F flag. Check whether discarding
684 transactions would make the pool openable, but do not actually
685 discard any transactions.
686 zpool create [-fn] [-o property=value] ... [-O file-system-prop‐
690 erty=value] ... [-m mountpoint] [-R root] pool vdev ...
691 Creates a new storage pool containing the virtual devices specified
693 on the command line. The pool name must begin with a letter, and
694 can only contain alphanumeric characters as well as underscore
695 ("_"), dash ("-"), and period ("."). The pool names mirror, raidz,
696 spare, and log are reserved, as are names beginning with the pat‐
697 tern c[0-9]. The vdev specification is described in the "Virtual
698 Devices" section.
699 The command verifies that each device specified is accessible and
701 not currently in use by another subsystem. There are some uses,
702 such as being currently mounted, or specified as the dedicated dump
703 device, that prevents a device from ever being used by ZFS. Other
704 uses, such as having a preexisting UFS file system, can be overrid‐
705 den with the -f option.
706 The command also checks that the replication strategy for the pool
708 is consistent. An attempt to combine redundant and non-redundant
709 storage in a single pool, or to mix disks and files, results in an
710 error unless -f is specified. The use of differently sized devices
711 within a single raidz or mirror group is also flagged as an error
712 unless -f is specified.
713 Unless the -R option is specified, the default mount point is
715 "/pool". The mount point must not exist or must be empty, or else
716 the root dataset cannot be mounted. This can be overridden with the
717 -m option.
718 -f
720 Forces use of vdevs, even if they appear in use or specify a
722 conflicting replication level. Not all devices can be overrid‐
723 den in this manner.
724 -n
727 Displays the configuration that would be used without actually
729 creating the pool. The actual pool creation can still fail due
730 to insufficient privileges or device sharing.
731 -o property=value [-o property=value] ...
734 Sets the given pool properties. See the "Properties" section
736 for a list of valid properties that can be set.
737 -O file-system-property=value
740 [-O file-system-property=value] ...
741 Sets the given file system properties in the root file system
743 of the pool. See the "Properties" section of zfs(1M) for a list
744 of valid properties that can be set.
745 -R root
748 Equivalent to "-o cachefile=none,altroot=root"
750 -m mountpoint
753 Sets the mount point for the root dataset. The default mount
755 point is "/pool" or "altroot/pool" if altroot is specified. The
756 mount point must be an absolute path, "legacy", or "none". For
757 more information on dataset mount points, see zfs(1M).
758 zpool destroy [-f] pool
762 Destroys the given pool, freeing up any devices for other use. This
764 command tries to unmount any active datasets before destroying the
765 pool.
766 -f
768 Forces any active datasets contained within the pool to be
770 unmounted.
771 zpool detach pool device
775 Detaches device from a mirror. The operation is refused if there
777 are no other valid replicas of the data.
778 zpool export [-f] pool ...
781 Exports the given pools from the system. All devices are marked as
783 exported, but are still considered in use by other subsystems. The
784 devices can be moved between systems (even those of different endi‐
785 anness) and imported as long as a sufficient number of devices are
786 present.
787 Before exporting the pool, all datasets within the pool are
789 unmounted. A pool can not be exported if it has a shared spare that
790 is currently being used.
791 For pools to be portable, you must give the zpool command whole
793 disks, not just slices, so that ZFS can label the disks with porta‐
794 ble EFI labels. Otherwise, disk drivers on platforms of different
795 endianness will not recognize the disks.
796 -f
798 Forcefully unmount all datasets, using the "unmount -f" com‐
800 mand.
801 This command will forcefully export the pool even if it has a
803 shared spare that is currently being used. This may lead to
804 potential data corruption.
805 zpool get "all" | property[,...] pool ...
809 Retrieves the given list of properties (or all properties if "all"
811 is used) for the specified storage pool(s). These properties are
812 displayed with the following fields:
813 name Name of storage pool
815 property Property name
816 value Property value
817 source Property source, either 'default' or 'local'.
818 See the "Properties" section for more information on the available
821 pool properties.
822 zpool history [-il] [pool] ...
825 Displays the command history of the specified pools or all pools if
827 no pool is specified.
828 -i
830 Displays internally logged ZFS events in addition to user ini‐
832 tiated events.
833 -l
836 Displays log records in long format, which in addition to stan‐
838 dard format includes, the user name, the hostname, and the zone
839 in which the operation was performed.
840 zpool import [-d dir | -c cachefile] [-D]
844 Lists pools available to import. If the -d option is not specified,
846 this command searches for devices in "/dev/dsk". The -d option can
847 be specified multiple times, and all directories are searched. If
848 the device appears to be part of an exported pool, this command
849 displays a summary of the pool with the name of the pool, a numeric
850 identifier, as well as the vdev layout and current health of the
851 device for each device or file. Destroyed pools, pools that were
852 previously destroyed with the "zpool destroy" command, are not
853 listed unless the -D option is specified.
854 The numeric identifier is unique, and can be used instead of the
856 pool name when multiple exported pools of the same name are avail‐
857 able.
858 -c cachefile
860 Reads configuration from the given cachefile that was created
862 with the "cachefile" pool property. This cachefile is used
863 instead of searching for devices.
864 -d dir
867 Searches for devices or files in dir. The -d option can be
869 specified multiple times.
870 -D
873 Lists destroyed pools only.
875 zpool import [-o mntopts] [ -o property=value] ... [-d dir | -c
879 cachefile] [-D] [-f] [-R root] [-F [-n]] -a
880 Imports all pools found in the search directories. Identical to the
882 previous command, except that all pools with a sufficient number of
883 devices available are imported. Destroyed pools, pools that were
884 previously destroyed with the "zpool destroy" command, will not be
885 imported unless the -D option is specified.
886 -o mntopts
888 Comma-separated list of mount options to use when mounting
890 datasets within the pool. See zfs(1M) for a description of
891 dataset properties and mount options.
892 -o property=value
895 Sets the specified property on the imported pool. See the
897 "Properties" section for more information on the available pool
898 properties.
899 -c cachefile
902 Reads configuration from the given cachefile that was created
904 with the "cachefile" pool property. This cachefile is used
905 instead of searching for devices.
906 -d dir
909 Searches for devices or files in dir. The -d option can be
911 specified multiple times. This option is incompatible with the
912 -c option.
913 -D
916 Imports destroyed pools only. The -f option is also required.
918 -f
921 Forces import, even if the pool appears to be potentially
923 active.
924 -F
927 Recovery mode for a non-importable pool. Attempt to return the
929 pool to an importable state by discarding the last few transac‐
930 tions. Not all damaged pools can be recovered by using this
931 option. If successful, the data from the discarded transactions
932 is irretrievably lost. This option is ignored if the pool is
933 importable or already imported.
934 -a
937 Searches for and imports all pools found.
939 -R root
942 Sets the "cachefile" property to "none" and the "altroot" prop‐
944 erty to "root".
945 -n
948 Used with the -F recovery option. Determines whether a non-
950 importable pool can be made importable again, but does not
951 actually perform the pool recovery. For more details about pool
952 recovery mode, see the -F option, above.
953 zpool import [-o mntopts] [ -o property=value] ... [-d dir | -c
957 cachefile] [-D] [-f] [-R root] [-F [-n]] pool | id [newpool]
958 Imports a specific pool. A pool can be identified by its name or
960 the numeric identifier. If newpool is specified, the pool is
961 imported using the name newpool. Otherwise, it is imported with the
962 same name as its exported name.
963 If a device is removed from a system without running "zpool export"
965 first, the device appears as potentially active. It cannot be
966 determined if this was a failed export, or whether the device is
967 really in use from another host. To import a pool in this state,
968 the -f option is required.
969 -o mntopts
971 Comma-separated list of mount options to use when mounting
973 datasets within the pool. See zfs(1M) for a description of
974 dataset properties and mount options.
975 -o property=value
978 Sets the specified property on the imported pool. See the
980 "Properties" section for more information on the available pool
981 properties.
982 -c cachefile
985 Reads configuration from the given cachefile that was created
987 with the "cachefile" pool property. This cachefile is used
988 instead of searching for devices.
989 -d dir
992 Searches for devices or files in dir. The -d option can be
994 specified multiple times. This option is incompatible with the
995 -c option.
996 -D
999 Imports destroyed pool. The -f option is also required.
1001 -f
1004 Forces import, even if the pool appears to be potentially
1006 active.
1007 -F
1010 Recovery mode for a non-importable pool. Attempt to return the
1012 pool to an importable state by discarding the last few transac‐
1013 tions. Not all damaged pools can be recovered by using this
1014 option. If successful, the data from the discarded transactions
1015 is irretrievably lost. This option is ignored if the pool is
1016 importable or already imported.
1017 -R root
1020 Sets the "cachefile" property to "none" and the "altroot" prop‐
1022 erty to "root".
1023 -n
1026 Used with the -F recovery option. Determines whether a non-
1028 importable pool can be made importable again, but does not
1029 actually perform the pool recovery. For more details about pool
1030 recovery mode, see the -F option, above.
1031 zpool iostat [-T u | d] [-v] [pool] ... [interval[count]]
1035 Displays I/O statistics for the given pools. When given an inter‐
1037 val, the statistics are printed every interval seconds until Ctrl-C
1038 is pressed. If no pools are specified, statistics for every pool in
1039 the system is shown. If count is specified, the command exits after
1040 count reports are printed.
1041 -T u | d
1043 Display a time stamp.
1045 Specify u for a printed representation of the internal repre‐
1047 sentation of time. See time(2). Specify d for standard date
1048 format. See date(1).
1049 -v
1052 Verbose statistics. Reports usage statistics for individual
1054 vdevs within the pool, in addition to the pool-wide statistics.
1055 zpool list [-H] [-o props[,...]] [pool] ...
1059 Lists the given pools along with a health status and space usage.
1061 When given no arguments, all pools in the system are listed.
1062 -H
1064 Scripted mode. Do not display headers, and separate fields by a
1066 single tab instead of arbitrary space.
1067 -o props
1070 Comma-separated list of properties to display. See the "Proper‐
1072 ties" section for a list of valid properties. The default list
1073 is name, size, allocated, free, capacity, health, altroot.
1074 zpool offline [-t] pool device ...
1078 Takes the specified physical device offline. While the device is
1080 offline, no attempt is made to read or write to the device.
1081 This command is not applicable to spares or cache devices.
1083 -t
1085 Temporary. Upon reboot, the specified physical device reverts
1087 to its previous state.
1088 zpool online [-e] pool device...
1092 Brings the specified physical device online.
1094 This command is not applicable to spares or cache devices.
1096 -e
1098 Expand the device to use all available space. If the device is
1100 part of a mirror or raidz then all devices must be expanded
1101 before the new space will become available to the pool.
1102 zpool remove pool device ...
1106 Removes the specified device from the pool. This command currently
1108 only supports removing hot spares, cache, and log devices. A mir‐
1109 rored log device can be removed by specifying the top-level mirror
1110 for the log. Non-log devices that are part of a mirrored configura‐
1111 tion can be removed using the zpool detach command. Non-redundant
1112 and raidz devices cannot be removed from a pool.
1113 zpool replace [-f] pool old_device [new_device]
1116 Replaces old_device with new_device. This is equivalent to attach‐
1118 ing new_device, waiting for it to resilver, and then detaching
1119 old_device.
1120 The size of new_device must be greater than or equal to the minimum
1122 size of all the devices in a mirror or raidz configuration.
1123 new_device is required if the pool is not redundant. If new_device
1125 is not specified, it defaults to old_device. This form of replace‐
1126 ment is useful after an existing disk has failed and has been phys‐
1127 ically replaced. In this case, the new disk may have the same
1128 /dev/dsk path as the old device, even though it is actually a dif‐
1129 ferent disk. ZFS recognizes this.
1130 -f
1132 Forces use of new_device, even if its appears to be in use. Not
1134 all devices can be overridden in this manner.
1135 zpool scrub [-s] pool ...
1139 Begins a scrub. The scrub examines all data in the specified pools
1141 to verify that it checksums correctly. For replicated (mirror or
1142 raidz) devices, ZFS automatically repairs any damage discovered
1143 during the scrub. The "zpool status" command reports the progress
1144 of the scrub and summarizes the results of the scrub upon comple‐
1145 tion.
1146 Scrubbing and resilvering are very similar operations. The differ‐
1148 ence is that resilvering only examines data that ZFS knows to be
1149 out of date (for example, when attaching a new device to a mirror
1150 or replacing an existing device), whereas scrubbing examines all
1151 data to discover silent errors due to hardware faults or disk fail‐
1152 ure.
1153 Because scrubbing and resilvering are I/O-intensive operations, ZFS
1155 only allows one at a time. If a scrub is already in progress, the
1156 "zpool scrub" command terminates it and starts a new scrub. If a
1157 resilver is in progress, ZFS does not allow a scrub to be started
1158 until the resilver completes.
1159 -s
1161 Stop scrubbing.
1163 zpool set property=value pool
1167 Sets the given property on the specified pool. See the "Properties"
1169 section for more information on what properties can be set and
1170 acceptable values.
1171 zpool split [-R altroot] [-n] [-o mntopts] [-o property=value] pool
1174 newpool [device ...]
1175 Splits off one disk from each mirrored top-level vdev in a pool and
1177 creates a new pool from the split-off disks. The original pool must
1178 be made up of one or more mirrors and must not be in the process of
1179 resilvering. The split subcommand chooses the last device in each
1180 mirror vdev unless overridden by a device specification on the com‐
1181 mand line.
1182 When using a device argument, split includes the specified
1184 device(s) in a new pool and, should any devices remain unspecified,
1185 assigns the last device in each mirror vdev to that pool, as it
1186 does normally. If you are uncertain about the outcome of a split
1187 command, use the -n ("dry-run") option to ensure your command will
1188 have the effect you intend.
1189 -R altroot
1191 Automatically import the newly created pool after splitting,
1193 using the specified altroot parameter for the new pool's alter‐
1194 nate root. See the altroot description in the "Properties" sec‐
1195 tion, above.
1196 -n
1199 Displays the configuration that would be created without actu‐
1201 ally splitting the pool. The actual pool split could still fail
1202 due to insufficient privileges or device status.
1203 -o mntopts
1206 Comma-separated list of mount options to use when mounting
1208 datasets within the pool. See zfs(1M) for a description of
1209 dataset properties and mount options. Valid only in conjunction
1210 with the -R option.
1211 -o property=value
1214 Sets the specified property on the new pool. See the "Proper‐
1216 ties" section, above, for more information on the available
1217 pool properties.
1218 zpool status [-xv] [pool] ...
1222 Displays the detailed health status for the given pools. If no pool
1224 is specified, then the status of each pool in the system is dis‐
1225 played. For more information on pool and device health, see the
1226 "Device Failure and Recovery" section.
1227 If a scrub or resilver is in progress, this command reports the
1229 percentage done and the estimated time to completion. Both of these
1230 are only approximate, because the amount of data in the pool and
1231 the other workloads on the system can change.
1232 -x
1234 Only display status for pools that are exhibiting errors or are
1236 otherwise unavailable.
1237 -v
1240 Displays verbose data error information, printing out a com‐
1242 plete list of all data errors since the last complete pool
1243 scrub.
1244 zpool upgrade
1248 Displays all pools formatted using a different ZFS on-disk version.
1250 Older versions can continue to be used, but some features may not
1251 be available. These pools can be upgraded using "zpool upgrade -a".
1252 Pools that are formatted with a more recent version are also dis‐
1253 played, although these pools will be inaccessible on the system.
1254 zpool upgrade -v
1257 Displays ZFS versions supported by the current software. The cur‐
1259 rent ZFS versions and all previous supported versions are dis‐
1260 played, along with an explanation of the features provided with
1261 each version.
1262 zpool upgrade [-V version] -a | pool ...
1265 Upgrades the given pool to the latest on-disk version. Once this is
1267 done, the pool will no longer be accessible on systems running
1268 older versions of the software.
1269 -a
1271 Upgrades all pools.
1273 -V version
1276 Upgrade to the specified version. If the -V flag is not speci‐
1278 fied, the pool is upgraded to the most recent version. This
1279 option can only be used to increase the version number, and
1280 only up to the most recent version supported by this software.
1281
1285 Example 1 Creating a RAID-Z Storage Pool
1286 The following command creates a pool with a single raidz root vdev that
1289 consists of six disks.
1290 # zpool create tank raidz c0t0d0 c0t1d0 c0t2d0 c0t3d0 c0t4d0 c0t5d0
1293 Example 2 Creating a Mirrored Storage Pool
1297 The following command creates a pool with two mirrors, where each mir‐
1300 ror contains two disks.
1301 # zpool create tank mirror c0t0d0 c0t1d0 mirror c0t2d0 c0t3d0
1304 Example 3 Creating a ZFS Storage Pool by Using Slices
1308 The following command creates an unmirrored pool using two disk slices.
1311 # zpool create tank /dev/dsk/c0t0d0s1 c0t1d0s4
1314 Example 4 Creating a ZFS Storage Pool by Using Files
1318 The following command creates an unmirrored pool using files. While not
1321 recommended, a pool based on files can be useful for experimental pur‐
1322 poses.
1323 # zpool create tank /path/to/file/a /path/to/file/b
1326 Example 5 Adding a Mirror to a ZFS Storage Pool
1330 The following command adds two mirrored disks to the pool "tank",
1333 assuming the pool is already made up of two-way mirrors. The additional
1334 space is immediately available to any datasets within the pool.
1335 # zpool add tank mirror c1t0d0 c1t1d0
1338 Example 6 Listing Available ZFS Storage Pools
1342 The following command lists all available pools on the system.
1345 # zpool list
1348 NAME SIZE ALLOC FREE CAP DEDUP HEALTH ALTROOT
1349 pool 136G 109M 136G 0% 3.00x ONLINE -
1350 rpool 67.5G 12.6G 54.9G 18% 1.01x ONLINE -
1351 Example 7 Listing All Properties for a Pool
1355 The following command lists all the properties for a pool.
1358 % zpool get all pool
1361 NAME PROPERTY VALUE SOURCE
1362 pool size 136G -
1363 pool capacity 0% -
1364 pool altroot - default
1365 pool health ONLINE -
1366 pool guid 15697759092019394988 default
1367 pool version 21 default
1368 pool bootfs - default
1369 pool delegation on default
1370 pool autoreplace off default
1371 pool cachefile - default
1372 pool failmode wait default
1373 pool listsnapshots off default
1374 pool autoexpand off default
1375 pool dedupratio 3.00x -
1376 pool free 136G -
1377 pool allocated 109M -
1378 Example 8 Destroying a ZFS Storage Pool
1382 The following command destroys the pool "tank" and any datasets con‐
1385 tained within.
1386 # zpool destroy -f tank
1389 Example 9 Exporting a ZFS Storage Pool
1393 The following command exports the devices in pool tank so that they can
1396 be relocated or later imported.
1397 # zpool export tank
1400 Example 10 Importing a ZFS Storage Pool
1404 The following command displays available pools, and then imports the
1407 pool "tank" for use on the system.
1408 The results from this command are similar to the following:
1412 # zpool import
1415 pool: tank
1416 id: 7678868315469843843
1417 state: ONLINE
1418 action: The pool can be imported using its name or numeric identifier.
1419 config:
1420 tank ONLINE
1422 mirror-0 ONLINE
1423 c1t2d0 ONLINE
1424 c1t3d0 ONLINE
1425 # zpool import tank
1427 Example 11 Upgrading All ZFS Storage Pools to the Current Version
1431 The following command upgrades all ZFS Storage pools to the current
1434 version of the software.
1435 # zpool upgrade -a
1438 This system is currently running ZFS pool version 19.
1439 All pools are formatted using this version.
1441 Example 12 Managing Hot Spares
1445 The following command creates a new pool with an available hot spare:
1448 # zpool create tank mirror c0t0d0 c0t1d0 spare c0t2d0
1451 If one of the disks were to fail, the pool would be reduced to the
1456 degraded state. The failed device can be replaced using the following
1457 command:
1458 # zpool replace tank c0t0d0 c0t3d0
1461 Once the data has been resilvered, the spare is automatically removed
1466 and is made available should another device fails. The hot spare can be
1467 permanently removed from the pool using the following command:
1468 # zpool remove tank c0t2d0
1471 Example 13 Creating a ZFS Pool with Mirrored Separate Intent Logs
1475 The following command creates a ZFS storage pool consisting of two,
1478 two-way mirrors and mirrored log devices:
1479 # zpool create pool mirror c0d0 c1d0 mirror c2d0 c3d0 log mirror \
1482 c4d0 c5d0
1483 Example 14 Adding Cache Devices to a ZFS Pool
1487 The following command adds two disks for use as cache devices to a ZFS
1490 storage pool:
1491 # zpool add pool cache c2d0 c3d0
1494 Once added, the cache devices gradually fill with content from main
1499 memory. Depending on the size of your cache devices, it could take over
1500 an hour for them to fill. Capacity and reads can be monitored using the
1501 iostat option as follows:
1502 # zpool iostat -v pool 5
1505 Example 15 Removing a Mirrored Log Device
1509 The following command removes the mirrored log device mirror-2.
1512 Given this configuration:
1516 pool: tank
1519 state: ONLINE
1520 scrub: none requested
1521 config:
1522 NAME STATE READ WRITE CKSUM
1524 tank ONLINE 0 0 0
1525 mirror-0 ONLINE 0 0 0
1526 c6t0d0 ONLINE 0 0 0
1527 c6t1d0 ONLINE 0 0 0
1528 mirror-1 ONLINE 0 0 0
1529 c6t2d0 ONLINE 0 0 0
1530 c6t3d0 ONLINE 0 0 0
1531 logs
1532 mirror-2 ONLINE 0 0 0
1533 c4t0d0 ONLINE 0 0 0
1534 c4t1d0 ONLINE 0 0 0
1535 The command to remove the mirrored log mirror-2 is:
1540 # zpool remove tank mirror-2
1543 Example 16 Recovering a Faulted ZFS Pool
1547 If a pool is faulted but recoverable, a message indicating this state
1550 is provided by zpool status if the pool was cached (see cachefile
1551 above), or as part of the error output from a failed zpool import of
1552 the pool.
1553 Recover a cached pool with the zpool clear command:
1557 # zpool clear -F data
1560 Pool data returned to its state as of Tue Sep 08 13:23:35 2009.
1561 Discarded approximately 29 seconds of transactions.
1562 If the pool configuration was not cached, use zpool import with the
1567 recovery mode flag:
1568 # zpool import -F data
1571 Pool data returned to its state as of Tue Sep 08 13:23:35 2009.
1572 Discarded approximately 29 seconds of transactions.
1573
1577 The following exit values are returned:
1578 0
1580 Successful completion.
1582 1
1585 An error occurred.
1587 2
1590 Invalid command line options were specified.
1592
1595 See attributes(5) for descriptions of the following attributes:
1596 ┌─────────────────────────────┬─────────────────────────────┐
1601 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
1602 ├─────────────────────────────┼─────────────────────────────┤
1603 │Availability │SUNWzfsu │
1604 ├─────────────────────────────┼─────────────────────────────┤
1605 │Interface Stability │Committed │
1606 └─────────────────────────────┴─────────────────────────────┘
1607
1609 zfs(1M), attributes(5)
1610SunOS 5.11 4 Jan 2010 zpool(1M)