home | help
zfs(1M) 		 System Administration Commands 		 zfs(1M)

NAME
     zfs - configures ZFS file systems

SYNOPSIS
     zfs [-?]

     zfs create [[-o property=value]]... filesystem

     zfs create [-s] [-b blocksize] [[-o property=value]]... -V size volume

     zfs destroy [-rRf] filesystem|volume|snapshot

     zfs clone snapshot filesystem|volume

     zfs promote filesystem

     zfs rename filesystem|volume|snapshot
	 [filesystem|volume|snapshot]

     zfs snapshot [-r] filesystem@name|volume@name

     zfs rollback [-rRf] snapshot

     zfs list [-rH] [-o prop[,prop] ]... [ -t type[,type]...]
	 [ -s prop [-s prop]... [ -S prop [-S prop]...
	 [filesystem|volume|snapshot|/pathname|./pathname ...

     zfs set property=value filesystem|volume ...

     zfs get [-rHp] [-o field[,field]...]
	 [-s source[,source]...] all | property[,property]...
	  filesystem|volume|snapshot ...

     zfs inherit [-r] property filesystem|volume... ...

     zfs mount

     zfs mount [-o options] [-O] -a

     zfs mount [-o options] [-O] filesystem

     zfs unmount [-f] -a

     zfs unmount [-f] filesystem|mountpoint

     zfs share -a

     zfs share filesystem

     zfs unshare [-f] -a

     zfs unshare [-f] filesystem|mountpoint

     zfs send [-i snapshot1] snapshot2

     zfs receive [-vnF ] filesystem|volume|snapshot

     zfs receive [-vnF ] -d filesystem

     zfs jail jailid filesystem

     zfs unjail jailid filesystem

DESCRIPTION
     The  zfs  command configures ZFS datasets within a ZFS storage pool, as de-
     scribed in zpool(1M). A dataset is identified by a unique path  within  the
     ZFS namespace. For example:

       pool/{filesystem,volume,snapshot}

     where the maximum length of a dataset name is MAXNAMELEN (256 bytes).

     A dataset can be one of the following:

     file system    A  standard  POSIX	file  system.  ZFS  file  systems can be
		    mounted within the standard file system namespace and behave
		    like any other file system.

     volume	    A logical volume exported as a raw	or  block  device.  This
		    type  of  dataset  should only be used under special circum-
		    stances. File systems are typically used  in  most	environ-
		    ments. Volumes cannot be used in a non-global zone.

     snapshot	    A  read-only  version  of a file system or volume at a given
		    point in time. It is specified as  filesystem@name	or  vol-
		    ume@name.

   ZFS File System Hierarchy
     A	ZFS  storage  pool is a logical collection of devices that provide space
     for datasets. A storage pool is also the root of the ZFS file system  hier-
     archy.

     The root of the pool can be accessed as a file system, such as mounting and
     unmounting,  taking snapshots, and setting properties. The physical storage
     characteristics, however, are managed by the zpool(1M) command.

     See zpool(1M) for more information on creating and administering pools.

   Snapshots
     A snapshot is a read-only copy of a file system or volume. Snapshots can be
     created extremely quickly, and initially consume no additional space within
     the pool. As data within the active dataset changes, the snapshot	consumes
     more data than would otherwise be shared with the active dataset.

     Snapshots	can  have arbitrary names. Snapshots of volumes can be cloned or
     rolled back, but cannot be accessed independently.

     File system snapshots can be accessed under the  ".zfs/snapshot"  directory
     in  the root of the file system. Snapshots are automatically mounted on de-
     mand and may be unmounted at  regular  intervals.	The  visibility  of  the
     ".zfs" directory can be controlled by the "snapdir" property.

   Clones
     A	clone is a writable volume or file system whose initial contents are the
     same as another dataset. As with snapshots, creating a clone is nearly  in-
     stantaneous, and initially consumes no additional space.

     Clones  can  only be created from a snapshot. When a snapshot is cloned, it
     creates an implicit dependency between the parent and  child.  Even  though
     the  clone is created somewhere else in the dataset hierarchy, the original
     snapshot cannot be destroyed as long as a clone exists. The "origin"  prop-
     erty exposes this dependency, and the destroy command lists any such depen-
     dencies, if they exist.

     The clone parent-child dependency relationship can be reversed by using the
     "promote"	subcommand.  This  causes  the	"origin" file system to become a
     clone of the specified file system, which makes it possible to destroy  the
     file system that the clone was created from.

   Mount Points
     Creating  a  ZFS  file  system is a simple operation, so the number of file
     systems per system will likely be numerous. To cope with this, ZFS automat-
     ically manages mounting and unmounting file systems  without  the	need  to
     edit  the	/etc/vfstab  file.   All  automatically managed file systems are
     mounted by ZFS at boot time.

     By default, file systems are mounted under /path, where path is the name of
     the file system in the ZFS namespace. Directories are created and destroyed
     as needed.

     A file system can also have a mount point set in the "mountpoint" property.
     This directory is created as needed, and ZFS automatically mounts the  file
     system when the "zfs mount -a" command is invoked (without editing /etc/vf-
     stab).  The  mountpoint  property	can  be inherited, so if pool/home has a
     mount point of /export/stuff, then pool/home/user automatically inherits  a
     mount point of /export/stuff/user.

     A	file  system mountpoint property of "none" prevents the file system from
     being mounted.

     If needed, ZFS file systems can also  be  managed	with  traditional  tools
     (mount,  umount,  /etc/vfstab).  If  a  file system's mount point is set to
     "legacy", ZFS makes no attempt to manage the file system, and the	adminis-
     trator is responsible for mounting and unmounting the file system.

   Zones
     A ZFS file system can be added to a non-global zone by using zonecfg's "add
     fs"  subcommand.  A ZFS file system that is added to a non-global zone must
     have its mountpoint property set to legacy.

     The physical properties of an added  file	system	are  controlled  by  the
     global  administrator.  However, the zone administrator can create, modify,
     or destroy files within the added file system, depending on  how  the  file
     system is mounted.

     A	dataset  can  also  be delegated to a non-global zone by using zonecfg's
     "add dataset" subcommand. You cannot delegate a dataset to one zone and the
     children of the same dataset to another zone. The	zone  administrator  can
     change  properties  of  the  dataset  or  any of its children. However, the
     "quota" property is controlled by the global administrator.

     A ZFS volume can be added as  a  device  to  a  non-global  zone  by  using
     zonecfg's	"add  device"  subcommand.  However, its physical properties can
     only be modified by the global administrator.

     For more information about zonecfg syntax, see zonecfg(1M).

     After a dataset is delegated to a non-global zone, the "zoned" property  is
     automatically  set.  A  zoned  file  system cannot be mounted in the global
     zone, since the zone administrator might have to set the mount point to  an
     unacceptable value.

     The  global  administrator  can forcibly clear the "zoned" property, though
     this should be done with extreme care. The global administrator should ver-
     ify that all the mount points are acceptable before clearing the property.

   Native Properties
     Properties are divided into two types, native properties and  user  defined
     properties.  Native properties either export internal statistics or control
     ZFS behavior. In addition, native properties are either editable  or  read-
     only.  User properties have no effect on ZFS behavior, but you can use them
     to annotate datasets in a way that is meaningful in your  environment.  For
     more information about user properties, see the "User Properties" section.

     Every  dataset  has  a  set  of properties that export statistics about the
     dataset as well as control various behavior. Properties are inherited  from
     the  parent  unless overridden by the child. Snapshot properties can not be
     edited; they always inherit their inheritable properties.	Properties  that
     are not applicable to snapshots are not displayed.

     The  values  of numeric properties can be specified using the following hu-
     man-readable suffixes (for example, "k", "KB", "M", "Gb", etc, up to Z  for
     zettabyte). The following are all valid (and equal) specifications:

       "1536M", "1.5g", "1.50GB".

     The  values of non-numeric properties are case sensitive and must be lower-
     case, except for "mountpoint" and "sharenfs".

     The first set of properties  consist  of  read-only  statistics  about  the
     dataset.  These  properties  cannot  be set, nor are they inherited. Native
     properties apply to all dataset types unless otherwise noted.

     type	      The type of dataset: "filesystem",  "volume",  "snapshot",
		      or "clone".

     creation	      The time this dataset was created.

     used	      The  amount  of space consumed by this dataset and all its
		      descendants. This is the value  that  is	checked  against
		      this  dataset's quota and reservation. The space used does
		      not include this dataset's reservation, but does take into
		      account the reservations of any descendant datasets.   The
		      amount  of  space that a dataset consumes from its parent,
		      as well as the amount of space that will be freed if  this
		      dataset  is  recursively	destroyed, is the greater of its
		      space used and its reservation.

		      When snapshots (see the "Snapshots" section) are	created,
		      their  space  is initially shared between the snapshot and
		      the file system, and possibly with previous snapshots.  As
		      the  file system changes, space that was previously shared
		      becomes unique to the snapshot, and counted in  the  snap-
		      shot's  space  used.  Additionally, deleting snapshots can
		      increase the amount of space unique to (and used by) other
		      snapshots.

		      The amount of space used, available,  or	referenced  does
		      not take into account pending changes. Pending changes are
		      generally accounted for within a few seconds. Committing a
		      change to a disk using fsync(3c) or O_SYNC does not neces-
		      sarily  guarantee  that the space usage information is up-
		      dated immediately.

     available	      The amount of space available to the dataset and	all  its
		      children,  assuming that there is no other activity in the
		      pool. Because space is shared within a pool,  availability
		      can  be limited by any number of factors, including physi-
		      cal pool size, quotas,  reservations,  or  other	datasets
		      within the pool.

		      This  property  can  also  be referred to by its shortened
		      column name, "avail".

     referenced       The amount of data that is  accessible  by  this	dataset,
		      which  may or may not be shared with other datasets in the
		      pool. When a snapshot or clone is  created,  it  initially
		      references  the same amount of space as the file system or
		      snapshot it was created from, since its contents are iden-
		      tical.

		      This property can also be referred  to  by  its  shortened
		      column name, "refer".

     compressratio    The compression ratio achieved for this dataset, expressed
		      as  a  multiplier. Compression can be turned on by running
		      "zfs set compression=on dataset".  The  default  value  is
		      "off".

     mounted	      For  file  systems,  indicates  whether the file system is
		      currently mounted. This property can be  either  "yes"  or
		      "no".

     origin	      For  cloned  file  systems  or  volumes, the snapshot from
		      which the clone was created.  The  origin  cannot  be  de-
		      stroyed  (even  with  the  -r  or -f options) so long as a
		      clone exists.

     The following two properties can be set to control the way space  is  allo-
     cated  between  datasets. These properties are not inherited, but do affect
     their descendants.

     quota=size | none

	 Limits the amount of space a dataset and its descendants  can	consume.
	 This  property  enforces a hard limit on the amount of space used. This
	 includes all space consumed by descendants, including file systems  and
	 snapshots.  Setting  a  quota on a descendant of a dataset that already
	 has a quota does not override the ancestor's quota, but rather  imposes
	 an additional limit.

	 Quotas  cannot  be set on volumes, as the "volsize" property acts as an
	 implicit quota.

     reservation=size | none

	 The minimum amount of space guaranteed to a  dataset  and  its  descen-
	 dants.  When  the amount of space used is below this value, the dataset
	 is treated as if it were taking up the amount of space specified by its
	 reservation. Reservations are accounted for  in  the  parent  datasets'
	 space	used, and count against the parent datasets' quotas and reserva-
	 tions.

	 This property can also be referred to by  its	shortened  column  name,
	 "reserv".

     volsize=size

	 For volumes, specifies the logical size of the volume. By default, cre-
	 ating	a volume establishes a reservation of equal size. Any changes to
	 volsize are reflected in an equivalent change to the  reservation.  The
	 volsize  can  only  be set to a multiple of volblocksize, and cannot be
	 zero.

	 The reservation is kept equal to the volume's logical size  to  prevent
	 unexpected  behavior for consumers. Without the reservation, the volume
	 could run out of space, resulting in undefined behavior or data corrup-
	 tion, depending on how the volume is used. These effects can also occur
	 when the volume size is changed while it is in use  (particularly  when
	 shrinking  the  size).  Extreme  care should be used when adjusting the
	 volume size.

	 Though not recommended, a "sparse volume" (also known as  "thin  provi-
	 sioning") can be created by specifying the -s option to the "zfs create
	 -V"  command,	or by changing the reservation after the volume has been
	 created.  A "sparse volume" is a volume where the reservation	is  less
	 then  the volume size. Consequently, writes to a sparse volume can fail
	 with ENOSPC when the pool is low on space. For a sparse volume, changes
	 to volsize are not reflected in the reservation.

     volblocksize=blocksize

	 For volumes, specifies the block size of the volume. The blocksize can-
	 not be changed once the volume has been written, so it should be set at
	 volume creation time. The default blocksize for volumes  is  8  Kbytes.
	 Any power of 2 from 512 bytes to 128 Kbytes is valid.

	 This  property  can  also  be referred to by its shortened column name,
	 "volblock".

     recordsize=size

	 Specifies a suggested block size for files in	the  file  system.  This
	 property is designed solely for use with database workloads that access
	 files	in  fixed-size	records. ZFS automatically tunes block sizes ac-
	 cording to internal algorithms optimized for typical access patterns.

	 For databases that create very large files but  access  them  in  small
	 random  chunks,  these  algorithms  may  be  suboptimal.  Specifying  a
	 "recordsize" greater than or equal to the record size of  the	database
	 can  result  in significant performance gains. Use of this property for
	 general purpose file systems is strongly discouraged, and may adversely
	 affect performance.

	 The size specified must be a power of two greater than or equal to  512
	 and less than or equal to 128 Kbytes.

	 Changing the file system's recordsize only affects files created after-
	 ward; existing files are unaffected.

	 This  property  can  also  be referred to by its shortened column name,
	 "recsize".

     mountpoint=path | none | legacy

	 Controls the mount point used for this  file  system.	See  the  "Mount
	 Points" section for more information on how this property is used.

	 When  the  mountpoint	property  is changed for a file system, the file
	 system and any children that inherit the mount point are unmounted.  If
	 the  new value is "legacy", then they remain unmounted. Otherwise, they
	 are automatically remounted in the new location  if  the  property  was
	 previously "legacy" or "none", or if they were mounted before the prop-
	 erty was changed. In addition, any shared file systems are unshared and
	 shared in the new location.

     sharenfs=on | off | opts

	 Controls  whether  the  file system is shared via NFS, and what options
	 are used. A file system with a sharenfs property of  "off"  is  managed
	 through  traditional  tools  such  as	share(1M),  unshare(1M), and df-
	 stab(4). Otherwise, the file system is  automatically	shared	and  un-
	 shared with the "zfs share" and "zfs unshare" commands. If the property
	 is  set to "on", the share(1M) command is invoked with no options. Oth-
	 erwise, the share(1M) command is invoked with options equivalent to the
	 contents of this property.

	 When the "sharenfs" property is changed for a dataset, the dataset  and
	 any  children	inheriting  the  property are re-shared with the new op-
	 tions, only if the property was  previously  "off",  or  if  they  were
	 shared  before  the property was changed. If the new property is "off",
	 the file systems are unshared.

     shareiscsi=on | off

	 Like the "sharenfs" property, "shareiscsi" indicates whether a ZFS vol-
	 ume is exported as an iSCSI target.  The  acceptable  values  for  this
	 property are "on", "off", and "type=disk".  The default value is "off".
	 In  the  future,  other  target  types might be supported. For example,
	 "tape".

	 You might want to set "shareiscsi=on" for a file system so that all ZFS
	 volumes within the file system are  shared  by  default.  Setting  this
	 property on a file system has no direct effect, however.

     checksum=on | off | fletcher2, | fletcher4 | sha256

	 Controls  the checksum used to verify data integrity. The default value
	 is "on", which automatically selects  an  appropriate	algorithm  (cur-
	 rently,  fletcher2,  but this may change in future releases). The value
	 "off" disables integrity checking on user data. Disabling checksums  is
	 NOT a recommended practice.

     compression=on | off | lzjb | gzip | gzip-N

	 Controls  the	compression  algorithm used for this dataset. The "lzjb"
	 compression algorithm is optimized for performance while providing  de-
	 cent data compression. Setting compression to "on" uses the "lzjb" com-
	 pression algorithm. The "gzip" compression algorithm uses the same com-
	 pression  as  the gzip(1) command.  You can specify the "gzip" level by
	 using the value "gzip-N", where N is an integer from 1 (fastest)  to  9
	 (best	compression  ratio). Currently, "gzip" is equivalent to "gzip-6"
	 (which is also the default for gzip(1)).

	 This property can also be referred to	by  its  shortened  column  name
	 "compress".

     atime=on | off

	 Controls  whether  the  access  time for files is updated when they are
	 read. Turning this property off avoids  producing  write  traffic  when
	 reading  files  and can result in significant performance gains, though
	 it might confuse mailers and other similar utilities. The default value
	 is "on".

     devices=on | off

	 Controls whether device nodes can be opened on this  file  system.  The
	 default value is "on".

     exec=on | off

	 Controls  whether  processes can be executed from within this file sys-
	 tem. The default value is "on".

     setuid=on | off

	 Controls whether the set-UID bit is respected for the file system.  The
	 default value is "on".

     readonly=on | off

	 Controls  whether  this  dataset  can be modified. The default value is
	 "off".

	 This property can also be referred to by  its	shortened  column  name,
	 "rdonly".

     zoned=on | off

	 Controls whether the dataset is managed from a non-global zone. See the
	 "Zones" section for more information. The default value is "off".

     snapdir=hidden | visible

	 Controls  whether the ".zfs" directory is hidden or visible in the root
	 of the file system as discussed in the "Snapshots" section. The default
	 value is "hidden".

     aclmode=discard | groupmask | passthrough

	 Controls how an ACL is modified during chmod(2). A file system with  an
	 "aclmode"  property  of  "discard"  deletes all ACL entries that do not
	 represent the mode of the file. An "aclmode"  property  of  "groupmask"
	 (the  default)  reduces  user or group permissions. The permissions are
	 reduced, such that they are no greater than the group permission  bits,
	 unless  it  is  a  user entry that has the same UID as the owner of the
	 file or directory. In this case, the ACL  permissions	are  reduced  so
	 that they are no greater than owner permission bits. A file system with
	 an  "aclmode"	property of "passthrough" indicates that no changes will
	 be made to the ACL other than generating the necessary ACL  entries  to
	 represent the new mode of the file or directory.

     aclinherit=discard | noallow | secure | passthrough

	 Controls  how	ACL entries are inherited when files and directories are
	 created. A file system with an "aclinherit" property of "discard"  does
	 not  inherit  any ACL entries. A file system with an "aclinherit" prop-
	 erty value of "noallow" only  inherits  inheritable  ACL  entries  that
	 specify  "deny"  permissions. The property value "secure" (the default)
	 removes the "write_acl" and "write_owner" permissions when the ACL  en-
	 try  is inherited. A file system with an "aclinherit" property value of
	 "passthrough" inherits all inheritable ACL entries without any  modifi-
	 cations made to the ACL entries when they are inherited.

     canmount=on | off

	 If  this  property  is set to "off", the file system cannot be mounted,
	 and is ignored by "zfs mount  -a".  This  is  similar	to  setting  the
	 "mountpoint"  property  to  "none", except that the dataset still has a
	 normal "mountpoint"  property	which  can  be	inherited.  This  allows
	 datasets  to  be  used solely as a mechanism to inherit properties. One
	 use case is to have two  logically  separate  datasets  have  the  same
	 mountpoint,  so  that	the children of both datasets appear in the same
	 directory, but may have different inherited  characteristics.	The  de-
	 fault value is "on".

	 This property is not inherited.

     xattr=on | off

	 Controls  whether extended attributes are enabled for this file system.
	 The default value is "on".

     copies=1 | 2 | 3

	 Controls the number of copies of data stored for  this  dataset.  These
	 copies  are in addition to any redundancy provided by the pool, for ex-
	 ample, mirroring or raid-z. The copies are stored on  different  disks,
	 if  possible. The space used by multiple copies is charged to the asso-
	 ciated file and dataset, changing  the  "used"  property  and	counting
	 against quotas and reservations.

	 Changing  this property only affects newly-written data. Therefore, set
	 this property at file system creation time by using  the  "-o	copies="
	 option.

     jailed=on | off

	 Controls whether the dataset is managed from within a jail. The default
	 value is "off".

   iscsioptions
     This  read-only property, which is hidden, is used by the iSCSI target dae-
     mon to store persistent information, such as the IQN. It cannot  be  viewed
     or modified using the zfs command. The contents are not intended for exter-
     nal consumers.

   Temporary Mount Point Properties
     When  a  file system is mounted, either through mount(1M) for legacy mounts
     or the "zfs mount" command for normal file systems, its mount  options  are
     set  according  to  its  properties. The correlation between properties and
     mount options is as follows:

	   PROPERTY		   MOUNT OPTION
	   devices		   devices/nodevices
	   exec 		   exec/noexec
	   readonly		   ro/rw
	   setuid		   setuid/nosetuid
	   xattr		   xattr/noxattr

     In addition, these options can be set on a per-mount basis using the -o op-
     tion, without affecting the property that is stored  on  disk.  The  values
     specified	on  the  command line override the values stored in the dataset.
     The -nosuid option is an alias for "nodevices,nosetuid".  These  properties
     are reported as "temporary" by the "zfs get" command. If the properties are
     changed  while the dataset is mounted, the new setting overrides any tempo-
     rary settings.

   User Properties
     In addition to the standard native properties, ZFS supports arbitrary  user
     properties.  User	properties  have no effect on ZFS behavior, but applica-
     tions or administrators can use them to annotate datasets.

     User property names must contain a colon (":")  character,  to  distinguish
     them from native properties. They might contain lowercase letters, numbers,
     and  the  following punctuation characters: colon (":"), dash ("-"), period
     ("."), and underscore ("_"). The expected convention is that  the	property
     name is divided into two portions such as "module:property", but this name-
     space  is not enforced by ZFS. User property names can be at most 256 char-
     acters, and cannot begin with a dash ("-").

     When making programmatic use of user properties, it is  strongly  suggested
     to  use  a  reversed  DNS	domain name for the module component of property
     names to reduce the chance that two  independently-developed  packages  use
     the  same	property  name	for different purposes. Property names beginning
     with "com.sun." are reserved for use by Sun Microsystems.

     The values of user properties are arbitrary strings, are always  inherited,
     and  are  never  validated.  All of the commands that operate on properties
     ("zfs list", "zfs get", "zfs set", etc.) can be used to manipulate both na-
     tive properties and user properties.  Use	the  "zfs  inherit"  command  to
     clear  a  user  property  .  If  the  property is not defined in any parent
     dataset, it is removed entirely. Property values are limited to 1024  char-
     acters.

   Volumes as Swap or Dump Devices
     To  set up a swap area, create a ZFS volume of a specific size and then en-
     able swap on that device. For more information, see the EXAMPLES section.

     Do not swap to a file on a ZFS file system. A ZFS swap  file  configuration
     is not supported.

     Using a ZFS volume as a dump device is not supported.

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

     zfs ?

	 Displays a help message.

     zfs create [[-o property=value]...] filesystem

	 Creates a new ZFS file system. The file system is automatically mounted
	 according to the "mountpoint" property inherited from the parent.

	 -o property=value    Sets the specified property as if "zfs  set  prop-
			      erty=value"  was	invoked  at  the  same	time the
			      dataset was created. Any editable ZFS property can
			      also be set at creation time. Multiple -o  options
			      can  be  specified.  An  error results if the same
			      property is specified in multiple -o options.

     zfs create [-s] [-b blocksize] [[-o property=value]...] -V size volume

	 Creates a volume of the given size. The volume is exported as	a  block
	 device in /dev/zvol/{dsk,rdsk}/path, where path is the name of the vol-
	 ume  in  the ZFS namespace. The size represents the logical size as ex-
	 ported by the device. By default, a reservation of equal size	is  cre-
	 ated.

	 size  is  automatically  rounded up to the nearest 128 Kbytes to ensure
	 that the volume has an integral number of blocks regardless  of  block-
	 size.

	 -s		      Creates  a  sparse volume with no reservation. See
			      "volsize" in the	Native	Properties  section  for
			      more information about sparse volumes.

	 -o property=value    Sets  the  specified property as if "zfs set prop-
			      erty=value" was  invoked	at  the  same  time  the
			      dataset was created. Any editable ZFS property can
			      also  be set at creation time. Multiple -o options
			      can be specified. An error  results  if  the  same
			      property is specified in multiple -o options.

	 -b blocksize	      Equivalent to "-o volblocksize=blocksize". If this
			      option  is  specified in conjunction with "-o vol-
			      blocksize", the resulting behavior is undefined.

     zfs destroy [-rRf] filesystem|volume|snapshot

	 Destroys the given dataset. By default, the command unshares  any  file
	 systems  that	are currently shared, unmounts any file systems that are
	 currently mounted, and refuses to destroy a dataset that has active de-
	 pendents (children, snapshots, clones).

	 -r    Recursively destroy all children. If a snapshot is specified, de-
	       stroy all snapshots with this name in descendant file systems.

	 -R    Recursively destroy all dependents, including cloned file systems
	       outside the target hierarchy. If a snapshot is specified, destroy
	       all snapshots with this name in descendant file systems.

	 -f    Force an unmount of any file systems using the "unmount -f"  com-
	       mand.  This option has no effect on non-file systems or unmounted
	       file systems.

	 Extreme care should be taken when applying either the -r or the -f  op-
	 tions,  as  they  can	destroy large portions of a pool and cause unex-
	 pected behavior for mounted file systems in use.

     zfs clone snapshot filesystem|volume

	 Creates a clone of the given snapshot. See the "Clones" section for de-
	 tails. The target dataset can be located anywhere in the ZFS hierarchy,
	 and is created as the same type as the original.

     zfs promote filesystem

	 Promotes a clone file system to no longer be dependent on its	"origin"
	 snapshot.  This  makes  it possible to destroy the file system that the
	 clone was created from. The clone parent-child dependency  relationship
	 is  reversed,	so  that the "origin" file system becomes a clone of the
	 specified file system.

	 The snaphot that was cloned, and any snapshots previous to  this  snap-
	 shot,	are  now  owned  by the promoted clone. The space they use moves
	 from the "origin" file system to the promoted clone,  so  enough  space
	 must  be available to accommodate these snapshots. No new space is con-
	 sumed by this operation, but the space accounting is adjusted. The pro-
	 moted clone must not have any conflicting snapshot names  of  its  own.
	 The  "rename"	subcommand  can  be used to rename any conflicting snap-
	 shots.

     zfs rename filesystem|volume|snapshot filesystem|volume|snapshot

	 Renames the given dataset. The new target can be  located  anywhere  in
	 the  ZFS hierarchy, with the exception of snapshots. Snapshots can only
	 be renamed within the parent file system or  volume.  When  renaming  a
	 snapshot,  the  parent  file system of the snapshot does not need to be
	 specified as part of the second argument. Renamed file systems can  in-
	 herit	new mount points, in which case they are unmounted and remounted
	 at the new mount point.

     zfs snapshot [-r] filesystem@name|volume@name

	 Creates a snapshot with the given name. See the "Snapshots" section for
	 details.

	 -r    Recursively create snapshots of all  descendant	datasets.  Snap-
	       shots  are taken atomically, so that all recursive snapshots cor-
	       respond to the same moment in time.

     zfs rollback [-rRf] snapshot

	 Roll back the given dataset to a previous snapshot. When a  dataset  is
	 rolled back, all data that has changed since the snapshot is discarded,
	 and  the  dataset  reverts to the state at the time of the snapshot. By
	 default, the command refuses to roll back to a snapshot other than  the
	 most  recent one. In order to do so, all intermediate snapshots must be
	 destroyed by specifying the -r option. The file system is unmounted and
	 remounted, if necessary.

	 -r    Recursively destroy any snapshots more recent than the one speci-
	       fied.

	 -R    Recursively destroy any more recent snapshots,  as  well  as  any
	       clones of those snapshots.

	 -f    Force  an unmount of any file systems using the "unmount -f" com-
	       mand.

     zfs list [-rH] [-o prop[,prop] ]... [ -t type[,type]...] [ -s prop [-s
     prop]... [ -S prop [-S prop]... [filesystem|volume|snapshot|/path-
     name|./pathname ...

	 Lists the property information for the given datasets in tabular  form.
	 If  specified,  you can list property information by the absolute path-
	 name or the relative pathname. By default, all datasets  are  displayed
	 and contain the following fields:

	   name,used,available,referenced,mountpoint

	 -H	    Used  for  scripting mode. Do not print headers and separate
		    fields by a single tab instead of arbitrary whitespace.

	 -r	    Recursively display any children of the dataset on the  com-
		    mand line.

	 -o prop    A  comma-separated	list of properties to display. The prop-
		    erty must be one of the properties described in the  "Native
		    Properties"  section, or the special value "name" to display
		    the dataset name.

	 -s prop    A property to use for sorting the output by  column  in  as-
		    cending  order based on the value of the property. The prop-
		    erty must be one of the properties described in the "Proper-
		    ties" section, or the special value "name" to  sort  by  the
		    dataset  name.  Multiple  properties can be specified at one
		    time using multiple -s property options. Multiple -s options
		    are evaluated from left to right in decreasing order of  im-
		    portance.

		    The following is a list of sorting criteria:

			o      Numeric types sort in numeric order.

			o      String types sort in alphabetical order.

			o      Types  inappropriate  for  a row sort that row to
			       the literal bottom, regardless of  the  specified
			       ordering.

			o      If  no sorting options are specified the existing
			       behavior of "zfs list" is preserved.

	 -S prop    Same as the -s option, but sorts by property  in  descending
		    order.

	 -t type    A  comma-separated list of types to display, where "type" is
		    one of "filesystem", "snapshot" or	"volume".  For	example,
		    specifying "-t snapshot" displays only snapshots.

     zfs set property=value filesystem|volume ...

	 Sets  the property to the given value for each dataset. Only some prop-
	 erties can be edited. See the "Properties" section for more information
	 on what properties can be set and acceptable values. Numeric values can
	 be specified as exact values, or in a human-readable form with a suffix
	 of "B", "K", "M", "G", "T", "P", "E", "Z" (for bytes,	Kbytes,  Mbytes,
	 gigabytes,  terabytes,  petabytes,  exabytes,	or  zettabytes,  respec-
	 tively). Properties cannot be set on snapshots.

     zfs get [-rHp] [-o field[,field]...] [-s source[,source]...] all | prop-
     erty[,property]... filesystem|volume|snapshot ...

	 Displays properties for the given datasets. If no datasets  are  speci-
	 fied, then the command displays properties for all datasets on the sys-
	 tem. For each property, the following columns are displayed:

	       name	 Dataset name
	       property  Property name
	       value	 Property value
	       source	 Property source. Can either be local, default,
			 temporary, inherited, or none (-).

	 All  columns are displayed by default, though this can be controlled by
	 using the -o option. This command takes a comma-separated list of prop-
	 erties as described in the "Native Properties"  and  "User  Properties"
	 sections.

	 The  special  value "all" can be used to display all properties for the
	 given dataset.

	 -r	      Recursively display properties for any children.

	 -H	      Display output in a form more easily  parsed  by	scripts.
		      Any  headers  are omitted, and fields are explicitly sepa-
		      rated by a single tab instead of an  arbitrary  amount  of
		      space.

	 -o field     A  comma-separated list of columns to display. "name,prop-
		      erty,value,source" is the default value.

	 -s source    A comma-separated list of sources to display. Those  prop-
		      erties  coming from a source other than those in this list
		      are ignored. Each source must be	one  of  the  following:
		      "local,default,inherited,temporary,none".    The	 default
		      value is all sources.

	 -p	      Display numbers in parsable (exact) values.

     zfs inherit [-r] property filesystem|volume ...

	 Clears the specified property, causing it to be inherited from  an  an-
	 cestor.  If no ancestor has the property set, then the default value is
	 used. See the "Properties" section for a listing of default values, and
	 details on which properties can be inherited.

	 -r    Recursively inherit the given property for all children.

     zfs mount

	 Displays all ZFS file systems currently mounted.

     zfs mount[-o opts] [-O] -a

	 Mounts all available ZFS file systems. Invoked automatically as part of
	 the boot process.

	 -o opts    An optional comma-separated list of  mount	options  to  use
		    temporarily  for  the duration of the mount. See the "Tempo-
		    rary Mount Point Properties" section for details.

	 -O	    Perform an overlay mount. See mount(1M)  for  more	informa-
		    tion.

     zfs mount [-o opts] [-O] filesystem

	 Mounts  a specific ZFS file system. This is typically not necessary, as
	 file systems are automatically mounted when they  are	created  or  the
	 mountpoint property has changed. See the "Mount Points" section for de-
	 tails.

	 -o opts    An	optional  comma-separated  list  of mount options to use
		    temporarily for the duration of the mount. See  the  "Tempo-
		    rary Mount Point Properties" section for details.

	 -O	    Perform  an  overlay  mount. See mount(1M) for more informa-
		    tion.

     zfs unmount -a

	 Unmounts all currently mounted ZFS file systems. Invoked  automatically
	 as part of the shutdown process.

     zfs unmount [-f] filesystem|mountpoint

	 Unmounts the given file system. The command can also be given a path to
	 a ZFS file system mount point on the system.

	 -f    Forcefully  unmount  the  file system, even if it is currently in
	       use.

     zfs share -a

	 Shares all available ZFS file systems. This is invoked automatically as
	 part of the boot process.

     zfs share filesystem

	 Shares a specific ZFS file system according to the "sharenfs" property.
	 File systems are shared when the "sharenfs" property is set.

     zfs unshare -a

	 Unshares all currently shared ZFS file systems. This is  invoked  auto-
	 matically as part of the shutdown process.

     zfs unshare [-F] filesystem|mountpoint

	 Unshares the given file system. The command can also be given a path to
	 a ZFS file system shared on the system.

	 -F    Forcefully  unshare  the  file system, even if it is currently in
	       use.

     zfs send [-i snapshot1] snapshot2

	 Creates a stream representation of snapshot2, which is written to stan-
	 dard output. The output can be redirected to a file or to  a  different
	 system  (for example, using ssh(1). By default, a full stream is gener-
	 ated.

	 -i snapshot1	 Generate an incremental stream from snapshot1 to  snap-
			 shot2.  The  incremental source snapshot1 can be speci-
			 fied as the last component of the  snapshot  name  (for
			 example,  the part after the "@"), and it is assumed to
			 be from the same file system as snapshot2.

     The format of the stream is evolving. No backwards compatibility is guaran-
     teed. You may not be able to receive your streams	on  future  versions  of
     ZFS.

     zfs receive [-vnF] filesystem|volume|snapshot
     zfs receive [-vnF] -d filesystem

	 Creates  a  snapshot whose contents are as specified in the stream pro-
	 vided on standard input. If a full stream is received, then a new  file
	 system  is  created  as  well. Streams are created using the "zfs send"
	 subcommand, which by default creates a full stream. "zfs recv"  can  be
	 used as an alias for "zfs receive".

	 If  an incremental stream is received, then the destination file system
	 must already exist, and its most recent snapshot must match the  incre-
	 mental  stream's  source.  The  destination  file system and all of its
	 child file systems are unmounted and cannot be accessed during the  re-
	 ceive operation.

	 The  name  of	the  snapshot  (and file system, if a full stream is re-
	 ceived) that this subcommand creates depends on the argument  type  and
	 the -d option.

	 If  the argument is a snapshot name, the specified snapshot is created.
	 If the argument is a file system or volume name, a  snapshot  with  the
	 same name as the sent snapshot is created within the specified filesys-
	 tem or volume.  If the -d option is specified, the snapshot name is de-
	 termined  by  appending  the  sent  snapshot's  name  to  the specified
	 filesystem. If the -d option is specified, any  required  file  systems
	 within the specified one are created.

	 -d    Use  the  name  of the sent snapshot to determine the name of the
	       new snapshot as described in the paragraph above.

	 -v    Print verbose information about the stream and the time	required
	       to perform the receive operation.

	 -n    Do  not	actually  receive the stream. This can be useful in con-
	       junction with the -v option to determine what  name  the  receive
	       operation would use.

	 -F    Force  a  rollback  of the filesystem to the most recent snapshot
	       before performing the receive operation.

     zfs jail jailid filesystem

	 Attaches the given file system to the given jail. From now on this file
	 system tree can be managed from within a jail if the "jailed"	property
	 has  been  set.   To  use  this functionality, sysctl security.jail.en-
	 force_statfs should be set to 0 and sysctl  security.jail.mount_allowed
	 should be set to 1.

     zfs unjail jailid filesystem

	 Detaches the given file system from the given jail.

EXAMPLES
     Example 1 Creating a ZFS File System Hierarchy

     The  following  commands  create a file system named "pool/home" and a file
     system named "pool/home/bob". The mount point "/export/home" is set for the
     parent file system, and automatically inherited by the child file system.

       # zfs create pool/home
       # zfs set mountpoint=/export/home pool/home
       # zfs create pool/home/bob

     Example 2 Creating a ZFS Snapshot

     The following command creates a snapshot named "yesterday".  This	snapshot
     is  mounted  on  demand in the ".zfs/snapshot" directory at the root of the
     "pool/home/bob" file system.

       # zfs snapshot pool/home/bob@yesterday

     Example 3 Taking and destroying multiple snapshots

     The following command creates snapshots named  "yesterday"  of  "pool/home"
     and  all of its descendant file systems. Each snapshot is mounted on demand
     in the ".zfs/snapshot" directory at the root of its file system. The second
     command destroys the newly created snapshots.

       # zfs snapshot -r pool/home@yesterday
       # zfs destroy -r pool/home@yesterday

     Example 4 Turning Off Compression

     The following commands turn compression off  for  all  file  systems  under
     "pool/home", but explicitly turns it on for "pool/home/anne".

       # zfs set compression=off pool/home
       # zfs set compression=on pool/home/anne

     Example 5 Listing ZFS Datasets

     The following command lists all active file systems and volumes in the sys-
     tem.

       # zfs list

	 NAME			   USED  AVAIL	REFER  MOUNTPOINT
	 pool			   100G   60G	    -  /pool
	 pool/home		   100G   60G	    -  /export/home
	 pool/home/bob		    40G   60G	  40G  /export/home/bob
	 pool/home/bob@yesterday     3M     -	  40G  -
	 pool/home/anne 	    60G   60G	  40G  /export/home/anne

     Example 6 Setting a Quota on a ZFS File System

     The following command sets a quota of 50 gbytes for "pool/home/bob".

       # zfs set quota=50G pool/home/bob

     Example 7 Listing ZFS Properties

     The following command lists all properties for "pool/home/bob".

       # zfs get all pool/home/bob

	 NAME		PROPERTY       VALUE		      SOURCE
	 pool/home/bob	type	       filesystem	      -
	 pool/home/bob	creation       Fri Feb 23 14:20 2007  -
	 pool/home/bob	used	       24.5K		      -
	 pool/home/bob	available      50.0G		      -
	 pool/home/bob	referenced     24.5K		      -
	 pool/home/bob	compressratio  1.00x		      -
	 pool/home/bob	mounted        yes		      -
	 pool/home/bob	quota	       50G		      local
	 pool/home/bob	reservation    none		      default
	 pool/home/bob	recordsize     128K		      default
	 pool/home/bob	mountpoint     /pool/home/bob	      default
	 pool/home/bob	sharenfs       off		      default
	 pool/home/bob	shareiscsi     off		      default
	 pool/home/bob	checksum       on		      default
	 pool/home/bob	compression    off		      default
	 pool/home/bob	atime	       on		      default
	 pool/home/bob	devices        on		      default
	 pool/home/bob	exec	       on		      default
	 pool/home/bob	setuid	       on		      default
	 pool/home/bob	readonly       off		      default
	 pool/home/bob	zoned	       off		      default
	 pool/home/bob	snapdir        hidden		      default
	 pool/home/bob	aclmode        groupmask	      default
	 pool/home/bob	aclinherit     secure		      default
	 pool/home/bob	canmount       on		      default
	 pool/home/bob	xattr	       on		      default

     The following command gets a single property value.

       # zfs get -H -o value compression pool/home/bob
       on

     The  following  command  lists  all  properties  with  local  settings  for
     "pool/home/bob".

       # zfs get -r -s local -o name,property,value all pool/home/bob

	 NAME		  PROPERTY	VALUE
	 pool		  compression	on
	 pool/home	  checksum	off

     Example 8 Rolling Back a ZFS File System

     The following command reverts the contents of "pool/home/anne" to the snap-
     shot named "yesterday", deleting all intermediate snapshots.

       # zfs rollback -r pool/home/anne@yesterday

     Example 9 Creating a ZFS Clone

     The following command creates a writable file system whose initial contents
     are the same as "pool/home/bob@yesterday".

       # zfs clone pool/home/bob@yesterday pool/clone

     Example 10 Promoting a ZFS Clone

     The following commands illustrate how to test out changes to a file system,
     and then replace the original file  system  with  the  changed  one,  using
     clones, clone promotion, and renaming:

       # zfs create pool/project/production
	populate /pool/project/production with data
       # zfs snapshot pool/project/production@today
       # zfs clone pool/project/production@today pool/project/beta
	make changes to /pool/project/beta and test them
       # zfs promote pool/project/beta
       # zfs rename pool/project/production pool/project/legacy
       # zfs rename pool/project/beta pool/project/production
	once the legacy version is no longer needed, it can be
	destroyed
       # zfs destroy pool/project/legacy

     Example 11 Inheriting ZFS Properties

     The  following  command  causes "pool/home/bob" and "pool/home/anne" to in-
     herit the "checksum" property from their parent.

       # zfs inherit checksum pool/home/bob pool/home/anne

     Example 12 Remotely Replicating ZFS Data

     The following commands send a full stream and then an incremental stream to
     a remote machine, restoring them into "poolB/received/fs@a" and  "poolB/re-
     ceived/fs@b", respectively. "poolB" must contain the file system "poolB/re-
     ceived", and must not initially contain "poolB/received/fs".

       # zfs send pool/fs@a | \
	 ssh host zfs receive poolB/received/fs@a
       # zfs send -i a pool/fs@b | ssh host \
	 zfs receive poolB/received/fs

     Example 13 Using the  zfs receive -d Option

     The  following command sends a full stream of "poolA/fsA/fsB@snap" to a re-
     mote  machine,  receiving	it   into   "poolB/received/fsA/fsB@snap".   The
     "fsA/fsB@snap"  portion  of the received snapshot's name is determined from
     the name of the  sent  snapshot.  "poolB"	must  contain  the  file  system
     "poolB/received".	If  "poolB/received/fsA" does not exist, it will be cre-
     ated as an empty file system.

       # zfs send poolA/fsA/fsB@snap | \
	 ssh host zfs receive -d poolB/received

     Example 14 Creating a ZFS volume as a Swap Device

     The following example shows how to create a 5-Gbyte ZFS volume and then add
     the volume as a swap device.

       # zfs create  -V 5gb tank/vol
       # swap -a /dev/zvol/dsk/tank/vol

     Example 15 Setting User Properties

     The  following example sets the user defined "com.example:department" prop-
     erty for a dataset.

       # zfs set com.example:department=12345 tank/accounting

     Example 16 Creating a ZFS Volume as a iSCSI Target Device

     The following example shows how to create a ZFS volume as an iSCSI target.

       # zfs create -V 2g pool/volumes/vol1
       # zfs set shareiscsi=on pool/volumes/vol1
       # iscsitadm list target
       Target: pool/volumes/vol1
       iSCSI Name:
       iqn.1986-03.com.sun:02:7b4b02a6-3277-eb1b-e686-a24762c52a8c
       Connections: 0

     After the iSCSI target is created, set up the iSCSI initiator. For more in-
     formation about the Solaris iSCSI initiator, see the Solaris Administration
     Guide: Devices and File Systems.

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
     gzip(1), ssh(1), mount(1M), share(1M), unshare(1M), zonecfg(1M), zpool(1M),
     chmod(2), stat(2), fsync(3c), dfstab(4), attributes(5)

SunOS 5.11			   16 Mar 2007				 zfs(1M)

home | help