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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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
       described 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  cir-
		      cumstances.  File	 systems  are  typically  used in most
		      environments. 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 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.

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

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

   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, 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-
       tions:

	 "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,
	   "reserv".

       volsize=size

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

       volblocksize=blocksize

	   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,
	   "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 according 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	 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,
	   "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.	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
	   "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
	   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
	   "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 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".

   iscsioptions
       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:

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

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

       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.

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

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

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

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

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

       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:

	     name,used,available,referenced,mountpoint

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

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

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

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

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

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

       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.

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

	 # 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
       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
	  destroyed
	 # 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
       "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
       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-
       get.

	 # 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
       information about the Solaris iSCSI initiator, see the Solaris Adminis-
       tration 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)

NAME | SYNOPSIS | DESCRIPTION | SUBCOMMANDS | EXAMPLES | EXIT STATUS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zfs&sektion=8&manpath=FreeBSD+7.2-RELEASE>

home | help