Go Back    


Recursive Search Engine for Linux and Unix Man Pages by Neo
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

zpool(1M)			  System Administration Commands			zpool(1M)

NAME
       zpool - configures ZFS storage pools

SYNOPSIS
       zpool [-?]

       zpool create [-fn] [-o property=value] ... [-m mountpoint] [-R root]
	   pool vdev ...

       zpool destroy [-f] pool

       zpool add [-fn] pool vdev ...

       zpool remove pool device ...

       zpool list [-H] [-o property[,...]] [pool] ...

       zpool iostat [-v] [pool] ... [interval[count]]

       zpool status [-xv] [pool] ...

       zpool online pool device ...

       zpool offline [-t] pool device ...

       zpool clear pool [device]

       zpool attach [-f] pool device new_device

       zpool detach pool device

       zpool replace [-f] pool device [new_device]

       zpool scrub [-s] pool ...

       zpool import [-d dir] [-D]

       zpool import [-o mntopts] [-p property=value] ... [-d dir | -c cachefile]
	   [-D] [-f] [-R root] -a

       zpool import [-o mntopts] [-o property=value] ... [-d dir | -c cachefile]
	   [-D] [-f] [-R root] pool |id [newpool]

       zpool export [-f] pool ...

       zpool upgrade

       zpool upgrade -v

       zpool upgrade [-V version] -a | pool ...

       zpool history [-il] [pool] ...

       zpool get "all" | property[,...] pool ...

       zpool set property=value pool

DESCRIPTION
       The  zpool command configures ZFS storage pools. A storage pool is a collection of devices
       that provides physical storage and data replication for ZFS datasets.

       All datasets within a storage pool share the same space. See zfs(1M)  for  information  on
       managing datasets.

   Virtual Devices (vdevs)
       A  "virtual device" describes a single device or a collection of devices organized accord-
       ing to certain performance and fault characteristics. The following  virtual  devices  are
       supported:

       disk	 A  block  device,  typically  located	under  "/dev/dsk". ZFS can use individual
		 slices or partitions, though the recommended mode of operation is to  use  whole
		 disks.  A  disk  can  be specified by a full path, or it can be a shorthand name
		 (the relative portion of the path under "/dev/dsk"). A whole disk can be  speci-
		 fied  by  omitting  the slice or partition designation. For example, "c0t0d0" is
		 equivalent to "/dev/dsk/c0t0d0s2". When given a whole	disk,  ZFS  automatically
		 labels the disk, if necessary.

       file	 A  regular file. The use of files as a backing store is strongly discouraged. It
		 is designed primarily for experimental purposes, as the  fault  tolerance  of	a
		 file  is  only  as good as the file system of which it is a part. A file must be
		 specified by a full path.

       mirror	 A mirror of two or more devices. Data is  replicated  in  an  identical  fashion
		 across  all  components  of a mirror. A mirror with N disks of size X can hold X
		 bytes and can withstand (N-1) devices failing before data integrity  is  compro-
		 mised.

       raidz	 A  variation  on RAID-5 that allows for better distribution of parity and elimi-
       raidz1	 nates the "RAID-5 write hole" (in which  data	and  parity  become  inconsistent
       raidz2	 after	a power loss). Data and parity is striped across all disks within a raidz
		 group.

		 A raidz group can have either single- or double-parity, meaning that  the  raidz
		 group	can sustain one or two failures respectively without losing any data. The
		 raidz1 vdev type specifies a single-parity raidz group and the raidz2 vdev  type
		 specifies  a  double-parity  raidz  group.  The  raidz vdev type is an alias for
		 raidz1.

		 A raidz group with N disks of size X with P parity disks can hold  approximately
		 (N-P)*X  bytes  and  can  withstand P device(s) failing before data integrity is
		 compromised. The minimum number of devices in a raidz group is one more than the
		 number  of  parity  disks.  The  recommended  number  is between 3 and 9 to help
		 increase performance.

       spare	 A special pseudo-vdev which keeps track of available hot spares for a pool.  For
		 more information, see the "Hot Spares" section.

       log	 A  separate  intent  log  device. If more than one log device is specified, then
		 writes are load-balanced between devices. Log devices can be mirrored.  However,
		 raidz and raidz2 are not supported for the intent log. For more information, see
		 the "Intent Log" section.

       cache	 A device used to cache storage pool data. A cache device cannot be  mirrored  or
		 part  of  a  raidz or raidz2 configuration. For more information, see the "Cache
		 Devices" section.

       Virtual devices cannot be nested, so a mirror or raidz virtual  device  can  only  contain
       files or disks. Mirrors of mirrors (or other combinations) are not allowed.

       A  pool	can  have any number of virtual devices at the top of the configuration (known as
       "root vdevs"). Data is dynamically distributed across all  top-level  devices  to  balance
       data among devices. As new virtual devices are added, ZFS automatically places data on the
       newly available devices.

       Virtual devices are specified one at a time on the command line, separated by  whitespace.
       The  keywords  "mirror" and "raidz" are used to distinguish where a group ends and another
       begins. For example, the following creates two root vdevs, each a mirror of two disks:

	 # zpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0

   Device Failure and Recovery
       ZFS supports a rich set of mechanisms for handling device failure and data corruption. All
       metadata  and data is checksummed, and ZFS automatically repairs bad data from a good copy
       when corruption is detected.

       In order to take advantage of these features, a pool must make use of some form of  redun-
       dancy,  using  either mirrored or raidz groups. While ZFS supports running in a non-redun-
       dant configuration, where each root vdev is simply a disk or file, this is  strongly  dis-
       couraged. A single case of bit corruption can render some or all of your data unavailable.

       A  pool's health status is described by one of three states: online, degraded, or faulted.
       An online pool has all devices operating normally. A degraded pool is one in which one  or
       more  devices  have  failed, but the data is still available due to a redundant configura-
       tion. A faulted pool has corrupted metadata, or one or more faulted devices, and  insuffi-
       cient replicas to continue functioning.

       The  health of the top-level vdev, such as mirror or raidz device, is potentially impacted
       by the state of its associated vdevs, or component devices. A top-level vdev or	component
       device is in one of the following states:

       DEGRADED    One	or more top-level vdevs is in the degraded state because one or more com-
		   ponent devices are offline. Sufficient replicas exist to continue functioning.

		   One or more component devices is in the degraded or faulted state, but  suffi-
		   cient replicas exist to continue functioning. The underlying conditions are as
		   follows:

		       o      The number of checksum errors exceeds  acceptable  levels  and  the
			      device  is  degraded  as an indication that something may be wrong.
			      ZFS continues to use the device as necessary.

		       o      The number of I/O errors	exceeds  acceptable  levels.  The  device
			      could  not  be  marked  as  faulted  because there are insufficient
			      replicas to continue functioning.

       FAULTED	   One or more top-level vdevs is in the faulted state because one or more compo-
		   nent devices are offline. Insufficient replicas exist to continue functioning.

		   One or more component devices is in the faulted state, and insufficient repli-
		   cas exist to continue functioning. The underlying conditions are as follows:

		       o      The device could be opened, but the contents did not match expected
			      values.

		       o      The  number  of I/O errors exceeds acceptable levels and the device
			      is faulted to prevent further use of the device.

       OFFLINE	   The device was explicitly taken offline by the "zpool offline" command.

       ONLINE	   The device is online and functioning.

       REMOVED	   The device was physically removed while the system was running. Device removal
		   detection is hardware-dependent and may not be supported on all platforms.

       UNAVAIL	   The	device	could  not  be	opened.  If  a pool is imported when a device was
		   unavailable, then the device will be identified by a unique identifier instead
		   of its path since the path was never correct in the first place.

       If a device is removed and later re-attached to the system, ZFS attempts to put the device
       online automatically. Device attach detection is hardware-dependent and might not be  sup-
       ported on all platforms.

   Hot Spares
       ZFS  allows  devices  to  be  associated with pools as "hot spares". These devices are not
       actively used in the pool, but when an active device fails, it is  automatically  replaced
       by  a  hot spare. To create a pool with hot spares, specify a "spare" vdev with any number
       of devices. For example,

	 # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0

       Spares can be shared across multiple pools, and can be added with the "zpool add"  command
       and  removed with the "zpool remove" command. Once a spare replacement is initiated, a new
       "spare" vdev is created within the configuration that will remain there until the original
       device is replaced. At this point, the hot spare becomes available again if another device
       fails.

       An in-progress spare replacement can be cancelled by detaching the hot spare. If the orig-
       inal  faulted  device  is detached, then the hot spare assumes its place in the configura-
       tion, and is removed from the spare list of all active pools.

       Spares cannot replace log devices.

   Intent Log
       The ZFS Intent Log (ZIL) satisfies POSIX requirements for  synchronous  transactions.  For
       instance,  databases often require their transactions to be on stable storage devices when
       returning from a system call. NFS and other applications can also use  fsync()  to  ensure
       data  stability. By default, the intent log is allocated from blocks within the main pool.
       However, it might be possible to get better performance using separate intent log  devices
       such as NVRAM or a dedicated disk. For example:

	 # zpool create pool c0d0 c1d0 log c2d0

       Multiple  log  devices  can  also be specified, and they can be mirrored. See the EXAMPLES
       section for an example of mirroring multiple log devices.

       Log devices can be added, replaced, attached, detached, and imported and exported as  part
       of the larger pool.

   Cache Devices
       Devices	can be added to a storage pool as "cache devices." These devices provide an addi-
       tional layer of caching between main memory and disk. For read-heavy workloads, where  the
       working	set  size  is  much  larger  than  what can be cached in main memory, using cache
       devices allow much more of this working set to be served from  low  latency  media.  Using
       cache  devices  provides the greatest performance improvement for random read-workloads of
       mostly static content.

       To create a pool with cache devices, specify a "cache" vdev with any  number  of  devices.
       For example:

	 # zpool create pool c0d0 c1d0 cache c2d0 c3d0

       Cache  devices  cannot  be  mirrored  or part of a raidz configuration. If a read error is
       encountered on a cache device, that read I/O is reissued  to  the  original  storage  pool
       device, which might be part of a mirrored or raidz configuration.

       The  content of the cache devices is considered volatile, as is the case with other system
       caches.

   Properties
       Each pool has several properties associated with it. Some properties are read-only statis-
       tics  while others are configurable and change the behavior of the pool. The following are
       read-only properties:

       available	   Amount of storage available within the pool. This property can also be
			   referred to by its shortened column name, "avail".

       capacity 	   Percentage  of  pool space used. This property can also be referred to
			   by its shortened column name, "cap".

       health		   The current health of the pool. Health can  be  "ONLINE",  "DEGRADED",
			   "FAULTED", " OFFLINE", "REMOVED", or "UNAVAIL".

       guid		   A unique identifier for the pool.

       size		   Total size of the storage pool.

       used		   Amount of storage space used within the pool.

       These  space  usage properties report actual physical space available to the storage pool.
       The physical space can be different from the total amount  of  space  that  any	contained
       datasets  can  actually	use. The amount of space used in a raidz configuration depends on
       the characteristics of the data being written. In addition, ZFS reserves  some  space  for
       internal  accounting  that  the	zfs(1M) command takes into account, but the zpool command
       does not. For non-full pools of a reasonable size, these effects should be invisible.  For
       small  pools,  or  pools  that are close to being completely full, these discrepancies may
       become more noticeable.

       The following property can be set at creation time and import time:

       altroot

	   Alternate root directory. If set, this directory is	prepended  to  any  mount  points
	   within  the	pool.  This  can  be  used when examining an unknown pool where the mount
	   points cannot be trusted, or in an alternate boot environment, where the typical paths
	   are not valid. altroot is not a persistent property. It is valid only while the system
	   is up. Setting altroot defaults to using cachefile=none, though this may  be  overrid-
	   den	   using an explicit setting.

       The  following  properties  can be set at creation time and import time, and later changed
       with the "zpool set" command:

       autoreplace=on | off

	   Controls automatic device replacement. If set to "off",  device  replacement  must  be
	   initiated  by  the administrator by using the "zpool replace" command. If set to "on",
	   any new device, found in the same  physical	location  as  a  device  that  previously
	   belonged to the pool, is automatically formatted and replaced. The default behavior is
	   "off". This property can also be referred to by its shortened column name, "replace".

       bootfs=pool/dataset

	   Identifies the default bootable dataset for the root pool. This property  is  expected
	   to be set mainly by the installation and upgrade programs.

       cachefile=path | "none"

	   Controls the location of where the pool configuration is cached. Discovering all pools
	   on system startup requires a cached copy of the configuration data that is  stored  on
	   the root file system. All pools in this cache are automatically imported when the sys-
	   tem boots. Some environments, such as install  and  clustering,  need  to  cache  this
	   information in a different location so that pools are not automatically imported. Set-
	   ting this property caches the pool configuration in	a  different  location	that  can
	   later  be imported with "zpool import -c". Setting it to the special value "none" cre-
	   ates a temporary pool that is never cached, and the special value  ''  (empty  string)
	   uses the default location.

	   Multiple  pools  can share the same cache file. Because the kernel destroys and recre-
	   ates this file when pools are added and removed, care should be taken when  attempting
	   to  access  this  file. When the last pool using a cachefile is exported or destroyed,
	   the file is removed.

       delegation=on | off

	   Controls whether a non-privileged user is granted access based on the dataset  permis-
	   sions defined on the dataset. See zfs(1M) for more information on ZFS delegated admin-
	   istration.

       failmode=wait | continue | panic

	   Controls the system behavior in the event of catastrophic pool failure. This condition
	   is typically a result of a loss of connectivity to the underlying storage device(s) or
	   a failure of all devices within the pool. The behavior of such an event is  determined
	   as follows:

	   wait        Blocks  all  I/O access until the device connectivity is recovered and the
		       errors are cleared. This is the default behavior.

	   continue    Returns EIO to any new write I/O requests but allows reads to any  of  the
		       remaining  healthy devices. Any write requests that have yet to be commit-
		       ted to disk would be blocked.

	   panic       Prints out a message to the console and generates a system crash dump.

       version=version

	   The current on-disk version of the pool. This can be increased, but	never  decreased.
	   The	preferred  method  of  updating pools is with the "zpool upgrade" command, though
	   this property can be used when a specific version is needed for backwards  compatibil-
	   ity.   This	property  can be any number between 1 and the current version reported by
	   "zpool upgrade -v". The special value "current" is an alias for the	latest	supported
	   version.

   Subcommands
       All  subcommands  that  modify state are logged persistently to the pool in their original
       form.

       The zpool command provides subcommands to create and destroy storage pools,  add  capacity
       to  storage  pools, and provide information about the storage pools. The following subcom-
       mands are supported:

       zpool -?

	   Displays a help message.

       zpool create [-fn] [-o property=value] ... [-m mountpoint] [-R root] pool vdev ...

	   Creates a new storage pool containing the virtual devices  specified  on  the  command
	   line.  The pool name must begin with a letter, and can only contain alphanumeric char-
	   acters as well as underscore ("_"), dash ("-"), and period ("."). The pool names "mir-
	   ror", "raidz", "spare" and "log" are reserved, as are names beginning with the pattern
	   "c[0-9]". The vdev specification is described in the "Virtual Devices" section.

	   The command verifies that each device specified is accessible and not currently in use
	   by  another subsystem. There are some uses, such as being currently mounted, or speci-
	   fied as the dedicated dump device, that prevents a device from ever being used by ZFS.
	   Other  uses,  such as having a preexisting UFS file system, can be overridden with the
	   -f option.

	   The command also checks that the replication strategy for the pool is  consistent.  An
	   attempt  to	combine  redundant  and non-redundant storage in a single pool, or to mix
	   disks and files, results in an error unless -f is specified. The  use  of  differently
	   sized devices within a single raidz or mirror group is also flagged as an error unless
	   -f is specified.

	   Unless the -R option is specified, the default mount point is "/pool". The mount point
	   must  not exist or must be empty, or else the root dataset cannot be mounted. This can
	   be overridden with the -m option.

	   -f

	       Forces use of vdevs, even if they appear in use or specify a conflicting  replica-
	       tion level. Not all devices can be overridden in this manner.

	   -n

	       Displays  the configuration that would be used without actually creating the pool.
	       The actual pool creation can still fail due to insufficient privileges  or  device
	       sharing.

	   -o property=value [-o property=value] ...

	       Sets  the  given pool properties. See the "Properties" section for a list of valid
	       properties that can be set.

	   -R root

	       Equivalent to "-o cachefile=none,altroot=root"

	   -m mountpoint

	       Sets the mount point for the root dataset. The default mount point is  "/pool"  or
	       "altroot/pool"  if altroot is specified. The mount point must be an absolute path,
	       "legacy", or "none". For more information on dataset mount points, see zfs(1M).

       zpool destroy [-f] pool

	   Destroys the given pool, freeing up any devices for other use. This command	tries  to
	   unmount any active datasets before destroying the pool.

	   -f	 Forces any active datasets contained within the pool to be unmounted.

       zpool add [-fn] pool vdev ...

	   Adds  the  specified  virtual  devices  to  the  given pool. The vdev specification is
	   described in the "Virtual Devices" section. The behavior of the  -f	option,  and  the
	   device checks performed are described in the "zpool create" subcommand.

	   -f	 Forces  use of vdevs, even if they appear in use or specify a conflicting repli-
		 cation level. Not all devices can be overridden in this manner.

	   -n	 Displays the configuration that would be used without actually adding the vdevs.
		 The actual pool creation can still fail due to insufficient privileges or device
		 sharing.

	   Do not add a disk that is currently configured as a quorum device to a zpool. After	a
	   disk is in the pool, that disk can then be configured as a quorum device.

       zpool remove pool device ...

	   Removes  the  specified  device  from  the  pool. This command currently only supports
	   removing hot spares and cache devices. Devices that are part of a mirrored  configura-
	   tion  can be removed using the "zpool detach" command. Non-redundant and raidz devices
	   cannot be removed from a pool.

       zpool list [-H] [-o props[,...]] [pool] ...

	   Lists the given pools along with a health status and space usage. When given no  argu-
	   ments, all pools in the system are listed.

	   -H	       Scripted mode. Do not display headers, and separate fields by a single tab
		       instead of arbitrary space.

	   -o props    Comma-separated list of properties to display. See the  "Properties"  sec-
		       tion  for  a  list  of  valid properties. The default list is "name, size,
		       used, available, capacity, health, altroot"

       zpool iostat [-v] [pool] ... [interval[count]]

	   Displays I/O statistics for the given pools. When given an  interval,  the  statistics
	   are printed every interval seconds until Ctrl-C is pressed. If no pools are specified,
	   statistics for every pool in the system is shown. If count is specified,  the  command
	   exits after count reports are printed.

	   -v	 Verbose  statistics.  Reports	usage  statistics for individual vdevs within the
		 pool, in addition to the pool-wide statistics.

       zpool status [-xv] [pool] ...

	   Displays the detailed health status for the given pools. If no pool is specified, then
	   the	status	of each pool in the system is displayed. For more information on pool and
	   device health, see the "Device Failure and Recovery" section.

	   If a scrub or resilver is in progress, this command reports the  percentage	done  and
	   the	estimated  time  to  completion.  Both of these are only approximate, because the
	   amount of data in the pool and the other workloads on the system can change.

	   -x	 Only display status for pools	that  are  exhibiting  errors  or  are	otherwise
		 unavailable.

	   -v	 Displays  verbose  data  error  information, printing out a complete list of all
		 data errors since the last complete pool scrub.

       zpool online pool device ...

	   Brings the specified physical device online.

	   This command is not applicable to spares or cache devices.

       zpool offline [-t] pool device ...

	   Takes the specified physical device offline. While the device is offline,  no  attempt
	   is made to read or write to the device.

	   This command is not applicable to spares or cache devices.

	   -t	 Temporary.  Upon  reboot,  the specified physical device reverts to its previous
		 state.

       zpool clear pool [device] ...

	   Clears device errors in a pool. If no  arguments  are  specified,  all  device  errors
	   within  the	pool  are cleared. If one or more devices is specified, only those errors
	   associated with the specified device or devices are cleared.

       zpool attach [-f] pool device new_device

	   Attaches new_device to an existing zpool device. The existing device cannot be part of
	   a  raidz  configuration.  If device is not currently part of a mirrored configuration,
	   device automatically transforms into a two-way mirror of  device  and  new_device.  If
	   device  is  part of a two-way mirror, attaching new_device creates a three-way mirror,
	   and so on. In either case, new_device begins to resilver immediately.

	   -f	 Forces use of new_device, even if its appears to be in use. Not all devices  can
		 be overridden in this manner.

       zpool detach pool device

	   Detaches  device  from  a mirror. The operation is refused if there are no other valid
	   replicas of the data.

       zpool replace [-f] pool old_device [new_device]

	   Replaces old_device with new_device. This is equivalent to attaching new_device, wait-
	   ing for it to resilver, and then detaching old_device.

	   The	size  of  new_device must be greater than or equal to the minimum size of all the
	   devices in a mirror or raidz configuration.

	   new_device is required if the pool is not redundant. If new_device is  not  specified,
	   it  defaults  to old_device. This form of replacement is useful after an existing disk
	   has failed and has been physically replaced.  In this case, the new disk may have  the
	   same /dev/dsk path as the old device, even though it is actually a different disk. ZFS
	   recognizes this.

	   -f	 Forces use of new_device, even if its appears to be in use. Not all devices  can
		 be overridden in this manner.

       zpool scrub [-s] pool ...

	   Begins  a  scrub. The scrub examines all data in the specified pools to verify that it
	   checksums correctly. For replicated	(mirror  or  raidz)  devices,  ZFS  automatically
	   repairs any damage discovered during the scrub. The "zpool status" command reports the
	   progress of the scrub and summarizes the results of the scrub upon completion.

	   Scrubbing and resilvering are very similar operations. The difference is  that  resil-
	   vering  only examines data that ZFS knows to be out of date (for example, when attach-
	   ing a new device to a mirror or replacing an existing device), whereas scrubbing exam-
	   ines all data to discover silent errors due to hardware faults or disk failure.

	   Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows one at
	   a time. If a scrub is already in progress, the "zpool scrub" command terminates it and
	   starts  a  new  scrub.  If a resilver is in progress, ZFS does not allow a scrub to be
	   started until the resilver completes.

	   -s	 Stop scrubbing.

       zpool import [-d dir | -c cachefile] [-D]

	   Lists pools available to import. If the -d  option  is  not	specified,  this  command
	   searches for devices in "/dev/dsk". The -d option can be specified multiple times, and
	   all directories are searched. If the device appears to be part of  an  exported  pool,
	   this command displays a summary of the pool with the name of the pool, a numeric iden-
	   tifier, as well as the vdev layout and current health of the device for each device or
	   file.  Destroyed  pools, pools that were previously destroyed with the "zpool destroy"
	   command, are not listed unless the -D option is specified.

	   The numeric identifier is unique, and can be used instead of the pool name when multi-
	   ple exported pools of the same name are available.

	   -c cachefile    Reads configuration from the given cachefile that was created with the
			   "cachefile" pool property. This cachefile is used instead of searching
			   for devices.

	   -d dir	   Searches  for  devices or files in dir. The -d option can be specified
			   multiple times.

	   -D		   Lists destroyed pools only.

       zpool import [-o mntopts] [ -o property=value] ... [-d dir | -c cachefile] [-D] [-f] [-R
       root] -a

	   Imports  all pools found in the search directories. Identical to the previous command,
	   except that all pools with a sufficient number  of  devices	available  are	imported.
	   Destroyed  pools,  pools  that were previously destroyed with the "zpool destroy" com-
	   mand, will not be imported unless the -D option is specified.

	   -o mntopts		Comma-separated list  of  mount  options  to  use  when  mounting
				datasets  within  the  pool.  See  zfs(1M)  for  a description of
				dataset properties and mount options.

	   -o property=value	Sets the specified property on the imported pool. See the  "Prop-
				erties"  section for more information on the available pool prop-
				erties.

	   -c cachefile 	Reads configuration from the given  cachefile  that  was  created
				with  the  "cachefile"	pool  property.  This  cachefile  is used
				instead of searching for devices.

	   -d dir		Searches for devices or files in dir. The -d option can be speci-
				fied  multiple	times.	This  option  is incompatible with the -c
				option.

	   -D			Imports destroyed pools only. The -f option is also required.

	   -f			Forces import, even if the pool appears to be potentially active.

	   -a			Searches for and imports all pools found.

	   -R root		Sets the "cachefile" property to "none" and the  "altroot"  prop-
				erty to "root".

       zpool import [-o mntopts] [ -o property=value] ... [-d dir | -c cachefile] [-D] [-f] [-R
       root] pool | id [newpool]

	   Imports a specific pool. A pool can be identified by its name or the  numeric  identi-
	   fier. If newpool is specified, the pool is imported using the name newpool. Otherwise,
	   it is imported with the same name as its exported name.

	   If a device is removed from a system without running "zpool export" first, the  device
	   appears as potentially active. It cannot be determined if this was a failed export, or
	   whether the device is really in use from another host. To import a pool in this state,
	   the -f option is required.

	   -o mntopts

	       Comma-separated	list  of  mount  options to use when mounting datasets within the
	       pool. See zfs(1M) for a description of dataset properties and mount options.

	   -o property=value

	       Sets the specified property on the imported pool. See the "Properties" section for
	       more information on the available pool properties.

	   -c cachefile

	       Reads configuration from the given cachefile that was created with the "cachefile"
	       pool property. This cachefile is used instead of searching for devices.

	   -d dir

	       Searches for devices or files in dir. The -d  option  can  be  specified  multiple
	       times. This option is incompatible with the -c option.

	   -D

	       Imports destroyed pool. The -f option is also required.

	   -f

	       Forces import, even if the pool appears to be potentially active.

	   -R root

	       Sets the "cachefile" property to "none" and the "altroot" property to "root".

       zpool export [-f] pool ...

	   Exports  the  given pools from the system. All devices are marked as exported, but are
	   still considered in use by other subsystems. The devices can be moved between  systems
	   (even  those  of  different endianness) and imported as long as a sufficient number of
	   devices are present.

	   Before exporting the pool, all datasets within the pool are unmounted.

	   For pools to be portable, you must give  the  zpool	command  whole	disks,	not  just
	   slices,  so	that  ZFS  can	label the disks with portable EFI labels. Otherwise, disk
	   drivers on platforms of different endianness will not recognize the disks.

	   -f	 Forcefully unmount all datasets, using the "unmount -f" command.

       zpool upgrade

	   Displays all pools formatted using a different ZFS on-disk version. Older versions can
	   continue  to  be  used,  but  some  features  may not be available. These pools can be
	   upgraded using "zpool upgrade -a". Pools that are formatted with a more recent version
	   are also displayed, although these pools will be inaccessible on the system.

       zpool upgrade -v

	   Displays  ZFS versions supported by the current software. The current ZFS versions and
	   all previous supported versions are displayed, along with an explanation of	the  fea-
	   tures provided with each version.

       zpool upgrade [-V version] -a | pool ...

	   Upgrades  the  given  pool  to the latest on-disk version. Once this is done, the pool
	   will no longer be accessible on systems running older versions of the software.

	   -a		 Upgrades all pools.

	   -V version	 Upgrade to the specified version. If the -V flag is not  specified,  the
			 pool  is  upgraded  to  the most recent version. This option can only be
			 used to increase the version number, and only up to the most recent ver-
			 sion supported by this software.

       zpool history [-il] [pool] ...

	   Displays  the command history of the specified pools or all pools if no pool is speci-
	   fied.

	   -i	 Displays internally logged ZFS events in addition to user initiated events.

	   -l	 Displays log records in long  format,	which  in  addition  to  standard  format
		 includes,  the  user name, the hostname, and the zone in which the operation was
		 performed.

       zpool get "all" | property[,...] pool ...

	   Retrieves the given list of properties (or all properties if "all" is  used)  for  the
	   specified storage pool(s). These properties are displayed with the following fields:

		    name	  Name of storage pool
		    property	  Property name
		    value	  Property value
		    source	  Property source, either 'default' or 'local'.

	   See the "Properties" section for more information on the available pool properties.

       zpool set property=value pool

	   Sets  the  given property on the specified pool. See the "Properties" section for more
	   information on what properties can be set and acceptable values.

EXAMPLES
       Example 1 Creating a RAID-Z Storage Pool

       The following command creates a pool with a single raidz root vdev that	consists  of  six
       disks.

	 # zpool create tank raidz c0t0d0 c0t1d0 c0t2d0 c0t3d0 c0t4d0 c0t5d0

       Example 2 Creating a Mirrored Storage Pool

       The  following  command	creates  a  pool with two mirrors, where each mirror contains two
       disks.

	 # zpool create tank mirror c0t0d0 c0t1d0 mirror c0t2d0 c0t3d0

       Example 3 Creating a ZFS Storage Pool by Using Slices

       The following command creates an unmirrored pool using two disk slices.

	 # zpool create tank /dev/dsk/c0t0d0s1 c0t1d0s4

       Example 4 Creating a ZFS Storage Pool by Using Files

       The following command creates an unmirrored pool using files.  While  not  recommended,	a
       pool based on files can be useful for experimental purposes.

	 # zpool create tank /path/to/file/a /path/to/file/b

       Example 5 Adding a Mirror to a ZFS Storage Pool

       The  following  command	adds  two mirrored disks to the pool "tank", assuming the pool is
       already made up of two-way mirrors. The additional space is immediately available  to  any
       datasets within the pool.

	 # zpool add tank mirror c1t0d0 c1t1d0

       Example 6 Listing Available ZFS Storage Pools

       The following command lists all available pools on the system. In this case, the pool zion
       is faulted due to a missing device.

       The results from this command are similar to the following:

	 # zpool list
	     NAME	       SIZE    USED   AVAIL    CAP  HEALTH     ALTROOT
	     pool	      67.5G   2.92M   67.5G	0%  ONLINE     -
	     tank	      67.5G   2.92M   67.5G	0%  ONLINE     -
	     zion		  -	  -	  -	0%  FAULTED    -

       Example 7 Destroying a ZFS Storage Pool

       The following command destroys the pool "tank" and any datasets contained within.

	 # zpool destroy -f tank

       Example 8 Exporting a ZFS Storage Pool

       The following command exports the devices in pool tank so that they can	be  relocated  or
       later imported.

	 # zpool export tank

       Example 9 Importing a ZFS Storage Pool

       The  following  command displays available pools, and then imports the pool "tank" for use
       on the system.

       The results from this command are similar to the following:

	 # zpool import
	  pool: tank
	    id: 15451357997522795478
	 state: ONLINE
	 action: The pool can be imported using its name or numeric identifier.
	 config:

		tank	    ONLINE
		  mirror    ONLINE
		    c1t2d0  ONLINE
		    c1t3d0  ONLINE

	 # zpool import tank

       Example 10 Upgrading All ZFS Storage Pools to the Current Version

       The following command upgrades all ZFS Storage pools to the current version of  the  soft-
       ware.

	 # zpool upgrade -a
	 This system is currently running ZFS version 2.

       Example 11 Managing Hot Spares

       The following command creates a new pool with an available hot spare:

	 # zpool create tank mirror c0t0d0 c0t1d0 spare c0t2d0

       If  one	of  the  disks were to fail, the pool would be reduced to the degraded state. The
       failed device can be replaced using the following command:

	 # zpool replace tank c0t0d0 c0t3d0

       Once the data has been resilvered, the spare is automatically removed and is  made  avail-
       able  should  another device fails. The hot spare can be permanently removed from the pool
       using the following command:

	 # zpool remove tank c0t2d0

       Example 12 Creating a ZFS Pool with Mirrored Separate Intent Logs

       The following command creates a ZFS storage pool consisting of two,  two-way  mirrors  and
       mirrored log devices:

	 # zpool create pool mirror c0d0 c1d0 mirror c2d0 c3d0 log mirror \
	   c4d0 c5d0

       Example 13 Adding Cache Devices to a ZFS Pool

       The following command adds two disks for use as cache devices to a ZFS storage pool:

	 # zpool add pool cache c2d0 c3d0

       Once  added,  the cache devices gradually fill with content from main memory. Depending on
       the size of your cache devices, it could take over an hour for them to fill. Capacity  and
       reads can be monitored using the iostat option as follows:

	 # zpool iostat -v pool 5

EXIT STATUS
       The following exit values are returned:

       0    Successful completion.

       1    An error occurred.

       2    Invalid command line options were specified.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWzfsu			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       zfs(1M), attributes(5)

SunOS 5.11				   13 Nov 2007					zpool(1M)
The UNIX and Linux Forums Man Pages : 2014 The UNIX and Linux Forums


All times are GMT -4. The time now is 11:56 AM.