Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

       zfs - configures	ZFS file systems

       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

       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

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


       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  cir-
		      cumstances.  File	 systems  are  typically  used in most
		      environments. Volumes cannot be  used  in	 a  non-global

       snapshot	      A	 read-only  version  of	 a  file system	or volume at a
		      given point in time. It is specified as  filesystem@name
		      or volume@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 hierarchy.

       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.

       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"	direc-
       tory  in	 the  root  of	the  file  system. Snapshots are automatically
       mounted on demand and may be unmounted at regular intervals. The	 visi-
       bility of the ".zfs" directory can be controlled	by the "snapdir" prop-

       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 instantaneous, 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" property exposes this dependency, and the destroy  command
       lists any such dependencies, 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
       automatically manages mounting and unmounting file systems without  the
       need to edit the	/etc/vfstab file.  All automatically managed file sys-
       tems 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" prop-
       erty. This directory is created as needed, and ZFS automatically	mounts
       the file	system when the	"zfs mount -a"	command	 is  invoked  (without
       editing	/etc/vfstab).  The mountpoint property can be inherited, so if
       pool/home has a mount point of /export/stuff, then pool/home/user auto-
       matically 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
       administrator  is responsible for mounting and unmounting the file sys-

       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, mod-
       ify, 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 administra-
       tor can change properties of the	dataset	or any of its  children.  How-
       ever, 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 verify 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.	 Prop-
       erties that are not applicable to snapshots are not displayed.

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

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

       The values of non-numeric properties are	case  sensitive	 and  must  be
       lowercase, 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",	"snap-
			shot", 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 reserva-
			tion, 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 cre-
			ated, their space  is  initially  shared  between  the
			snapshot and the file system, and possibly with	previ-
			ous snapshots. As the file system changes, space  that
			was  previously	shared becomes unique to the snapshot,
			and counted in the snapshot's  space  used.  Addition-
			ally,  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  sec-
			onds. Committing a change to a disk using fsync(3c) or
			O_SYNC does not	necessarily guarantee that  the	 space
			usage information is updated 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 physical 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 ini-
			tially references the same amount of space as the file
			system or snapshot it was created from,	since its con-
			tents are identical.

			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
			destroyed (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
       allocated 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 con-
	   sume. 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 reservations.

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


	   For	volumes, specifies the logical size of the volume. By default,
	   creating 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 volblock-
	   size, and cannot be zero.

	   The	reservation is kept equal to the volume's logical size to pre-
	   vent	unexpected behavior for	consumers.  Without  the  reservation,
	   the	volume could run out of	space, resulting in undefined behavior
	   or data corruption, 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 pro-
	   visioning") 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 reserva-
	   tion	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 reserva-


	   For volumes,	specifies the block size of the	volume.	The  blocksize
	   cannot 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,


	   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 according to internal algorithms optimized for	typical	access

	   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	 data-
	   base	can result in significant performance gains. Use of this prop-
	   erty	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
	   afterward; existing files are unaffected.

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

       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.	Other-
	   wise, they are automatically	remounted in the new location  if  the
	   property was	previously "legacy" or "none", or if they were mounted
	   before the property was changed. In addition, any shared file  sys-
	   tems	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 dfstab(4). Otherwise, the file system is automati-
	   cally  shared  and  unshared	with the "zfs share" and "zfs unshare"
	   commands. If	the property is	set to "on", the share(1M) command  is
	   invoked  with  no  options.	Otherwise,  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
	   options, 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
	   volume  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
	   (currently, 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 decent data compression. Setting compression to "on" uses
	   the	"lzjb" compression algorithm. The "gzip" compression algorithm
	   uses	the same compression 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

       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
	   system. 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

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

       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

       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 per-
	   mission   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 "dis-
	   card" does not inherit any ACL  entries.  A	file  system  with  an
	   "aclinherit"	 property 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 entry is inherited.	A file system with  an
	   "aclinherit"	property value of "passthrough"	inherits all inherita-
	   ble ACL entries without any modifications 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  set-
	   ting	 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	default	value is "on".

	   This	property is not	inherited.

       xattr=on	| off

	   Controls whether extended attributes	are enabled for	this file sys-
	   tem.	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 example, mirroring	or raid-z. The copies  are  stored  on
	   different  disks, if	possible. The space used by multiple copies is
	   charged to the associated 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".

       This read-only property,	which is hidden, is used by the	 iSCSI	target
       daemon  to  store persistent information, such as the IQN. It cannot be
       viewed or modified using	the zfs	command. The contents are not intended
       for external 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:

	     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
       option, without affecting the property that is stored on	disk. The val-
       ues 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 temporary settings.

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

       User property names must	contain	a colon	(":")  character,  to  distin-
       guish  them  from  native properties. They might	contain	lowercase let-
       ters, 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	 "mod-
       ule:property", but this namespace is not	enforced by ZFS. User property
       names can be at most 256	characters,  and  cannot  begin	 with  a  dash

       When  making  programmatic  use of user properties, it is strongly sug-
       gested 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 Microsys-

       The values of user properties are arbitrary strings, are	always	inher-
       ited,  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	 native	 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 characters.

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

       Do not swap to a	file on	a ZFS file system. A ZFS swap file  configura-
       tion is not supported.

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

       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

	   -o property=value	Sets the specified property  as	 if  "zfs  set
				property=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 volume in the	ZFS namespace. The size	represents the logical
	   size	 as exported by	the device. By default,	a reservation of equal
	   size	is created.

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

	   -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
				property=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 volblocksize", the resulting  behavior  is

       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 dependents (children, snapshots, clones).

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

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

	   -f	 Force	an  unmount of any file	systems	using the "unmount -f"
		 command. 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
	   options, as they can	destroy	large portions of  a  pool  and	 cause
	   unexpected behavior for mounted file	systems	in use.

       zfs clone snapshot filesystem|volume

	   Creates a clone of the given	snapshot. See the "Clones" section for
	   details. 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 "ori-
	   gin"	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
	   snapshot, 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 consumed by this operation, but the space accounting
	   is adjusted.	The promoted clone must	not have any conflicting snap-
	   shot	 names	of  its	 own.  The  "rename" subcommand	can be used to
	   rename any conflicting snapshots.

       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 inherit 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.
		 Snapshots are taken atomically, so that all  recursive	 snap-
		 shots correspond 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	 snap-
	   shot	 other than the	most recent one. In order to do	so, all	inter-
	   mediate 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

	   -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"

       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 abso-
	   lute	pathname or the	relative pathname. By  default,	 all  datasets
	   are displayed and contain the following fields:


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

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

	   -o prop    A	comma-separated	list of	 properties  to	 display.  The
		      property	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
		      ascending	order based on the value of the	property.  The
		      property	must be	one of the properties described	in the
		      "Properties" 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 importance.

		      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 descend-
		      ing 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	 snap-

       zfs set property=value filesystem|volume	...

	   Sets	 the  property	to the given value for each dataset. Only some
	   properties 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, respectively). Properties cannot be	set on

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

	   Displays  properties	 for  the  given  datasets. If no datasets are
	   specified, then the command displays	properties for all datasets on
	   the system. 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  properties  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  separated  by  a  single tab instead of an
			arbitrary amount of space.

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

	   -s source	A  comma-separated  list  of sources to	display. Those
			properties 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
	   ancestor. 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 "Tem-
		      porary Mount Point Properties" section for details.

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

       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 details.

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

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

       zfs unmount -a

	   Unmounts all	currently mounted ZFS file systems. Invoked  automati-
	   cally 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 automati-
	   cally as part of the	boot process.

       zfs share filesystem

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

       zfs unshare -a

	   Unshares  all  currently  shared  ZFS file systems. This is invoked
	   automatically 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
	   standard  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 generated.

	   -i snapshot1	   Generate  an	 incremental  stream from snapshot1 to
			   snapshot2. The incremental source snapshot1 can  be
			   specified  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 snap-

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

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

	   Creates a snapshot whose contents are as specified  in  the	stream
	   provided  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 incremental stream's source. The	destination  file  system  and
	   all	of its child file systems are unmounted	and cannot be accessed
	   during the receive operation.

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

	   If the argument is a	snapshot name, the specified snapshot is  cre-
	   ated.  If  the argument is a	file system or volume name, a snapshot
	   with	the same name as the sent snapshot is created within the spec-
	   ified  filesystem  or  volume.   If the -d option is	specified, the
	   snapshot name is determined 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
		 conjunction  with  the	 -v  option to determine what name the
		 receive operation would use.

	   -F	 Force a rollback of the filesystem to the most	 recent	 snap-
		 shot 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 secu-
	   rity.jail.enforce_statfs should  be	set  to	 0  and	 sysctl	 secu-
	   rity.jail.mount_allowed should be set to 1.

       zfs unjail jailid filesystem

	   Detaches the	given file system from the given jail.

       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	 snap-
       shot  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

	 # zfs list

	   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

	   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

       The  following  command	lists  all  properties with local settings for

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

	   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
       snapshot	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 con-
       tents 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
	 # zfs destroy pool/project/legacy

       Example 11 Inheriting ZFS Properties

       The following command causes "pool/home/bob"  and  "pool/home/anne"  to
       inherit 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/received/fs@b", respectively. "poolB" must contain the file
       system	"poolB/received",   and	   must	   not	  initially    contain

	 # 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
       remote 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  sys-
       tem "poolB/received".  If  "poolB/received/fsA" does not	exist, it will
       be created 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"
       property	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 tar-

	 # zfs create -V 2g pool/volumes/vol1
	 # zfs set shareiscsi=on pool/volumes/vol1
	 # iscsitadm list target
	 Target: pool/volumes/vol1
	 iSCSI Name:
	 Connections: 0

       After the iSCSI target is created, set up the iSCSI initiator. For more
       information about the Solaris iSCSI initiator, see the Solaris Adminis-
       tration Guide: Devices and File Systems.

       The following exit values are returned:

       0    Successful completion.

       1    An error occurred.

       2    Invalid command line options were specified.

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

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

       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)


Want to link to this manual page? Use this URL:

home | help