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

FreeBSD Manual Pages

  
 
  

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 en-
		      vironments. 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 ac-
       tive 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 be-
       come 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  au-
       tomatically  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 ad-
       ministrator is responsible for mounting and unmounting the file system.

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

       The physical properties of an added file	system are controlled  by  the
       global  administrator. However, the zone	administrator can create, 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 de-
       fined properties. Native	properties either export  internal  statistics
       or  control ZFS behavior. In addition, native properties	are either ed-
       itable 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, ex-
			pressed	as a multiplier. Compression can be turned  on
			by  running  "zfs set compression=on dataset". The de-
			fault value is "off".

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

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

       The following two properties can	be set to control the way space	is al-
       located 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  ef-
	   fects 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 op-
	   tions 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	 automatically	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 op-
	   tions 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 ap-
	   pear	in the same directory, but may have different inherited	 char-
	   acteristics.	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 de-
	   fault 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  ma-
       nipulate	 both native properties	and user properties.  Use the "zfs in-
       herit" command to clear a user property . If the	property  is  not  de-
       fined  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  en-
	   sure	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 un-
		 mounted 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 un-
	   expected 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  hi-
	   erarchy, 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 re-
	   name	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  op-
		      tions.  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  ex-
				 isting	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 ex-
		      ample, specifying	"-t snapshot" displays only snapshots.

       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 in-
	   formation on	what properties	can be set and acceptable values.  Nu-
	   meric  values can be	specified as exact values, or in a human-read-
	   able	form with a suffix of "B", "K",	"M", "G", "T", "P",  "E",  "Z"
	   (for	 bytes,	 Kbytes,  Mbytes, gigabytes, terabytes,	petabytes, ex-
	   abytes, 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 ex-
			plicitly separated by a	single tab instead of an arbi-
			trary 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  de-
	   fault 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 au-
	   tomatically 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 re-
	   ceived) that	this subcommand	creates	depends	on the	argument  type
	   and the -d option.

	   If  the argument is a snapshot name,	the specified snapshot is 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 re-
	   quired 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  re-
		 quired	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 re-
		 ceive 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/re-
       ceived/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