2 .\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>.
3 .\" Copyright (c) 2013-2014, Xin Li <delphij@FreeBSD.org>.
4 .\" All Rights Reserved.
6 .\" The contents of this file are subject to the terms of the
7 .\" Common Development and Distribution License (the "License").
8 .\" You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
11 .\" or http://www.opensolaris.org/os/licensing.
12 .\" See the License for the specific language governing permissions
13 .\" and limitations under the License.
15 .\" When distributing Covered Code, include this CDDL HEADER in each
16 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
17 .\" If applicable, add the following below this CDDL HEADER, with the
18 .\" fields enclosed by brackets "[]" replaced with your own identifying
19 .\" information: Portions Copyright [yyyy] [name of copyright owner]
21 .\" Copyright (c) 2010, Sun Microsystems, Inc. All Rights Reserved.
22 .\" Copyright (c) 2011, Justin T. Gibbs <gibbs@FreeBSD.org>
23 .\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org>
24 .\" Copyright (c) 2012, 2017 by Delphix. All Rights Reserved.
25 .\" Copyright 2017 Nexenta Systems, Inc.
26 .\" Copyright (c) 2017 Datto Inc.
35 .Nd configures ZFS storage pools
46 .Ar pool device new_device
59 .Op Fl o Ar property Ns = Ns Ar value
61 .Op Fl O Ar file-system-property Ns = Ns Ar value
63 .Op Fl m Ar mountpoint
81 .Op Fl o Ar field Ns Op , Ns Ar ...
82 .Ar all | property Ns Op , Ns Ar ...
91 .Op Fl d Ar dir | Fl c Ar cachefile
96 .Op Fl o Ar property Ns = Ns Ar value
98 .Op Fl -rewind-to-checkpoint
99 .Op Fl d Ar dir | Fl c Ar cachefile
110 .Op Fl o Ar property Ns = Ns Ar value
112 .Op Fl -rewind-to-checkpoint
113 .Op Fl d Ar dir | Fl c Ar cachefile
130 .Op Fl T Cm d Ns | Ns Cm u
141 .Op Fl o Ar property Ns Op , Ns Ar ...
142 .Op Fl T Cm d Ns | Ns Cm u
145 .Op Ar inverval Op Ar count
179 .Ar property Ns = Ns Ar value pool
185 .Op Fl o Ar property Ns = Ns Ar value
191 .Op Fl T Cm d Ns | Ns Cm u
194 .Op Ar interval Op Ar count
207 storage pools. A storage pool is a collection of devices that provides physical
208 storage and data replication for
212 All datasets within a storage pool share the same space. See
214 for information on managing datasets.
215 .Ss Virtual Devices (vdevs)
219 describes a single device or a collection of devices organized according to
220 certain performance and fault characteristics. The following virtual devices
222 .Bl -tag -width "XXXXXX"
224 A block device, typically located under
227 can use individual slices or partitions, though the recommended mode of
228 operation is to use whole disks. A disk can be specified by a full path to the
231 provider name. When given a whole disk,
233 automatically labels the disk, if necessary.
235 A regular file. The use of files as a backing store is strongly discouraged. It
236 is designed primarily for experimental purposes, as the fault tolerance of a
237 file is only as good the file system of which it is a part. A file must be
238 specified by a full path.
240 A mirror of two or more devices. Data is replicated in an identical fashion
241 across all components of a mirror. A mirror with
247 bytes and can withstand
249 devices failing before data integrity is compromised.
252 .Sy raidz1 raidz2 raidz3 ) .
255 that allows for better distribution of parity and eliminates the
257 write hole (in which data and parity become inconsistent after a power loss).
258 Data and parity is striped across all disks within a
264 group can have single-, double- , or triple parity, meaning that the
266 group can sustain one, two, or three failures, respectively, without
269 type specifies a single-parity
273 type specifies a double-parity
277 type specifies a triple-parity
292 parity disks can hold approximately
297 bytes and can withstand
299 device(s) failing before data integrity is compromised. The minimum number of
302 group is one more than the number of parity disks. The
303 recommended number is between 3 and 9 to help increase performance.
306 .No pseudo- Ns No vdev
307 which keeps track of available hot spares for a pool.
308 For more information, see the
312 A separate-intent log device. If more than one log device is specified, then
313 writes are load-balanced between devices. Log devices can be mirrored. However,
316 types are not supported for the intent log. For more information,
321 A device used to cache storage pool data. A cache device cannot be configured
324 group. For more information, see the
329 Virtual devices cannot be nested, so a mirror or
331 virtual device can only
332 contain files or disks. Mirrors of mirrors (or other combinations) are not
335 A pool can have any number of virtual devices at the top of the configuration
339 Data is dynamically distributed across all top-level devices to balance data
340 among devices. As new virtual devices are added,
342 automatically places data on the newly available devices.
344 Virtual devices are specified one at a time on the command line, separated by
345 whitespace. The keywords
349 are used to distinguish where a group ends and another begins. For example, the
350 following creates two root
352 each a mirror of two disks:
353 .Bd -literal -offset 2n
354 .Li # Ic zpool create mypool mirror da0 da1 mirror da2 da3
356 .Ss Device Failure and Recovery
358 supports a rich set of mechanisms for handling device failure and data
359 corruption. All metadata and data is checksummed, and
361 automatically repairs bad data from a good copy when corruption is detected.
363 In order to take advantage of these features, a pool must make use of some form
364 of redundancy, using either mirrored or
368 supports running in a non-redundant configuration, where each root
370 is simply a disk or file, this is strongly discouraged. A single case of bit
371 corruption can render some or all of your data unavailable.
373 A pool's health status is described by one of three states: online, degraded,
374 or faulted. An online pool has all devices operating normally. A degraded pool
375 is one in which one or more devices have failed, but the data is still
376 available due to a redundant configuration. A faulted pool has corrupted
377 metadata, or one or more faulted devices, and insufficient replicas to continue
380 The health of the top-level
385 potentially impacted by the state of its associated
387 or component devices. A top-level
389 or component device is in one of the following states:
390 .Bl -tag -width "DEGRADED"
392 One or more top-level
394 is in the degraded state because one or more
395 component devices are offline. Sufficient replicas exist to continue
398 One or more component devices is in the degraded or faulted state, but
399 sufficient replicas exist to continue functioning. The underlying conditions
401 .Bl -bullet -offset 2n
403 The number of checksum errors exceeds acceptable levels and the device is
404 degraded as an indication that something may be wrong.
406 continues to use the device as necessary.
410 errors exceeds acceptable levels. The device could not be
411 marked as faulted because there are insufficient replicas to continue
415 One or more top-level
417 is in the faulted state because one or more
418 component devices are offline. Insufficient replicas exist to continue
421 One or more component devices is in the faulted state, and insufficient
422 replicas exist to continue functioning. The underlying conditions are as
424 .Bl -bullet -offset 2n
426 The device could be opened, but the contents did not match expected values.
430 errors exceeds acceptable levels and the device is faulted to
431 prevent further use of the device.
434 The device was explicitly taken offline by the
438 The device is online and functioning.
440 The device was physically removed while the system was running. Device removal
441 detection is hardware-dependent and may not be supported on all platforms.
443 The device could not be opened. If a pool is imported when a device was
444 unavailable, then the device will be identified by a unique identifier instead
445 of its path since the path was never correct in the first place.
448 If a device is removed and later reattached to the system,
450 attempts to put the device online automatically. Device attach detection is
451 hardware-dependent and might not be supported on all platforms.
454 allows devices to be associated with pools as
456 These devices are not actively used in the pool, but when an active device
457 fails, it is automatically replaced by a hot spare. To create a pool with hot
461 with any number of devices. For example,
462 .Bd -literal -offset 2n
463 .Li # Ic zpool create pool mirror da0 da1 spare da2 da3
466 Spares can be shared across multiple pools, and can be added with the
468 command and removed with the
470 command. Once a spare replacement is initiated, a new "spare"
473 within the configuration that will remain there until the original device is
474 replaced. At this point, the hot spare becomes available again if another
477 If a pool has a shared spare that is currently being used, the pool can not be
478 exported since other pools may use this shared spare, which may lead to
479 potential data corruption.
481 An in-progress spare replacement can be cancelled by detaching the hot spare.
482 If the original faulted device is detached, then the hot spare assumes its
483 place in the configuration, and is removed from the spare list of all active
486 Spares cannot replace log devices.
488 This feature requires a userland helper.
492 It must be manually enabled by adding
493 .Va zfsd_enable="YES"
503 requirements for synchronous transactions. For instance, databases often
504 require their transactions to be on stable storage devices when returning from
507 and other applications can also use
509 to ensure data stability. By default, the intent log is allocated from blocks
510 within the main pool. However, it might be possible to get better performance
511 using separate intent log devices such as
513 or a dedicated disk. For example:
514 .Bd -literal -offset 2n
515 .Li # Ic zpool create pool da0 da1 log da2
518 Multiple log devices can also be specified, and they can be mirrored. See the
520 section for an example of mirroring multiple log devices.
522 Log devices can be added, replaced, attached, detached, imported and exported
523 as part of the larger pool.
524 Mirrored devices can be removed by specifying the top-level mirror vdev.
526 Devices can be added to a storage pool as "cache devices." These devices
527 provide an additional layer of caching between main memory and disk. For
528 read-heavy workloads, where the working set size is much larger than what can
529 be cached in main memory, using cache devices allow much more of this working
530 set to be served from low latency media. Using cache devices provides the
531 greatest performance improvement for random read-workloads of mostly static
534 To create a pool with cache devices, specify a "cache"
536 with any number of devices. For example:
537 .Bd -literal -offset 2n
538 .Li # Ic zpool create pool da0 da1 cache da2 da3
541 Cache devices cannot be mirrored or part of a
543 configuration. If a read
544 error is encountered on a cache device, that read
546 is reissued to the original storage pool device, which might be part of a
551 The content of the cache devices is considered volatile, as is the case with
554 Before starting critical procedures that include destructive actions (e.g
556 ), an administrator can checkpoint the pool's state and in the case of a
557 mistake or failure, rewind the entire pool back to the checkpoint.
558 Otherwise, the checkpoint can be discarded when the procedure has completed
561 A pool checkpoint can be thought of as a pool-wide snapshot and should be used
562 with care as it contains every part of the pool's state, from properties to vdev
564 Thus, while a pool has a checkpoint certain operations are not allowed.
565 Specifically, vdev removal/attach/detach, mirror splitting, and
566 changing the pool's guid.
567 Adding a new vdev is supported but in the case of a rewind it will have to be
569 Finally, users of this feature should keep in mind that scrubs in a pool that
570 has a checkpoint do not repair checkpointed data.
572 To create a checkpoint for a pool:
574 # zpool checkpoint pool
577 To later rewind to its checkpointed state, you need to first export it and
578 then rewind it during import:
581 # zpool import --rewind-to-checkpoint pool
584 To discard the checkpoint from a pool:
586 # zpool checkpoint -d pool
589 Dataset reservations (controlled by the
593 zfs properties) may be unenforceable while a checkpoint exists, because the
594 checkpoint is allowed to consume the dataset's reservation.
595 Finally, data that is part of the checkpoint but has been freed in the
596 current state of the pool won't be scanned during a scrub.
598 Each pool has several properties associated with it. Some properties are
599 read-only statistics while others are configurable and change the behavior of
600 the pool. The following are read-only properties:
601 .Bl -tag -width "dedupratio"
603 Amount of storage space within the pool that has been physically allocated.
605 Percentage of pool space used. This property can also be referred to by its
606 shortened column name, "cap".
608 The deduplication ratio specified for a pool, expressed as a multiplier.
611 value of 1.76 indicates that 1.76 units of data were stored but only 1 unit of disk space was actually consumed. See
613 for a description of the deduplication feature.
615 Amount of uninitialized space within the pool or device that can be used to
616 increase the total capacity of the pool.
617 Uninitialized space consists of
618 any space on an EFI labeled vdev which has not been brought online
619 .Pq i.e. zpool online -e .
620 This space occurs when a LUN is dynamically expanded.
622 The amount of fragmentation in the pool.
624 Number of blocks within the pool that are not allocated.
626 After a file system or snapshot is destroyed, the space it was using is
627 returned to the pool asynchronously.
629 is the amount of space remaining to be reclaimed.
636 A unique identifier for the pool.
638 The current health of the pool. Health can be
647 Total size of the storage pool.
648 .It Sy unsupported@ Ns Ar feature_guid
649 Information about unsupported features that are enabled on the pool.
654 Amount of storage space used within the pool.
657 The space usage properties report actual physical space available to the
658 storage pool. The physical space can be different from the total amount of
659 space that any contained datasets can actually use. The amount of space used in
662 configuration depends on the characteristics of the data being written.
665 reserves some space for internal accounting that the
667 command takes into account, but the
669 command does not. For non-full pools of a reasonable size, these effects should
670 be invisible. For small pools, or pools that are close to being completely
671 full, these discrepancies may become more noticeable.
673 The following property can be set at creation time and import time:
676 Alternate root directory. If set, this directory is prepended to any mount
677 points within the pool. This can be used when examining an unknown pool where
678 the mount points cannot be trusted, or in an alternate boot environment, where
679 the typical paths are not valid.
681 is not a persistent property. It is valid only while the system is up.
686 though this may be overridden using an explicit setting.
689 The following property can only be set at import time:
691 .It Sy readonly Ns = Ns Cm on No | Cm off
694 pool will be imported in read-only mode with the following restrictions:
695 .Bl -bullet -offset 2n
697 Synchronous data in the intent log will not be accessible
699 Properties of the pool can not be changed
701 Datasets of this pool can only be mounted read-only
703 To write to a read-only pool, a export and import of the pool is required.
706 This property can also be referred to by its shortened column name,
710 The following properties can be set at creation time and import time, and later
715 .It Sy autoexpand Ns = Ns Cm on No | Cm off
716 Controls automatic pool expansion when the underlying LUN is grown. If set to
718 the pool will be resized according to the size of the expanded
719 device. If the device is part of a mirror or
721 then all devices within that
722 .No mirror/ Ns No raidz
723 group must be expanded before the new space is made available to
724 the pool. The default behavior is
726 This property can also be referred to by its shortened column name,
728 .It Sy autoreplace Ns = Ns Cm on No | Cm off
729 Controls automatic device replacement. If set to
731 device replacement must be initiated by the administrator by using the
735 any new device, found in the same
736 physical location as a device that previously belonged to the pool, is
737 automatically formatted and replaced. The default behavior is
739 This property can also be referred to by its shortened column name, "replace".
740 .It Sy bootfs Ns = Ns Ar pool Ns / Ns Ar dataset
741 Identifies the default bootable dataset for the root pool. This property is
742 expected to be set mainly by the installation and upgrade programs.
743 .It Sy cachefile Ns = Ns Ar path No | Cm none
744 Controls the location of where the pool configuration is cached. Discovering
745 all pools on system startup requires a cached copy of the configuration data
746 that is stored on the root file system. All pools in this cache are
747 automatically imported when the system boots. Some environments, such as
748 install and clustering, need to cache this information in a different location
749 so that pools are not automatically imported. Setting this property caches the
750 pool configuration in a different location that can later be imported with
751 .Qq Nm Cm import Fl c .
752 Setting it to the special value
754 creates a temporary pool that is never cached, and the special value
756 (empty string) uses the default location.
757 .It Sy comment Ns = Ns Ar text
758 A text string consisting of printable ASCII characters that will be stored
759 such that it is available even if the pool becomes faulted.
760 An administrator can provide additional information about a pool using this
762 .It Sy dedupditto Ns = Ns Ar number
763 Threshold for the number of block ditto copies. If the reference count for a
764 deduplicated block increases above this number, a new ditto copy of this block
765 is automatically stored. Default setting is
767 which causes no ditto copies to be created for deduplicated blocks.
768 The miniumum legal nonzero setting is 100.
769 .It Sy delegation Ns = Ns Cm on No | Cm off
770 Controls whether a non-privileged user is granted access based on the dataset
771 permissions defined on the dataset. See
773 for more information on
775 delegated administration.
776 .It Sy failmode Ns = Ns Cm wait No | Cm continue No | Cm panic
777 Controls the system behavior in the event of catastrophic pool failure. This
778 condition is typically a result of a loss of connectivity to the underlying
779 storage device(s) or a failure of all devices within the pool. The behavior of
780 such an event is determined as follows:
781 .Bl -tag -width indent
785 access until the device connectivity is recovered and the errors are cleared.
786 This is the default behavior.
792 requests but allows reads to any of the remaining healthy devices. Any write
793 requests that have yet to be committed to disk would be blocked.
795 Prints out a message to the console and generates a system crash dump.
797 .It Sy feature@ Ns Ar feature_name Ns = Ns Sy enabled
798 The value of this property is the current state of
800 The only valid value when setting this property is
804 to the enabled state.
807 for details on feature states.
808 .It Sy listsnaps Ns = Ns Cm on No | Cm off
809 Controls whether information about snapshots associated with this pool is
814 option. The default value is
816 .It Sy version Ns = Ns Ar version
817 The current on-disk version of the pool. This can be increased, but never
818 decreased. The preferred method of updating pools is with the
820 command, though this property can be used when a specific version is needed
821 for backwards compatibility.
822 Once feature flags is enabled on a pool this property will no longer have a
826 All subcommands that modify state are logged persistently to the pool in their
831 command provides subcommands to create and destroy storage pools, add capacity
832 to storage pools, and provide information about the storage pools. The following
833 subcommands are supported:
840 Displays a help message.
848 Adds the specified virtual devices to the given pool. The
850 specification is described in the
851 .Qq Sx Virtual Devices
852 section. The behavior of the
854 option, and the device checks performed are described in the
857 .Bl -tag -width indent
861 even if they appear in use or specify a conflicting replication level.
862 Not all devices can be overridden in this manner.
864 Displays the configuration that would be used without actually adding the
866 The actual pool creation can still fail due to insufficient privileges or device
869 Do not add a disk that is currently configured as a quorum device to a zpool.
870 After a disk is in the pool, that disk can then be configured as a quorum
877 .Ar pool device new_device
884 device. The existing device cannot be part of a
888 is not currently part of a mirrored configuration,
890 automatically transforms into a two-way mirror of
891 .Ar device No and Ar new_device .
894 is part of a two-way mirror, attaching
896 creates a three-way mirror, and so on. In either case,
898 begins to resilver immediately.
899 .Bl -tag -width indent
903 even if its appears to be in use. Not all devices can be overridden in this
912 Checkpoints the current state of
914 , which can be later restored by
915 .Nm zpool Cm import --rewind-to-checkpoint .
916 The existence of a checkpoint in a pool prohibits the following
925 In addition, it may break reservation boundaries if the pool lacks free
929 command indicates the existence of a checkpoint or the progress of discarding a
930 checkpoint from a pool.
933 command reports how much space the checkpoint takes from the pool.
936 Discards an existing checkpoint from
947 Clears device errors in a pool. If no arguments are specified, all device
948 errors within the pool are cleared. If one or more devices is specified, only
949 those errors associated with the specified device or devices are cleared.
950 .Bl -tag -width indent
952 Initiates recovery mode for an unopenable pool. Attempts to discard the last
953 few transactions in the pool to return it to an openable state. Not all damaged
954 pools can be recovered by using this option. If successful, the data from the
955 discarded transactions is irretrievably lost.
957 Used in combination with the
959 flag. Check whether discarding transactions would make the pool openable, but
960 do not actually discard any transactions.
966 .Op Fl o Ar property Ns = Ns Ar value
968 .Op Fl O Ar file-system-property Ns = Ns Ar value
970 .Op Fl m Ar mountpoint
976 Creates a new storage pool containing the virtual devices specified on the
977 command line. The pool name must begin with a letter, and can only contain
978 alphanumeric characters as well as underscore ("_"), dash ("-"), and period
979 ("."). The pool names "mirror", "raidz", "spare" and "log" are reserved, as are
980 names beginning with the pattern "c[0-9]". The
982 specification is described in the
983 .Qq Sx Virtual Devices
986 The command verifies that each device specified is accessible and not currently
987 in use by another subsystem. There are some uses, such as being currently
988 mounted, or specified as the dedicated dump device, that prevents a device from
991 Other uses, such as having a preexisting
993 file system, can be overridden with the
997 The command also checks that the replication strategy for the pool is
998 consistent. An attempt to combine redundant and non-redundant storage in a
999 single pool, or to mix disks and files, results in an error unless
1001 is specified. The use of differently sized devices within a single
1003 or mirror group is also flagged as an error unless
1009 option is specified, the default mount point is
1011 The mount point must not exist or must be empty, or else the
1012 root dataset cannot be mounted. This can be overridden with the
1016 By default all supported features are enabled on the new pool unless the
1018 option is specified.
1019 .Bl -tag -width indent
1023 even if they appear in use or specify a conflicting replication level.
1024 Not all devices can be overridden in this manner.
1026 Displays the configuration that would be used without actually creating the
1027 pool. The actual pool creation can still fail due to insufficient privileges or
1030 Do not enable any features on the new pool.
1031 Individual features can be enabled by setting their corresponding properties
1038 .Xr zpool-features 7
1039 for details about feature properties.
1041 .Fl o Ar property Ns = Ns Ar value
1042 .Op Fl o Ar property Ns = Ns Ar value
1045 Sets the given pool properties. See the
1047 section for a list of valid properties that can be set.
1050 .Ar file-system-property Ns = Ns Ar value
1051 .Op Fl O Ar file-system-property Ns = Ns Ar value
1054 Sets the given file system properties in the root file system of the pool. See
1055 .Xr zfs 8 Properties
1056 for a list of valid properties that
1060 .Qq Fl o Cm cachefile=none,altroot= Ns Pa root
1061 .It Fl m Ar mountpoint
1062 Sets the mount point for the root dataset. The default mount point is
1065 .Qq Cm altroot Ns Pa /pool
1068 is specified. The mount point must be an absolute path,
1072 For more information on dataset mount points, see
1074 .It Fl t Ar tempname
1075 Sets the in-core pool name to
1077 while the on-disk name will be the name specified as the pool name
1079 This will set the default
1083 This is intended to handle name space collisions when creating pools
1084 for other systems, such as virtual machines or physical machines
1085 whose pools live on network block devices.
1094 Destroys the given pool, freeing up any devices for other use. This command
1095 tries to unmount any active datasets before destroying the pool.
1096 .Bl -tag -width indent
1098 Forces any active datasets contained within the pool to be unmounted.
1108 from a mirror. The operation is refused if there are no other valid replicas
1117 Exports the given pools from the system. All devices are marked as exported,
1118 but are still considered in use by other subsystems. The devices can be moved
1119 between systems (even those of different endianness) and imported as long as a
1120 sufficient number of devices are present.
1122 Before exporting the pool, all datasets within the pool are unmounted. A pool
1123 can not be exported if it has a shared spare that is currently being used.
1125 For pools to be portable, you must give the
1127 command whole disks, not just slices, so that
1129 can label the disks with portable
1131 labels. Otherwise, disk drivers on platforms of different endianness will not
1132 recognize the disks.
1133 .Bl -tag -width indent
1135 Forcefully unmount all datasets, using the
1139 This command will forcefully export the pool even if it has a shared spare that
1140 is currently being used. This may lead to potential data corruption.
1146 .Op Fl o Ar field Ns Op , Ns Ar ...
1147 .Ar all | property Ns Op , Ns Ar ...
1151 Retrieves the given list of properties (or all properties if
1153 is used) for the specified storage pool(s). These properties are displayed with
1154 the following fields:
1155 .Bl -column -offset indent "property"
1156 .It name Ta Name of storage pool
1157 .It property Ta Property name
1158 .It value Ta Property value
1159 .It source Ta Property source, either 'default' or 'local'.
1164 section for more information on the available pool properties.
1166 Scripted mode. Do not display headers, and separate fields by a single tab
1167 instead of arbitrary space.
1169 Display numbers in parsable (exact) values.
1171 A comma-separated list of columns to display.
1173 .Sy property Ns , Ns
1176 is the default value.
1185 Displays the command history of the specified pools or all pools if no pool is
1187 .Bl -tag -width indent
1189 Displays internally logged
1191 events in addition to user initiated events.
1193 Displays log records in long format, which in addition to standard format
1194 includes, the user name, the hostname, and the zone in which the operation was
1200 .Op Fl d Ar dir | Fl c Ar cachefile
1204 Lists pools available to import. If the
1206 option is not specified, this command searches for devices in
1210 option can be specified multiple times, and all directories are searched. If
1211 the device appears to be part of an exported pool, this command displays a
1212 summary of the pool with the name of the pool, a numeric identifier, as well as
1215 layout and current health of the device for each device or file.
1216 Destroyed pools, pools that were previously destroyed with the
1218 command, are not listed unless the
1220 option is specified.
1222 The numeric identifier is unique, and can be used instead of the pool name when
1223 multiple exported pools of the same name are available.
1224 .Bl -tag -width indent
1225 .It Fl c Ar cachefile
1226 Reads configuration from the given
1228 that was created with the
1232 is used instead of searching for devices.
1234 Searches for devices or files in
1238 option can be specified multiple times.
1240 Lists destroyed pools only.
1246 .Op Fl o Ar property Ns = Ns Ar value
1248 .Op Fl d Ar dir | Fl c Ar cachefile
1258 Imports all pools found in the search directories. Identical to the previous
1259 command, except that all pools with a sufficient number of devices available
1260 are imported. Destroyed pools, pools that were previously destroyed with the
1262 command, will not be imported unless the
1264 option is specified.
1265 .Bl -tag -width indent
1267 Comma-separated list of mount options to use when mounting datasets within the
1270 for a description of dataset properties and mount options.
1271 .It Fl o Ar property Ns = Ns Ar value
1272 Sets the specified property on the imported pool. See the
1274 section for more information on the available pool properties.
1275 .It Fl c Ar cachefile
1276 Reads configuration from the given
1278 that was created with the
1282 is used instead of searching for devices.
1284 Searches for devices or files in
1288 option can be specified multiple times. This option is incompatible with the
1292 Imports destroyed pools only. The
1294 option is also required.
1296 Forces import, even if the pool appears to be potentially active.
1298 Allows a pool to import when there is a missing log device. Recent transactions
1299 can be lost because the log device will be discarded.
1301 Import the pool without mounting any file systems.
1312 Recovery mode for a non-importable pool. Attempt to return the pool to an
1313 importable state by discarding the last few transactions. Not all damaged pools
1314 can be recovered by using this option. If successful, the data from the
1315 discarded transactions is irretrievably lost. This option is ignored if the
1316 pool is importable or already imported.
1320 recovery option. Determines whether a non-importable pool can be made
1321 importable again, but does not actually perform the pool recovery. For more
1322 details about pool recovery mode, see the
1326 Searches for and imports all pools found.
1332 .Op Fl o Ar property Ns = Ns Ar value
1334 .Op Fl d Ar dir | Fl c Ar cachefile
1346 Imports a specific pool. A pool can be identified by its name or the numeric
1349 is specified, the pool is imported using the name
1351 Otherwise, it is imported with the same name as its exported name.
1353 If a device is removed from a system without running
1355 first, the device appears as potentially active. It cannot be determined if
1356 this was a failed export, or whether the device is really in use from another
1357 host. To import a pool in this state, the
1360 .Bl -tag -width indent
1362 Comma-separated list of mount options to use when mounting datasets within the
1365 for a description of dataset properties and mount options.
1366 .It Fl o Ar property Ns = Ns Ar value
1367 Sets the specified property on the imported pool. See the
1369 section for more information on the available pool properties.
1370 .It Fl c Ar cachefile
1371 Reads configuration from the given
1373 that was created with the
1377 is used instead of searching for devices.
1379 Searches for devices or files in
1383 option can be specified multiple times. This option is incompatible with the
1387 Imports destroyed pools only. The
1389 option is also required.
1391 Forces import, even if the pool appears to be potentially active.
1393 Allows a pool to import when there is a missing log device. Recent transactions
1394 can be lost because the log device will be discarded.
1396 Import the pool without mounting any file systems.
1399 .Qq Fl o Cm cachefile=none,altroot= Ns Pa root
1406 Temporary pool names last until export.
1407 Ensures that the original pool name will be used in all label updates and
1408 therefore is retained upon export.
1413 when not explicitly specified.
1415 Recovery mode for a non-importable pool. Attempt to return the pool to an
1416 importable state by discarding the last few transactions. Not all damaged pools
1417 can be recovered by using this option. If successful, the data from the
1418 discarded transactions is irretrievably lost. This option is ignored if the
1419 pool is importable or already imported.
1423 recovery option. Determines whether a non-importable pool can be made
1424 importable again, but does not actually perform the pool recovery. For more
1425 details about pool recovery mode, see the
1428 .It Fl -rewind-to-checkpoint
1429 Rewinds pool to the checkpointed state.
1430 Once the pool is imported with this flag there is no way to undo the rewind.
1431 All changes and data that were written after the checkpoint are lost!
1432 The only exception is when the
1434 mounting option is enabled.
1435 In this case, the checkpointed state of the pool is opened and an
1436 administrator can see how the pool would look like if they were
1444 .Op Ar device Ns ...
1446 Begins initializing by writing to all unallocated regions on the specified
1447 devices, or all eligible devices in the pool if no individual devices are
1449 Only leaf data or log devices may be initialized.
1452 Cancel initializing on the specified devices, or all eligible devices if none
1454 If one or more target devices are invalid or are not currently being
1455 initialized, the command will fail and no cancellation will occur on any device.
1457 Suspend initializing on the specified devices, or all eligible devices if none
1459 If one or more target devices are invalid or are not currently being
1460 initialized, the command will fail and no suspension will occur on any device.
1461 Initializing can then be resumed by running
1462 .Nm zpool Cm initialize
1463 with no flags on the relevant target devices.
1468 .Op Fl T Cm d Ns | Ns Cm u
1472 .Op Ar interval Op Ar count
1477 statistics for the given pools. When given an interval, the statistics are
1484 are specified, statistics for every pool in the system is shown. If
1486 is specified, the command exits after
1488 reports are printed.
1489 .Bl -tag -width indent
1490 .It Fl T Cm d Ns | Ns Cm u
1495 for standard date format. See
1500 .Pq equals Qq Ic date +%s .
1502 Verbose statistics. Reports usage statistics for individual
1504 within the pool, in addition to the pool-wide statistics.
1515 label information from the specified
1519 must not be part of an active pool configuration.
1520 .Bl -tag -width indent
1522 Treat exported or foreign devices as inactive.
1528 .Op Fl o Ar property Ns Op , Ns Ar ...
1529 .Op Fl T Cm d Ns | Ns Cm u
1532 .Op Ar inverval Op Ar count
1535 Lists the given pools along with a health status and space usage. If no
1537 are specified, all pools in the system are listed.
1539 When given an interval, the output is printed every
1545 is specified, the command exits after
1547 reports are printed.
1548 .Bl -tag -width indent
1549 .It Fl T Cm d Ns | Ns Cm u
1554 for standard date format. See
1559 .Pq equals Qq Ic date +%s .
1561 Scripted mode. Do not display headers, and separate fields by a single tab
1562 instead of arbitrary space.
1564 Display numbers in parsable (exact) values.
1566 Verbose statistics. Reports usage statistics for individual
1569 the pool, in addition to the pool-wide statistics.
1570 .It Fl o Ar property Ns Op , Ns Ar ...
1571 Comma-separated list of properties to display. See the
1573 section for a list of valid properties. The default list is
1585 .It Fl T Cm d Ns | Ns Cm u
1590 for standard date format. See
1595 .Pq equals Qq Ic date +%s .
1604 Takes the specified physical device offline. While the
1606 is offline, no attempt is made to read or write to the device.
1607 .Bl -tag -width indent
1609 Temporary. Upon reboot, the specified physical device reverts to its previous
1619 Brings the specified physical device online.
1621 This command is not applicable to spares or cache devices.
1622 .Bl -tag -width indent
1624 Expand the device to use all available space. If the device is part of a mirror
1627 then all devices must be expanded before the new space will become
1628 available to the pool.
1636 Generates a new unique identifier for the pool. You must ensure that all
1637 devices in this pool are online and healthy before performing this action.
1645 Removes the specified device from the pool.
1646 This command currently only supports removing hot spares, cache, log
1647 devices and mirrored top-level vdevs (mirror of leaf devices); but not raidz.
1649 Removing a top-level vdev reduces the total amount of space in the storage pool.
1650 The specified device will be evacuated by copying all allocated space from it to
1651 the other devices in the pool.
1654 command initiates the removal and returns, while the evacuation continues in
1656 The removal progress can be monitored with
1657 .Nm zpool Cm status.
1658 This feature must be enabled to be used, see
1659 .Xr zpool-features 5
1661 A mirrored top-level device (log or data) can be removed by specifying the
1662 top-level mirror for the same.
1663 Non-log devices or data devices that are part of a mirrored configuration can
1664 be removed using the
1669 Do not actually perform the removal ("no-op").
1670 Instead, print the estimated amount of memory that will be used by the
1671 mapping table after the removal completes.
1672 This is nonzero only for top-level vdevs.
1676 Used in conjunction with the
1678 flag, displays numbers as parsable (exact) values.
1687 Stops and cancels an in-progress removal of a top-level vdev.
1694 Reopen all the vdevs associated with the pool.
1707 This is equivalent to attaching
1709 waiting for it to resilver, and then detaching
1714 must be greater than or equal to the minimum size
1715 of all the devices in a mirror or
1720 is required if the pool is not redundant. If
1722 is not specified, it defaults to
1724 This form of replacement is useful after an existing disk has failed and has
1725 been physically replaced. In this case, the new disk may have the same
1727 path as the old device, even though it is actually a different disk.
1730 .Bl -tag -width indent
1734 even if its appears to be in use. Not all devices can be overridden in this
1744 Begins a scrub or resumes a paused scrub.
1745 The scrub examines all data in the specified pools to verify that it checksums
1749 devices, ZFS automatically repairs any damage discovered during the scrub.
1752 command reports the progress of the scrub and summarizes the results of the
1753 scrub upon completion.
1755 Scrubbing and resilvering are very similar operations.
1756 The difference is that resilvering only examines data that ZFS knows to be out
1759 for example, when attaching a new device to a mirror or replacing an existing
1762 whereas scrubbing examines all data to discover silent errors due to hardware
1763 faults or disk failure.
1765 Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows
1767 If a scrub is paused, the
1770 If a resilver is in progress, ZFS does not allow a scrub to be started until the
1779 Scrub pause state and progress are periodically synced to disk.
1780 If the system is restarted or pool is exported during a paused scrub,
1781 even after import, scrub will remain paused until it is resumed.
1782 Once resumed the scrub will pick up from the place where it was last
1783 checkpointed to disk.
1784 To resume a paused scrub issue
1791 .Ar property Ns = Ns Ar value pool
1794 Sets the given property on the specified pool. See the
1796 section for more information on what properties can be set and acceptable
1804 .Op Fl o Ar property Ns = Ns Ar value
1809 Splits off one disk from each mirrored top-level
1811 in a pool and creates a new pool from the split-off disks. The original pool
1812 must be made up of one or more mirrors and must not be in the process of
1815 subcommand chooses the last device in each mirror
1817 unless overridden by a device specification on the command line.
1823 includes the specified device(s) in a new pool and, should any devices remain
1824 unspecified, assigns the last device in each mirror
1826 to that pool, as it does normally. If you are uncertain about the outcome of a
1830 ("dry-run") option to ensure your command will have the effect you intend.
1831 .Bl -tag -width indent
1833 Automatically import the newly created pool after splitting, using the
1836 parameter for the new pool's alternate root. See the
1842 Displays the configuration that would be created without actually splitting the
1843 pool. The actual pool split could still fail due to insufficient privileges or
1846 Comma-separated list of mount options to use when mounting datasets within the
1849 for a description of dataset properties and mount options. Valid only in
1850 conjunction with the
1853 .It Fl o Ar property Ns = Ns Ar value
1854 Sets the specified property on the new pool. See the
1856 section, above, for more information on the available pool properties.
1862 .Op Fl T Cm d Ns | Ns Cm u
1865 .Op Ar interval Op Ar count
1868 Displays the detailed health status for the given pools. If no
1870 is specified, then the status of each pool in the system is displayed. For more
1871 information on pool and device health, see the
1872 .Qq Sx Device Failure and Recovery
1875 When given an interval, the output is printed every
1881 is specified, the command exits after
1883 reports are printed.
1885 If a scrub or resilver is in progress, this command reports the percentage
1886 done and the estimated time to completion. Both of these are only approximate,
1887 because the amount of data in the pool and the other workloads on the system
1889 .Bl -tag -width indent
1891 Display a histogram of deduplication statistics, showing the allocated
1892 .Pq physically present on disk
1894 .Pq logically referenced in the pool
1895 block counts and sizes by reference count.
1896 .It Fl T Cm d Ns | Ns Cm u
1901 for standard date format. See
1906 .Pq equals Qq Ic date +%s .
1908 Displays verbose data error information, printing out a complete list of all
1909 data errors since the last complete pool scrub.
1911 Only display status for pools that are exhibiting errors or are otherwise
1913 Warnings about pools not using the latest on-disk format, having non-native
1914 block size or disabled features will not be included.
1922 Displays pools which do not have all supported features enabled and pools
1923 formatted using a legacy
1926 These pools can continue to be used, but some features may not be available.
1929 to enable all features on all pools.
1930 .Bl -tag -width indent
1934 versions supported by the current software.
1936 .Xr zpool-features 7
1937 for a description of feature flags features supported by the current software.
1946 Enables all supported features on the given pool.
1947 Once this is done, the pool will no longer be accessible on systems that do
1948 not support feature flags.
1950 .Xr zpool-features 7
1951 for details on compatibility with systems that support feature flags, but do
1952 not support all features enabled on the pool.
1953 .Bl -tag -width indent
1955 Enables all supported features on all pools.
1957 Upgrade to the specified legacy version. If the
1959 flag is specified, no features will be enabled on the pool.
1960 This option can only be used to increase version number up to the last
1961 supported legacy version number.
1965 The following exit values are returned:
1966 .Bl -tag -offset 2n -width 2n
1968 Successful completion.
1972 Invalid command line options were specified.
1976 .It Sy Example 1 No Creating a RAID-Z Storage Pool
1978 The following command creates a pool with a single
1982 that consists of six disks.
1983 .Bd -literal -offset 2n
1984 .Li # Ic zpool create tank raidz da0 da1 da2 da3 da4 da5
1986 .It Sy Example 2 No Creating a Mirrored Storage Pool
1988 The following command creates a pool with two mirrors, where each mirror
1990 .Bd -literal -offset 2n
1991 .Li # Ic zpool create tank mirror da0 da1 mirror da2 da3
1993 .It Sy Example 3 No Creating a Tn ZFS No Storage Pool by Using Partitions
1995 The following command creates an unmirrored pool using two GPT partitions.
1996 .Bd -literal -offset 2n
1997 .Li # Ic zpool create tank da0p3 da1p3
1999 .It Sy Example 4 No Creating a Tn ZFS No Storage Pool by Using Files
2001 The following command creates an unmirrored pool using files. While not
2002 recommended, a pool based on files can be useful for experimental purposes.
2003 .Bd -literal -offset 2n
2004 .Li # Ic zpool create tank /path/to/file/a /path/to/file/b
2006 .It Sy Example 5 No Adding a Mirror to a Tn ZFS No Storage Pool
2008 The following command adds two mirrored disks to the pool
2010 assuming the pool is already made up of two-way mirrors. The additional space
2011 is immediately available to any datasets within the pool.
2012 .Bd -literal -offset 2n
2013 .Li # Ic zpool add tank mirror da2 da3
2015 .It Sy Example 6 No Listing Available Tn ZFS No Storage Pools
2017 The following command lists all available pools on the system.
2018 .Bd -literal -offset 2n
2020 NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT
2021 pool 2.70T 473G 2.24T 33% - 17% 1.00x ONLINE -
2022 test 1.98G 89.5K 1.98G 48% - 0% 1.00x ONLINE -
2024 .It Sy Example 7 No Listing All Properties for a Pool
2026 The following command lists all the properties for a pool.
2027 .Bd -literal -offset 2n
2028 .Li # Ic zpool get all pool
2031 pool altroot - default
2032 pool health ONLINE -
2033 pool guid 2501120270416322443 default
2034 pool version 28 default
2035 pool bootfs pool/root local
2036 pool delegation on default
2037 pool autoreplace off default
2038 pool cachefile - default
2039 pool failmode wait default
2040 pool listsnapshots off default
2041 pool autoexpand off default
2042 pool dedupditto 0 default
2043 pool dedupratio 1.00x -
2045 pool allocated 473G -
2048 .It Sy Example 8 No Destroying a Tn ZFS No Storage Pool
2050 The following command destroys the pool
2052 and any datasets contained within.
2053 .Bd -literal -offset 2n
2054 .Li # Ic zpool destroy -f tank
2056 .It Sy Example 9 No Exporting a Tn ZFS No Storage Pool
2058 The following command exports the devices in pool
2060 so that they can be relocated or later imported.
2061 .Bd -literal -offset 2n
2062 .Li # Ic zpool export tank
2064 .It Sy Example 10 No Importing a Tn ZFS No Storage Pool
2066 The following command displays available pools, and then imports the pool
2068 for use on the system.
2070 The results from this command are similar to the following:
2071 .Bd -literal -offset 2n
2072 .Li # Ic zpool import
2075 id: 15451357997522795478
2077 action: The pool can be imported using its name or numeric identifier.
2089 Storage Pools to the Current Version
2092 The following command upgrades all
2094 Storage pools to the current version of
2096 .Bd -literal -offset 2n
2097 .Li # Ic zpool upgrade -a
2098 This system is currently running ZFS pool version 28.
2100 .It Sy Example 12 No Managing Hot Spares
2102 The following command creates a new pool with an available hot spare:
2103 .Bd -literal -offset 2n
2104 .Li # Ic zpool create tank mirror da0 da1 spare da2
2107 If one of the disks were to fail, the pool would be reduced to the degraded
2108 state. The failed device can be replaced using the following command:
2109 .Bd -literal -offset 2n
2110 .Li # Ic zpool replace tank da0 da2
2113 Once the data has been resilvered, the spare is automatically removed and is
2114 made available should another device fails. The hot spare can be permanently
2115 removed from the pool using the following command:
2116 .Bd -literal -offset 2n
2117 .Li # Ic zpool remove tank da2
2123 Pool with Mirrored Separate Intent Logs
2126 The following command creates a
2128 storage pool consisting of two, two-way
2129 mirrors and mirrored log devices:
2130 .Bd -literal -offset 2n
2131 .Li # Ic zpool create pool mirror da0 da1 mirror da2 da3 log mirror da4 da5
2133 .It Sy Example 14 No Adding Cache Devices to a Tn ZFS No Pool
2135 The following command adds two disks for use as cache devices to a
2138 .Bd -literal -offset 2n
2139 .Li # Ic zpool add pool cache da2 da3
2142 Once added, the cache devices gradually fill with content from main memory.
2143 Depending on the size of your cache devices, it could take over an hour for
2144 them to fill. Capacity and reads can be monitored using the
2146 subcommand as follows:
2147 .Bd -literal -offset 2n
2148 .Li # Ic zpool iostat -v pool 5
2152 Displaying expanded space on a device
2155 The following command dipslays the detailed information for the
2158 This pool is comprised of a single
2160 vdev where one of its
2161 devices increased its capacity by 10GB.
2162 In this example, the pool will not
2163 be able to utilized this extra capacity until all the devices under the
2165 vdev have been expanded.
2166 .Bd -literal -offset 2n
2167 .Li # Ic zpool list -v data
2168 NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT
2169 data 23.9G 14.6G 9.30G 48% - 61% 1.00x ONLINE -
2170 raidz1 23.9G 14.6G 9.30G 48% -
2177 Removing a Mirrored top-level (Log or Data) Device
2180 The following commands remove the mirrored log device
2182 and mirrored top-level data device
2185 Given this configuration:
2186 .Bd -literal -offset 2n
2189 scrub: none requested
2192 NAME STATE READ WRITE CKSUM
2194 mirror-0 ONLINE 0 0 0
2197 mirror-1 ONLINE 0 0 0
2201 mirror-2 ONLINE 0 0 0
2206 The command to remove the mirrored log
2209 .Bd -literal -offset 2n
2210 .Li # Ic zpool remove tank mirror-2
2213 The command to remove the mirrored data
2216 .Bd -literal -offset 2n
2217 .Li # Ic zpool remove tank mirror-1
2221 Recovering a Faulted
2226 If a pool is faulted but recoverable, a message indicating this state is
2229 if the pool was cached (see the
2231 argument above), or as part of the error output from a failed
2235 Recover a cached pool with the
2238 .Bd -literal -offset 2n
2239 .Li # Ic zpool clear -F data
2240 Pool data returned to its state as of Tue Sep 08 13:23:35 2009.
2241 Discarded approximately 29 seconds of transactions.
2244 If the pool configuration was not cached, use
2246 with the recovery mode flag:
2247 .Bd -literal -offset 2n
2248 .Li # Ic zpool import -F data
2249 Pool data returned to its state as of Tue Sep 08 13:23:35 2009.
2250 Discarded approximately 29 seconds of transactions.
2254 .Xr zpool-features 7 ,
2258 This manual page is a
2260 reimplementation of the
2264 modified and customized for
2266 and licensed under the Common Development and Distribution License
2271 implementation of this manual page was initially written by
2272 .An Martin Matuska Aq mm@FreeBSD.org .
projects / FreeBSD / FreeBSD.git / blob