manpagez: man (manual) pages & more
man zfs(8)
Home | html | info | man
zfs(8)                    BSD System Manager's Manual                   zfs(8)




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



DESCRIPTION

       The  zfs  command configures ZFS datasets within a ZFS storage pool, as
       described in zpool(8). 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.


       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 Read-only Implementation
       ZFS on OSX is implemented as a readonly filesystem  by  default.   This
       means  that  only  the ZFS subcommands that do non write operations are
       permitted. Permitted subcommands are list,  get,  mount,  unmount,  and
       send.

       A full ZFS implementation that allows all subcommands and is read/write
       is available for download at http://developer.apple.com/.

       To determine which version of ZFS is loaded(readonly or writable):

         # kextstat | grep zfs

       com.apple.filesystems.zfs.readonly  is  the  readonly   kext   version.
       com.apple.filesystems.zfs is the writable kext version.


   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(8) command.

       See zpool(8) 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.  All  auto-
       matically managed file systems are mounted by ZFS at boot time.

       By default, file systems are mounted under /Volumes/fs, where fs 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. The mount-
       point property can be inherited, so if Volumes/pool/home  has  a  mount
       point  of  /export/stuff,  then pool/home/user automatically inherits a
       mount point of /export/stuff/user.

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

       If  needed, ZFS file systems can also be managed with traditional tools
       (mount, umount). 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 system.

   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.  ZFS volumes are not supported yet in OSX.


       volblocksize=blocksize

           For volumes. ZFS volumes are not supported yet in OSX.



       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.



       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
           is  not  yet  supported  for OSX.  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".



       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.


   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.apple." are reserved for use by Apple Inc.

       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 size represents the  logi-
           cal  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

           Share is not supported for ZFS on OSX.



       zfs unshare -a

           Unshare is not supported for ZFS on OSX.




       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.




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       -  /Volumes/pool
           pool/home                 100G   60G       -  /Volumes/export/home
           pool/home/bob              40G   60G     40G  /Volumes/export/home/bob
           pool/home/bob@yesterday     3M     -     40G  -
           pool/home/anne             60G   60G     40G  /Volumes/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  Replicating ZFS Data

       The following commands send a  full  stream  and  then  an  incremental
       stream    to    respective    backup   files,   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 > /tmp/backup_full \
         # zfs receive poolB/received/fs@a < /tmp/backup_full
         # zfs send -i a pool/fs@b > /tmp/backup.today \
         # zfs receive poolB/received/fs < /tmp/backup.today



       Example 13 Using the  zfs receive -d Option

       The following command sends a full stream of "poolA/fsA/fsB@snap" to  a
       backup  file,  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 > /tmp/backup.fsB \
            # zfs receive -d poolB/received < /tmp/backup.fsB




       Example 14 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




EXIT STATUS

       The following exit values are returned:

       0    Successful completion.


       1    An error occurred.


       2    Invalid command line options were specified.



SEE ALSO

       ssh(1), mount(8), zpool(8), chmod(1), stat(1), fsync(2), zfs.util(8)



HISTORY

       The zpool command first appeared in Mac OS X 10.5 (Leopard).




Mac OS X                          16 Mar 2007                           zfs(8)

Mac OS X 10.5 - Generated Sun Oct 28 21:48:39 EDT 2007