Placeholder

          --- old/usr/src/man/man1m/zfs.1m
          +++ new/usr/src/man/man1m/zfs.1m

   1    1  .\"
   2    2  .\" CDDL HEADER START
   3    3  .\"
   4    4  .\" The contents of this file are subject to the terms of the
   5    5  .\" Common Development and Distribution License (the "License").
   6    6  .\" You may not use this file except in compliance with the License.
   7    7  .\"
   8    8  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9    9  .\" or http://www.opensolaris.org/os/licensing.
  10   10  .\" See the License for the specific language governing permissions
  11   11  .\" and limitations under the License.
  12   12  .\"
  13   13  .\" When distributing Covered Code, include this CDDL HEADER in each
  14   14  .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15   15  .\" If applicable, add the following below this CDDL HEADER, with the
  16   16  .\" fields enclosed by brackets "[]" replaced with your own identifying
  17   17  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18   18  .\"

  19   19  .\" CDDL HEADER END
  20   20  .\"
  21   21  .\"
  22   22  .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
  23   23  .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
  24   24  .\" Copyright (c) 2011, 2015 by Delphix. All rights reserved.
  25   25  .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
  26   26  .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
  27   27  .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
  28   28  .\" Copyright 2015 Nexenta Systems, Inc.  All Rights Reserved.
       29 +.\" Copyright 2015 RackTop Systems.
  29   30  .\"
  30      -.Dd June 8, 2015
       31 +.Dd December 29, 2015
  31   32  .Dt ZFS 1M
  32   33  .Os
  33   34  .Sh NAME
  34   35  .Nm zfs
  35   36  .Nd configures ZFS file systems
  36   37  .Sh SYNOPSIS
  37   38  .Nm
  38   39  .Op Fl \?
  39   40  .Nm
  40   41  .Cm create

  41   42  .Op Fl p
  42   43  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  43   44  .Ar filesystem
  44   45  .Nm
  45   46  .Cm create
  46   47  .Op Fl ps
  47   48  .Op Fl b Ar blocksize
  48   49  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  49   50  .Fl V Ar size Ar volume
  50   51  .Nm
  51   52  .Cm destroy
  52   53  .Op Fl Rfnprv
  53   54  .Ar filesystem Ns | Ns Ar volume
  54   55  .Nm
  55   56  .Cm destroy
  56   57  .Op Fl Rdnprv
  57   58  .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
  58   59  .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
  59   60  .Nm
  60   61  .Cm destroy
  61   62  .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
  62   63  .Nm
  63   64  .Cm snapshot
  64   65  .Op Fl r
  65   66  .Oo Fl o Ar property Ns = Ns value Oc Ns ...
  66   67  .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
  67   68  .Nm
  68   69  .Cm rollback
  69   70  .Op Fl Rfr
  70   71  .Ar snapshot
  71   72  .Nm
  72   73  .Cm clone
  73   74  .Op Fl p
  74   75  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  75   76  .Ar snapshot Ar filesystem Ns | Ns Ar volume
  76   77  .Nm
  77   78  .Cm promote
  78   79  .Ar clone-filesystem
  79   80  .Nm
  80   81  .Cm rename
  81   82  .Op Fl f
  82   83  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  83   84  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  84   85  .Nm
  85   86  .Cm rename
  86   87  .Op Fl fp
  87   88  .Ar filesystem Ns | Ns Ar volume
  88   89  .Ar filesystem Ns | Ns Ar volume
  89   90  .Nm
  90   91  .Cm rename
  91   92  .Fl r
  92   93  .Ar snapshot Ar snapshot
  93   94  .Nm
  94   95  .Cm list
  95   96  .Op Fl r Ns | Ns Fl d Ar depth
  96   97  .Op Fl Hp
  97   98  .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
  98   99  .Oo Fl s Ar property Oc Ns ...
  99  100  .Oo Fl S Ar property Oc Ns ...
 100  101  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 101  102  .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
 102  103  .Nm
 103  104  .Cm set
 104  105  .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
 105  106  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 106  107  .Nm
 107  108  .Cm get
 108  109  .Op Fl r Ns | Ns Fl d Ar depth
 109  110  .Op Fl Hp
 110  111  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 111  112  .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
 112  113  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 113  114  .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
 114  115  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 115  116  .Nm
 116  117  .Cm inherit
 117  118  .Op Fl rS
 118  119  .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 119  120  .Nm
 120  121  .Cm upgrade
 121  122  .Nm
 122  123  .Cm upgrade
 123  124  .Fl v
 124  125  .Nm
 125  126  .Cm upgrade
 126  127  .Op Fl r
 127  128  .Op Fl V Ar version
 128  129  .Fl a | Ar filesystem
 129  130  .Nm
 130  131  .Cm userspace
 131  132  .Op Fl Hinp
 132  133  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 133  134  .Oo Fl s Ar field Oc Ns ...
 134  135  .Oo Fl S Ar field Oc Ns ...
 135  136  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 136  137  .Ar filesystem Ns | Ns Ar snapshot
 137  138  .Nm
 138  139  .Cm groupspace
 139  140  .Op Fl Hinp
 140  141  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 141  142  .Oo Fl s Ar field Oc Ns ...
 142  143  .Oo Fl S Ar field Oc Ns ...
 143  144  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 144  145  .Ar filesystem Ns | Ns Ar snapshot
 145  146  .Nm
 146  147  .Cm mount
 147  148  .Nm
 148  149  .Cm mount
 149  150  .Op Fl Ov
 150  151  .Op Fl o Ar options
 151  152  .Fl a | Ar filesystem
 152  153  .Nm
 153  154  .Cm unmount
 154  155  .Op Fl f
 155  156  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
 156  157  .Nm

 157  158  .Cm share
 158  159  .Fl a | Ar filesystem
 159  160  .Nm
 160  161  .Cm unshare
 161  162  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
 162  163  .Nm
 163  164  .Cm bookmark
 164  165  .Ar snapshot bookmark
 165  166  .Nm
 166  167  .Cm send
 167      -.Op Fl DLPRenpv
      168 +.Op Fl DFLPRenpv
 168  169  .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
 169  170  .Ar snapshot
 170  171  .Nm
 171  172  .Cm send
 172      -.Op Fl Le
      173 +.Op Fl FLe
 173  174  .Op Fl i Ar snapshot Ns | Ns Ar bookmark
 174  175  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
 175  176  .Nm
 176  177  .Cm send
 177  178  .Op Fl Penv
 178  179  .Fl t Ar receive_resume_token
 179  180  .Nm
 180  181  .Cm receive
 181  182  .Op Fl Fnsuv
 182  183  .Op Fl o Sy origin Ns = Ns Ar snapshot

 183  184  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
 184  185  .Nm
 185  186  .Cm receive
 186  187  .Op Fl Fnsuv
 187  188  .Op Fl d Ns | Ns Fl e
 188  189  .Op Fl o Sy origin Ns = Ns Ar snapshot
 189  190  .Ar filesystem
 190  191  .Nm
 191  192  .Cm receive
 192  193  .Fl A
 193  194  .Ar filesystem Ns | Ns Ar volume
 194  195  .Nm
 195  196  .Cm allow
 196  197  .Ar filesystem Ns | Ns Ar volume
 197  198  .Nm
 198  199  .Cm allow
 199  200  .Op Fl dglu
 200  201  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
 201  202  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 202  203  .Ar setname Oc Ns ...
 203  204  .Ar filesystem Ns | Ns Ar volume
 204  205  .Nm
 205  206  .Cm allow
 206  207  .Op Fl dl
 207  208  .Fl e Ns | Ns Sy everyone
 208  209  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 209  210  .Ar setname Oc Ns ...
 210  211  .Ar filesystem Ns | Ns Ar volume
 211  212  .Nm
 212  213  .Cm allow
 213  214  .Fl c
 214  215  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 215  216  .Ar setname Oc Ns ...
 216  217  .Ar filesystem Ns | Ns Ar volume
 217  218  .Nm
 218  219  .Cm allow
 219  220  .Fl s No @ Ns Ar setname
 220  221  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 221  222  .Ar setname Oc Ns ...
 222  223  .Ar filesystem Ns | Ns Ar volume
 223  224  .Nm
 224  225  .Cm unallow
 225  226  .Op Fl dglru
 226  227  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
 227  228  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 228  229  .Ar setname Oc Ns ... Oc
 229  230  .Ar filesystem Ns | Ns Ar volume
 230  231  .Nm
 231  232  .Cm unallow
 232  233  .Op Fl dlr
 233  234  .Fl e Ns | Ns Sy everyone
 234  235  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 235  236  .Ar setname Oc Ns ... Oc
 236  237  .Ar filesystem Ns | Ns Ar volume
 237  238  .Nm
 238  239  .Cm unallow
 239  240  .Op Fl r
 240  241  .Fl c
 241  242  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 242  243  .Ar setname Oc Ns ... Oc
 243  244  .Ar filesystem Ns | Ns Ar volume
 244  245  .Nm
 245  246  .Cm unallow
 246  247  .Op Fl r
 247  248  .Fl s @ Ns Ar setname
 248  249  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 249  250  .Ar setname Oc Ns ... Oc
 250  251  .Ar filesystem Ns | Ns Ar volume
 251  252  .Nm
 252  253  .Cm hold
 253  254  .Op Fl r
 254  255  .Ar tag Ar snapshot Ns ...
 255  256  .Nm
 256  257  .Cm holds
 257  258  .Op Fl r
 258  259  .Ar snapshot Ns ...
 259  260  .Nm
 260  261  .Cm release
 261  262  .Op Fl r
 262  263  .Ar tag Ar snapshot Ns ...
 263  264  .Nm
 264  265  .Cm diff
 265  266  .Op Fl FHt
 266  267  .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
 267  268  .Sh DESCRIPTION
 268  269  The
 269  270  .Nm
 270  271  command configures ZFS datasets within a ZFS storage pool, as described in
 271  272  .Xr zpool 1M .
 272  273  A dataset is identified by a unique path within the ZFS namespace. For example:
 273  274  .Bd -literal
 274  275  pool/{filesystem,volume,snapshot}
 275  276  .Ed
 276  277  .Pp
 277  278  where the maximum length of a dataset name is
 278  279  .Dv MAXNAMELEN
 279  280  .Pq 256 bytes .
 280  281  .Pp
 281  282  A dataset can be one of the following:
 282  283  .Bl -tag -width "file system"
 283  284  .It Sy file system
 284  285  A ZFS dataset of type
 285  286  .Sy filesystem
 286  287  can be mounted within the standard system namespace and behaves like other file
 287  288  systems. While ZFS file systems are designed to be POSIX compliant, known issues
 288  289  exist that prevent compliance in some cases. Applications that depend on
 289  290  standards conformance might fail due to non-standard behavior when checking file
 290  291  system free space.
 291  292  .It Sy volume
 292  293  A logical volume exported as a raw or block device. This type of dataset should
 293  294  only be used under special circumstances. File systems are typically used in
 294  295  most environments.
 295  296  .It Sy snapshot
 296  297  A read-only version of a file system or volume at a given point in time. It is
 297  298  specified as
 298  299  .Ar filesystem Ns @ Ns Ar name
 299  300  or
 300  301  .Ar volume Ns @ Ns Ar name .
 301  302  .El
 302  303  .Ss ZFS File System Hierarchy
 303  304  A ZFS storage pool is a logical collection of devices that provide space for
 304  305  datasets. A storage pool is also the root of the ZFS file system hierarchy.
 305  306  .Pp
 306  307  The root of the pool can be accessed as a file system, such as mounting and
 307  308  unmounting, taking snapshots, and setting properties. The physical storage
 308  309  characteristics, however, are managed by the
 309  310  .Xr zpool 1M
 310  311  command.
 311  312  .Pp
 312  313  See
 313  314  .Xr zpool 1M
 314  315  for more information on creating and administering pools.
 315  316  .Ss Snapshots
 316  317  A snapshot is a read-only copy of a file system or volume. Snapshots can be
 317  318  created extremely quickly, and initially consume no additional space within the
 318  319  pool. As data within the active dataset changes, the snapshot consumes more
 319  320  data than would otherwise be shared with the active dataset.
 320  321  .Pp
 321  322  Snapshots can have arbitrary names. Snapshots of volumes can be cloned or
 322  323  rolled back, but cannot be accessed independently.
 323  324  .Pp
 324  325  File system snapshots can be accessed under the
 325  326  .Pa .zfs/snapshot
 326  327  directory in the root of the file system. Snapshots are automatically mounted on
 327  328  demand and may be unmounted at regular intervals. The visibility of the
 328  329  .Pa .zfs
 329  330  directory can be controlled by the
 330  331  snapdir
 331  332  property.
 332  333  .Ss Clones
 333  334  A clone is a writable volume or file system whose initial contents are the same
 334  335  as another dataset. As with snapshots, creating a clone is nearly instantaneous,
 335  336  and initially consumes no additional space.
 336  337  .Pp
 337  338  Clones can only be created from a snapshot. When a snapshot is cloned, it
 338  339  creates an implicit dependency between the parent and child. Even though the
 339  340  clone is created somewhere else in the dataset hierarchy, the original snapshot
 340  341  cannot be destroyed as long as a clone exists. The
 341  342  .Sy origin
 342  343  property exposes this dependency, and the
 343  344  .Cm destroy
 344  345  command lists any such dependencies, if they exist.
 345  346  .Pp
 346  347  The clone parent-child dependency relationship can be reversed by using the
 347  348  .Cm promote
 348  349  subcommand. This causes the
 349  350  .Qq origin
 350  351  file system to become a clone of the specified file system, which makes it
 351  352  possible to destroy the file system that the clone was created from.
 352  353  .Ss "Mount Points"
 353  354  Creating a ZFS file system is a simple operation, so the number of file systems
 354  355  per system is likely to be numerous. To cope with this, ZFS automatically
 355  356  manages mounting and unmounting file systems without the need to edit the
 356  357  .Pa /etc/vfstab
 357  358  file. All automatically managed file systems are mounted by ZFS at boot time.
 358  359  .Pp
 359  360  By default, file systems are mounted under
 360  361  .Pa /path ,
 361  362  where
 362  363  .Ar path
 363  364  is the name of the file system in the ZFS namespace. Directories are created and
 364  365  destroyed as needed.
 365  366  .Pp
 366  367  A file system can also have a mount point set in the
 367  368  .Sy mountpoint
 368  369  property. This directory is created as needed, and ZFS automatically mounts the
 369  370  file system when the
 370  371  .Nm zfs Cm mount Fl a
 371  372  command is invoked
 372  373  .Po without editing
 373  374  .Pa /etc/vfstab
 374  375  .Pc .
 375  376  The
 376  377  .Sy mountpoint
 377  378  property can be inherited, so if
 378  379  .Em pool/home
 379  380  has a mount point of
 380  381  .Pa /export/stuff ,
 381  382  then
 382  383  .Em pool/home/user
 383  384  automatically inherits a mount point of
 384  385  .Pa /export/stuff/user .
 385  386  .Pp
 386  387  A file system
 387  388  .Sy mountpoint
 388  389  property of
 389  390  .Sy none
 390  391  prevents the file system from being mounted.
 391  392  .Pp
 392  393  If needed, ZFS file systems can also be managed with traditional tools
 393  394  .Po
 394  395  .Nm mount ,
 395  396  .Nm umount ,
 396  397  .Pa /etc/vfstab
 397  398  .Pc .
 398  399  If a file system's mount point is set to
 399  400  .Sy legacy ,
 400  401  ZFS makes no attempt to manage the file system, and the administrator is
 401  402  responsible for mounting and unmounting the file system.
 402  403  .Ss "Zones"
 403  404  A ZFS file system can be added to a non-global zone by using the
 404  405  .Nm zonecfg Cm add Sy fs
 405  406  subcommand. A ZFS file system that is added to a non-global zone must have its
 406  407  .Sy mountpoint
 407  408  property set to
 408  409  .Sy legacy .
 409  410  .Pp
 410  411  The physical properties of an added file system are controlled by the global
 411  412  administrator. However, the zone administrator can create, modify, or destroy
 412  413  files within the added file system, depending on how the file system is mounted.
 413  414  .Pp
 414  415  A dataset can also be delegated to a non-global zone by using the
 415  416  .Nm zonecfg Cm add Sy dataset
 416  417  subcommand. You cannot delegate a dataset to one zone and the children of the
 417  418  same dataset to another zone. The zone administrator can change properties of
 418  419  the dataset or any of its children. However, the
 419  420  .Sy quota ,
 420  421  .Sy filesystem_limit
 421  422  and
 422  423  .Sy snapshot_limit
 423  424  properties of the delegated dataset can be modified only by the global
 424  425  administrator.
 425  426  .Pp
 426  427  A ZFS volume can be added as a device to a non-global zone by using the
 427  428  .Nm zonecfg Cm add Sy device
 428  429  subcommand. However, its physical properties can be modified only by the global
 429  430  administrator.
 430  431  .Pp
 431  432  For more information about
 432  433  .Nm zonecfg
 433  434  syntax, see
 434  435  .Xr zonecfg 1M .
 435  436  .Pp
 436  437  After a dataset is delegated to a non-global zone, the
 437  438  .Sy zoned
 438  439  property is automatically set. A zoned file system cannot be mounted in the
 439  440  global zone, since the zone administrator might have to set the mount point to
 440  441  an unacceptable value.
 441  442  .Pp
 442  443  The global administrator can forcibly clear the
 443  444  .Sy zoned
 444  445  property, though this should be done with extreme care. The global administrator
 445  446  should verify that all the mount points are acceptable before clearing the
 446  447  property.
 447  448  .Ss Native Properties
 448  449  Properties are divided into two types, native properties and user-defined
 449  450  .Po or
 450  451  .Qq user
 451  452  .Pc
 452  453  properties. Native properties either export internal statistics or control ZFS
 453  454  behavior. In addition, native properties are either editable or read-only. User
 454  455  properties have no effect on ZFS behavior, but you can use them to annotate
 455  456  datasets in a way that is meaningful in your environment. For more information
 456  457  about user properties, see the
 457  458  .Sx User Properties
 458  459  section, below.
 459  460  .Pp
 460  461  Every dataset has a set of properties that export statistics about the dataset
 461  462  as well as control various behaviors. Properties are inherited from the parent
 462  463  unless overridden by the child. Some properties apply only to certain types of
 463  464  datasets
 464  465  .Pq file systems, volumes, or snapshots .
 465  466  .Pp
 466  467  The values of numeric properties can be specified using human-readable suffixes
 467  468  .Po for example,
 468  469  .Sy k ,
 469  470  .Sy KB ,
 470  471  .Sy M ,
 471  472  .Sy Gb ,
 472  473  and so forth, up to
 473  474  .Sy Z
 474  475  for zettabyte
 475  476  .Pc .
 476  477  The following are all valid
 477  478  .Pq and equal
 478  479  specifications:
 479  480  .Li 1536M, 1.5g, 1.50GB .
 480  481  .Pp
 481  482  The values of non-numeric properties are case sensitive and must be lowercase,
 482  483  except for
 483  484  .Sy mountpoint ,
 484  485  .Sy sharenfs ,
 485  486  and
 486  487  .Sy sharesmb .
 487  488  .Pp
 488  489  The following native properties consist of read-only statistics about the
 489  490  dataset. These properties can be neither set, nor inherited. Native properties
 490  491  apply to all dataset types unless otherwise noted.
 491  492  .Bl -tag -width "usedbyrefreservation"
 492  493  .It Sy available
 493  494  The amount of space available to the dataset and all its children, assuming that
 494  495  there is no other activity in the pool. Because space is shared within a pool,
 495  496  availability can be limited by any number of factors, including physical pool
 496  497  size, quotas, reservations, or other datasets within the pool.
 497  498  .Pp
 498  499  This property can also be referred to by its shortened column name,
 499  500  .Sy avail .
 500  501  .It Sy compressratio
 501  502  For non-snapshots, the compression ratio achieved for the
 502  503  .Sy used
 503  504  space of this dataset, expressed as a multiplier. The
 504  505  .Sy used
 505  506  property includes descendant datasets, and, for clones, does not include the
 506  507  space shared with the origin snapshot. For snapshots, the
 507  508  .Sy compressratio
 508  509  is the same as the
 509  510  .Sy refcompressratio
 510  511  property. Compression can be turned on by running:
 511  512  .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
 512  513  The default value is
 513  514  .Sy off .
 514  515  .It Sy creation
 515  516  The time this dataset was created.
 516  517  .It Sy clones
 517  518  For snapshots, this property is a comma-separated list of filesystems or volumes
 518  519  which are clones of this snapshot. The clones'
 519  520  .Sy origin
 520  521  property is this snapshot. If the
 521  522  .Sy clones
 522  523  property is not empty, then this snapshot can not be destroyed
 523  524  .Po even with the
 524  525  .Fl r
 525  526  or
 526  527  .Fl f
 527  528  options
 528  529  .Pc .
 529  530  .It Sy defer_destroy
 530  531  This property is
 531  532  .Sy on
 532  533  if the snapshot has been marked for deferred destroy by using the
 533  534  .Nm zfs Cm destroy Fl d
 534  535  command. Otherwise, the property is
 535  536  .Sy off .
 536  537  .It Sy filesystem_count
 537  538  The total number of filesystems and volumes that exist under this location in
 538  539  the dataset tree. This value is only available when a
 539  540  .Sy filesystem_limit
 540  541  has been set somewhere in the tree under which the dataset resides.
 541  542  .It Sy logicalreferenced
 542  543  The amount of space that is
 543  544  .Qq logically
 544  545  accessible by this dataset. See the
 545  546  .Sy referenced
 546  547  property. The logical space ignores the effect of the
 547  548  .Sy compression
 548  549  and
 549  550  .Sy copies
 550  551  properties, giving a quantity closer to the amount of data that applications
 551  552  see. However, it does include space consumed by metadata.
 552  553  .Pp
 553  554  This property can also be referred to by its shortened column name,
 554  555  .Sy lrefer .
 555  556  .It Sy logicalused
 556  557  The amount of space that is
 557  558  .Qq logically
 558  559  consumed by this dataset and all its descendents. See the
 559  560  .Sy used
 560  561  property. The logical space ignores the effect of the
 561  562  .Sy compression
 562  563  and
 563  564  .Sy copies
 564  565  properties, giving a quantity closer to the amount of data that applications
 565  566  see. However, it does include space consumed by metadata.
 566  567  .Pp
 567  568  This property can also be referred to by its shortened column name,
 568  569  .Sy lused .
 569  570  .It Sy mounted
 570  571  For file systems, indicates whether the file system is currently mounted. This
 571  572  property can be either
 572  573  .Sy yes
 573  574  or
 574  575  .Sy no .
 575  576  .It Sy origin
 576  577  For cloned file systems or volumes, the snapshot from which the clone was
 577  578  created. See also the
 578  579  .Sy clones
 579  580  property.
 580  581  .It Sy receive_resume_token
 581  582  For filesystems or volumes which have saved partially-completed state from
 582  583  .Sy zfs receive -s ,
 583  584  this opaque token can be provided to
 584  585  .Sy zfs send -t
 585  586  to resume and complete the
 586  587  .Sy zfs receive .
 587  588  .It Sy referenced
 588  589  The amount of data that is accessible by this dataset, which may or may not be
 589  590  shared with other datasets in the pool. When a snapshot or clone is created, it
 590  591  initially references the same amount of space as the file system or snapshot it
 591  592  was created from, since its contents are identical.
 592  593  .Pp
 593  594  This property can also be referred to by its shortened column name,
 594  595  .Sy refer .
 595  596  .It Sy refcompressratio
 596  597  The compression ratio achieved for the
 597  598  .Sy referenced
 598  599  space of this dataset, expressed as a multiplier. See also the
 599  600  .Sy compressratio
 600  601  property.
 601  602  .It Sy snapshot_count
 602  603  The total number of snapshots that exist under this location in the dataset
 603  604  tree. This value is only available when a
 604  605  .Sy snapshot_limit
 605  606  has been set somewhere in the tree under which the dataset resides.
 606  607  .It Sy type
 607  608  The type of dataset:
 608  609  .Sy filesystem ,
 609  610  .Sy volume ,
 610  611  or
 611  612  .Sy snapshot .
 612  613  .It Sy used
 613  614  The amount of space consumed by this dataset and all its descendents. This is
 614  615  the value that is checked against this dataset's quota and reservation. The
 615  616  space used does not include this dataset's reservation, but does take into
 616  617  account the reservations of any descendent datasets. The amount of space that a
 617  618  dataset consumes from its parent, as well as the amount of space that are freed
 618  619  if this dataset is recursively destroyed, is the greater of its space used and
 619  620  its reservation.
 620  621  .Pp
 621  622  When snapshots
 622  623  .Po see the
 623  624  .Sx Snapshots
 624  625  section
 625  626  .Pc
 626  627  are created, their space is initially shared between the snapshot and
 627  628  the file system, and possibly with previous snapshots. As the file system
 628  629  changes, space that was previously shared becomes unique to the snapshot, and
 629  630  counted in the snapshot's space used. Additionally, deleting snapshots can
 630  631  increase the amount of space unique to
 631  632  .Pq and used by
 632  633  other snapshots.
 633  634  .Pp
 634  635  The amount of space used, available, or referenced does not take into account
 635  636  pending changes. Pending changes are generally accounted for within a few
 636  637  seconds. Committing a change to a disk using
 637  638  .Xr fsync 3C
 638  639  or
 639  640  .Dv O_SYNC
 640  641  does not necessarily guarantee that the space usage information is updated
 641  642  immediately.
 642  643  .It Sy usedby*
 643  644  The
 644  645  .Sy usedby*
 645  646  properties decompose the
 646  647  .Sy used
 647  648  properties into the various reasons that space is used. Specifically,
 648  649  .Sy used No =
 649  650  .Sy usedbychildren No +
 650  651  .Sy usedbydataset No +
 651  652  .Sy usedbyrefreservation No +
 652  653  .Sy usedbysnapshots .
 653  654  These properties are only available for datasets created on
 654  655  .Nm zpool
 655  656  .Qo version 13 Qc
 656  657  pools.
 657  658  .It Sy usedbychildren
 658  659  The amount of space used by children of this dataset, which would be freed if
 659  660  all the dataset's children were destroyed.
 660  661  .It Sy usedbydataset
 661  662  The amount of space used by this dataset itself, which would be freed if the
 662  663  dataset were destroyed
 663  664  .Po after first removing any
 664  665  .Sy refreservation
 665  666  and destroying any necessary snapshots or descendents
 666  667  .Pc .
 667  668  .It Sy usedbyrefreservation
 668  669  The amount of space used by a
 669  670  .Sy refreservation
 670  671  set on this dataset, which would be freed if the
 671  672  .Sy refreservation
 672  673  was removed.
 673  674  .It Sy usedbysnapshots
 674  675  The amount of space consumed by snapshots of this dataset. In particular, it is
 675  676  the amount of space that would be freed if all of this dataset's snapshots were
 676  677  destroyed. Note that this is not simply the sum of the snapshots'
 677  678  .Sy used
 678  679  properties because space can be shared by multiple snapshots.
 679  680  .It Sy userused Ns @ Ns Em user
 680  681  The amount of space consumed by the specified user in this dataset. Space is
 681  682  charged to the owner of each file, as displayed by
 682  683  .Nm ls Fl l .
 683  684  The amount of space charged is displayed by
 684  685  .Nm du
 685  686  and
 686  687  .Nm ls Fl s .
 687  688  See the
 688  689  .Nm zfs Cm userspace
 689  690  subcommand for more information.
 690  691  .Pp
 691  692  Unprivileged users can access only their own space usage. The root user, or a
 692  693  user who has been granted the
 693  694  .Sy userused
 694  695  privilege with
 695  696  .Nm zfs Cm allow ,
 696  697  can access everyone's usage.
 697  698  .Pp
 698  699  The
 699  700  .Sy userused Ns @ Ns Em ...
 700  701  properties are not displayed by
 701  702  .Nm zfs Cm get Sy all .
 702  703  The user's name must be appended after the @ symbol, using one of the following
 703  704  forms:
 704  705  .Bl -bullet -width ""
 705  706  .It
 706  707  .Em POSIX name
 707  708  .Po for example,
 708  709  .Sy joe
 709  710  .Pc
 710  711  .It
 711  712  .Em POSIX numeric ID
 712  713  .Po for example,
 713  714  .Sy 789
 714  715  .Pc
 715  716  .It
 716  717  .Em SID name
 717  718  .Po for example,
 718  719  .Sy joe.smith@mydomain
 719  720  .Pc
 720  721  .It
 721  722  .Em SID numeric ID
 722  723  .Po for example,
 723  724  .Sy S-1-123-456-789
 724  725  .Pc
 725  726  .El
 726  727  .It Sy userrefs
 727  728  This property is set to the number of user holds on this snapshot. User holds
 728  729  are set by using the
 729  730  .Nm zfs Cm hold
 730  731  command.
 731  732  .It Sy groupused Ns @ Ns Em group
 732  733  The amount of space consumed by the specified group in this dataset. Space is
 733  734  charged to the group of each file, as displayed by
 734  735  .Nm ls Fl l .
 735  736  See the
 736  737  .Sy userused Ns @ Ns Em user
 737  738  property for more information.
 738  739  .Pp
 739  740  Unprivileged users can only access their own groups' space usage. The root user,
 740  741  or a user who has been granted the
 741  742  .Sy groupused
 742  743  privilege with
 743  744  .Nm zfs Cm allow ,
 744  745  can access all groups' usage.
 745  746  .It Sy volblocksize Ns = Ns Em blocksize
 746  747  For volumes, specifies the block size of the volume. The
 747  748  .Sy blocksize
 748  749  cannot be changed once the volume has been written, so it should be set at
 749  750  volume creation time. The default
 750  751  .Sy blocksize
 751  752  for volumes is 8 Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid.
 752  753  .Pp
 753  754  This property can also be referred to by its shortened column name,
 754  755  .Sy volblock .
 755  756  .It Sy written
 756  757  The amount of
 757  758  .Sy referenced
 758  759  space written to this dataset since the previous snapshot.
 759  760  .It Sy written Ns @ Ns Em snapshot
 760  761  The amount of
 761  762  .Sy referenced
 762  763  space written to this dataset since the specified snapshot. This is the space
 763  764  that is referenced by this dataset but was not referenced by the specified
 764  765  snapshot.
 765  766  .Pp
 766  767  The
 767  768  .Em snapshot
 768  769  may be specified as a short snapshot name
 769  770  .Po just the part after the
 770  771  .Sy @
 771  772  .Pc ,
 772  773  in which case it will be interpreted as a snapshot in the same filesystem as
 773  774  this dataset. The
 774  775  .Em snapshot
 775  776  may be a full snapshot name
 776  777  .Po Em filesystem Ns @ Ns Em snapshot Pc ,
 777  778  which for clones may be a snapshot in the origin's filesystem
 778  779  .Pq or the origin of the origin's filesystem, etc.
 779  780  .El
 780  781  .Pp
 781  782  The following native properties can be used to change the behavior of a ZFS
 782  783  dataset.
 783  784  .Bl -tag -width ""
 784  785  .It Xo
 785  786  .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
 786  787  .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
 787  788  .Xc
 788  789  Controls how
 789  790  .Sy ACE Ns s
 790  791  are inherited when files and directories are created.
 791  792  .Bl -tag -width "passthrough-x"
 792  793  .It Sy discard
 793  794  does not inherit any
 794  795  .Sy ACE Ns s .
 795  796  .It Sy noallow
 796  797  only inherits inheritable
 797  798  .Sy ACE Ns s
 798  799  that specify
 799  800  .Qq deny
 800  801  permissions.
 801  802  .It Sy restricted
 802  803  default, removes the
 803  804  .Sy write_acl
 804  805  and
 805  806  .Sy write_owner
 806  807  permissions when the
 807  808  .Sy ACE
 808  809  is inherited.
 809  810  .It Sy passthrough
 810  811  inherits all inheritable
 811  812  .Sy ACE Ns s
 812  813  without any modifications.
 813  814  .It Sy passthrough-x
 814  815  same meaning as
 815  816  .Sy passthrough ,
 816  817  except that the
 817  818  .Sy owner@ ,
 818  819  .Sy group@ ,
 819  820  and
 820  821  .Sy everyone@
 821  822  .Sy ACE Ns s
 822  823  inherit the execute permission only if the file creation mode also requests the
 823  824  execute bit.
 824  825  .El
 825  826  .Pp
 826  827  When the property value is set to
 827  828  .Sy passthrough ,
 828  829  files are created with a mode determined by the inheritable
 829  830  .Sy ACE Ns s .
 830  831  If no inheritable
 831  832  .Sy ACE Ns s
 832  833  exist that affect the mode, then the mode is set in accordance to the requested
 833  834  mode from the application.
 834  835  .It Xo
 835  836  .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
 836  837  .Sy passthrough Ns | Ns Sy restricted
 837  838  .Xc
 838  839  Controls how an
 839  840  .Sy ACL
 840  841  is modified during
 841  842  .Xr chmod 2 .
 842  843  .Bl -tag -width "passthrough"
 843  844  .It Sy discard
 844  845  default, deletes all
 845  846  .Sy ACE Ns s
 846  847  that do not represent the mode of the file.
 847  848  .It Sy groupmask
 848  849  reduces permissions granted in all
 849  850  .Sy ALLOW
 850  851  entries found in the
 851  852  .Sy ACL
 852  853  such that they are no greater than the group permissions specified by
 853  854  .Xr chmod 2 .
 854  855  .It Sy passthrough
 855  856  indicates that no changes are made to the
 856  857  .Sy ACL
 857  858  other than creating or updating the necessary
 858  859  .Sy ACE Ns s
 859  860  to represent the new mode of the file or directory.
 860  861  .It Sy restricted
 861  862  causes the
 862  863  .Xr chmod 2
 863  864  operation to return an error when used on any file or directory which has a
 864  865  non-trivial
 865  866  .Sy ACE Ns s
 866  867  whose entries can not be represented by a mode.
 867  868  .El
 868  869  .Pp
 869  870  .Xr chmod 2
 870  871  is required to change the set user ID, set group ID, or sticky bits on a file or
 871  872  directory, as they do not have equivalent
 872  873  .Sy ACE Ns s.
 873  874  In order to use
 874  875  .Xr chmod 2
 875  876  on a file or directory with a non-trivial
 876  877  .Sy ACL
 877  878  when
 878  879  .Sy aclmode
 879  880  is set to
 880  881  .Sy restricted ,
 881  882  you must first remove all
 882  883  .Sy ACE Ns s
 883  884  which do not represent the current mode.
 884  885  .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
 885  886  Controls whether the access time for files is updated when they are read.
 886  887  Turning this property off avoids producing write traffic when reading files and
 887  888  can result in significant performance gains, though it might confuse mailers
 888  889  and other similar utilities. The default value is
 889  890  .Sy on .
 890  891  .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
 891  892  If this property is set to
 892  893  .Sy off ,
 893  894  the file system cannot be mounted, and is ignored by
 894  895  .Nm zfs Cm mount Fl a .
 895  896  Setting this property to
 896  897  .Sy off
 897  898  is similar to setting the
 898  899  .Sy mountpoint
 899  900  property to
 900  901  .Sy none ,
 901  902  except that the dataset still has a normal
 902  903  .Sy mountpoint
 903  904  property, which can be inherited. Setting this property to
 904  905  .Sy off
 905  906  allows datasets to be used solely as a mechanism to inherit properties. One
 906  907  example of setting
 907  908  .Sy canmount Ns = Ns Sy off
 908  909  is to have two datasets with the same
 909  910  .Sy mountpoint ,
 910  911  so that the children of both datasets appear in the same directory, but might
 911  912  have different inherited characteristics.
 912  913  .Pp
 913  914  When set to
 914  915  .Sy noauto ,
 915  916  a dataset can only be mounted and unmounted explicitly. The dataset is not
 916  917  mounted automatically when the dataset is created or imported, nor is it mounted
 917  918  by the
 918  919  .Nm zfs Cm mount Fl a
 919  920  command or unmounted by the
 920  921  .Nm zfs Cm unmount Fl a
 921  922  command.
 922  923  .Pp
 923  924  This property is not inherited.
 924  925  .It Xo
 925  926  .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
 926  927  .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
 927  928  .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
 928  929  .Xc
 929  930  Controls the checksum used to verify data integrity. The default value is
 930  931  .Sy on ,
 931  932  which automatically selects an appropriate algorithm
 932  933  .Po currently,
 933  934  .Sy fletcher4 ,
 934  935  but this may change in future releases
 935  936  .Pc .
 936  937  The value
 937  938  .Sy off
 938  939  disables integrity checking on user data. The value
 939  940  .Sy noparity
 940  941  not only disables integrity but also disables maintaining parity for user data.
 941  942  This setting is used internally by a dump device residing on a RAID-Z pool and
 942  943  should not be used by any other dataset. Disabling checksums is
 943  944  .Sy NOT
 944  945  a recommended practice.
 945  946  .Pp
 946  947  The
 947  948  .Sy sha512 ,
 948  949  .Sy skein ,
 949  950  and
 950  951  .Sy edonr
 951  952  checksum algorithms require enabling the appropriate features on the
 952  953  pool. Please see
 953  954  .Xr zpool-features 5
 954  955  for more information on these algorithms.
 955  956  .Pp
 956  957  Changing this property affects only newly-written data.
 957  958  .It Xo
 958  959  .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
 959  960  .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
 960  961  .Xc
 961  962  Controls the compression algorithm used for this dataset.
 962  963  .Pp
 963  964  Setting compression to
 964  965  .Sy on
 965  966  indicates that the current default compression algorithm should be used. The
 966  967  default balances compression and decompression speed, with compression ratio and
 967  968  is expected to work well on a wide variety of workloads.  Unlike all other
 968  969  settings for this property,
 969  970  .Sy on
 970  971  does not select a fixed compression type. As new compression algorithms are
 971  972  added to ZFS and enabled on a pool, the default compression algorithm may
 972  973  change. The current default compression algorthm is either
 973  974  .Sy lzjb
 974  975  or, if the
 975  976  .Sy lz4_compress
 976  977  feature is enabled,
 977  978  .Sy lz4 .
 978  979  .Pp
 979  980  The
 980  981  .Sy lz4
 981  982  compression algorithm is a high-performance replacement for the
 982  983  .Sy lzjb
 983  984  algorithm. It features significantly faster compression and decompression, as
 984  985  well as a moderately higher compression ratio than
 985  986  .Sy lzjb ,
 986  987  but can only be used on pools with the
 987  988  .Sy lz4_compress
 988  989  feature set to
 989  990  .Sy enabled .
 990  991  See
 991  992  .Xr zpool-features 5
 992  993  for details on ZFS feature flags and the
 993  994  .Sy lz4_compress
 994  995  feature.
 995  996  .Pp
 996  997  The
 997  998  .Sy lzjb
 998  999  compression algorithm is optimized for performance while providing decent data
 999 1000  compression.
1000 1001  .Pp
1001 1002  The
1002 1003  .Sy gzip
1003 1004  compression algorithm uses the same compression as the
1004 1005  .Xr gzip 1
1005 1006  command. You can specify the
1006 1007  .Sy gzip
1007 1008  level by using the value
1008 1009  .Sy gzip- Ns Em N ,
1009 1010  where
1010 1011  .Em N
1011 1012  is an integer from 1
1012 1013  .Pq fastest
1013 1014  to 9
1014 1015  .Pq best compression ratio .
1015 1016  Currently,
1016 1017  .Sy gzip
1017 1018  is equivalent to
1018 1019  .Sy gzip-6
1019 1020  .Po which is also the default for
1020 1021  .Xr gzip 1
1021 1022  .Pc .
1022 1023  .Pp
1023 1024  The
1024 1025  .Sy zle
1025 1026  compression algorithm compresses runs of zeros.
1026 1027  .Pp
1027 1028  This property can also be referred to by its shortened column name
1028 1029  \fBcompress\fR. Changing this property affects only newly-written data.
1029 1030  .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1030 1031  Controls the number of copies of data stored for this dataset. These copies are
1031 1032  in addition to any redundancy provided by the pool, for example, mirroring or
1032 1033  RAID-Z. The copies are stored on different disks, if possible. The space used
1033 1034  by multiple copies is charged to the associated file and dataset, changing the
1034 1035  .Sy used
1035 1036  property and counting against quotas and reservations.
1036 1037  .Pp
1037 1038  Changing this property only affects newly-written data. Therefore, set this
1038 1039  property at file system creation time by using the
1039 1040  .Fl o Sy copies Ns = Ns Ar N
1040 1041  option.
1041 1042  .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1042 1043  Controls whether device nodes can be opened on this file system. The default
1043 1044  value is
1044 1045  .Sy on .
1045 1046  .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1046 1047  Controls whether processes can be executed from within this file system. The
1047 1048  default value is
1048 1049  .Sy on .
1049 1050  .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1050 1051  Limits the number of filesystems and volumes that can exist under this point in
1051 1052  the dataset tree. The limit is not enforced if the user is allowed to change
1052 1053  the limit. Setting a
1053 1054  .Sy filesystem_limit
1054 1055  to
1055 1056  .Sy on
1056 1057  a descendent of a filesystem that already has a
1057 1058  .Sy filesystem_limit
1058 1059  does not override the ancestor's
1059 1060  .Sy filesystem_limit ,
1060 1061  but rather imposes an additional limit. This feature must be enabled to be used
1061 1062  .Po see
1062 1063  .Xr zpool-features 5
1063 1064  .Pc .
1064 1065  .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1065 1066  Controls the mount point used for this file system. See the
1066 1067  .Sx Mount Points
1067 1068  section for more information on how this property is used.
1068 1069  .Pp
1069 1070  When the
1070 1071  .Sy mountpoint
1071 1072  property is changed for a file system, the file system and any children that
1072 1073  inherit the mount point are unmounted. If the new value is
1073 1074  .Sy legacy ,
1074 1075  then they remain unmounted. Otherwise, they are automatically remounted in the
1075 1076  new location if the property was previously
1076 1077  .Sy legacy
1077 1078  or
1078 1079  .Sy none ,
1079 1080  or if they were mounted before the property was changed. In addition, any shared
1080 1081  file systems are unshared and shared in the new location.
1081 1082  .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1082 1083  Controls whether the file system should be mounted with
1083 1084  .Sy nbmand
1084 1085  .Pq Non Blocking mandatory locks .
1085 1086  This is used for SMB clients. Changes to this property only take effect when the
1086 1087  file system is umounted and remounted. See
1087 1088  .Xr mount 1M
1088 1089  for more information on
1089 1090  .Sy nbmand
1090 1091  mounts.
1091 1092  .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1092 1093  Controls what is cached in the primary cache
1093 1094  .Pq ARC .
1094 1095  If this property is set to
1095 1096  .Sy all ,
1096 1097  then both user data and metadata is cached. If this property is set to
1097 1098  .Sy none ,
1098 1099  then neither user data nor metadata is cached. If this property is set to
1099 1100  .Sy metadata ,
1100 1101  then only metadata is cached. The default value is
1101 1102  .Sy all .
1102 1103  .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1103 1104  Limits the amount of space a dataset and its descendents can consume. This
1104 1105  property enforces a hard limit on the amount of space used. This includes all
1105 1106  space consumed by descendents, including file systems and snapshots. Setting a
1106 1107  quota on a descendent of a dataset that already has a quota does not override
1107 1108  the ancestor's quota, but rather imposes an additional limit.
1108 1109  .Pp
1109 1110  Quotas cannot be set on volumes, as the
1110 1111  .Sy volsize
1111 1112  property acts as an implicit quota.
1112 1113  .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1113 1114  Limits the number of snapshots that can be created on a dataset and its
1114 1115  descendents. Setting a
1115 1116  .Sy snapshot_limit
1116 1117  on a descendent of a dataset that already has a
1117 1118  .Sy snapshot_limit
1118 1119  does not override the ancestor's
1119 1120  .Sy snapshot_limit ,
1120 1121  but rather imposes an additional limit. The limit is not enforced if the user is
1121 1122  allowed to change the limit. For example, this means that recursive snapshots
1122 1123  taken from the global zone are counted against each delegated dataset within
1123 1124  a zone. This feature must be enabled to be used
1124 1125  .Po see
1125 1126  .Xr zpool-features 5
1126 1127  .Pc .
1127 1128  .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1128 1129  Limits the amount of space consumed by the specified user. User space
1129 1130  consumption is identified by the
1130 1131  .Sy userspace@ Ns Em user
1131 1132  property.
1132 1133  .Pp
1133 1134  Enforcement of user quotas may be delayed by several seconds. This delay means
1134 1135  that a user might exceed their quota before the system notices that they are
1135 1136  over quota and begins to refuse additional writes with the
1136 1137  .Er EDQUOT
1137 1138  error message. See the
1138 1139  .Nm zfs Cm userspace
1139 1140  subcommand for more information.
1140 1141  .Pp
1141 1142  Unprivileged users can only access their own groups' space usage. The root
1142 1143  user, or a user who has been granted the
1143 1144  .Sy userquota
1144 1145  privilege with
1145 1146  .Nm zfs Cm allow ,
1146 1147  can get and set everyone's quota.
1147 1148  .Pp
1148 1149  This property is not available on volumes, on file systems before version 4, or
1149 1150  on pools before version 15. The
1150 1151  .Sy userquota@ Ns Em ...
1151 1152  properties are not displayed by
1152 1153  .Nm zfs Cm get Sy all .
1153 1154  The user's name must be appended after the
1154 1155  .Sy @
1155 1156  symbol, using one of the following forms:
1156 1157  .Bl -bullet
1157 1158  .It
1158 1159  .Em POSIX name
1159 1160  .Po for example,
1160 1161  .Sy joe
1161 1162  .Pc
1162 1163  .It
1163 1164  .Em POSIX numeric ID
1164 1165  .Po for example,
1165 1166  .Sy 789
1166 1167  .Pc
1167 1168  .It
1168 1169  .Em SID name
1169 1170  .Po for example,
1170 1171  .Sy joe.smith@mydomain
1171 1172  .Pc
1172 1173  .It
1173 1174  .Em SID numeric ID
1174 1175  .Po for example,
1175 1176  .Sy S-1-123-456-789
1176 1177  .Pc
1177 1178  .El
1178 1179  .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1179 1180  Limits the amount of space consumed by the specified group. Group space
1180 1181  consumption is identified by the
1181 1182  .Sy groupused@ Ns Em group
1182 1183  property.
1183 1184  .Pp
1184 1185  Unprivileged users can access only their own groups' space usage. The root
1185 1186  user, or a user who has been granted the
1186 1187  .Sy groupquota
1187 1188  privilege with
1188 1189  .Nm zfs Cm allow ,
1189 1190  can get and set all groups' quotas.
1190 1191  .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1191 1192  Controls whether this dataset can be modified. The default value is
1192 1193  .Sy off .
1193 1194  .Pp
1194 1195  This property can also be referred to by its shortened column name,
1195 1196  .Sy rdonly .
1196 1197  .It Sy recordsize Ns = Ns Em size
1197 1198  Specifies a suggested block size for files in the file system. This property is
1198 1199  designed solely for use with database workloads that access files in fixed-size
1199 1200  records. ZFS automatically tunes block sizes according to internal algorithms
1200 1201  optimized for typical access patterns.
1201 1202  .Pp
1202 1203  For databases that create very large files but access them in small random
1203 1204  chunks, these algorithms may be suboptimal. Specifying a
1204 1205  .Sy recordsize
1205 1206  greater than or equal to the record size of the database can result in
1206 1207  significant performance gains. Use of this property for general purpose file
1207 1208  systems is strongly discouraged, and may adversely affect performance.
1208 1209  .Pp
1209 1210  The size specified must be a power of two greater than or equal to 512 and less
1210 1211  than or equal to 128 Kbytes. If the
1211 1212  .Sy large_blocks
1212 1213  feature is enabled on the pool, the size may be up to 1 Mbyte. See
1213 1214  .Xr zpool-features 5
1214 1215  for details on ZFS feature flags.
1215 1216  .Pp
1216 1217  Changing the file system's
1217 1218  .Sy recordsize
1218 1219  affects only files created afterward; existing files are unaffected.
1219 1220  .Pp
1220 1221  This property can also be referred to by its shortened column name,
1221 1222  .Sy recsize .
1222 1223  .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1223 1224  Controls what types of metadata are stored redundantly. ZFS stores an extra copy
1224 1225  of metadata, so that if a single block is corrupted, the amount of user data
1225 1226  lost is limited. This extra copy is in addition to any redundancy provided at
1226 1227  the pool level
1227 1228  .Pq e.g. by mirroring or RAID-Z ,
1228 1229  and is in addition to an extra copy specified by the
1229 1230  .Sy copies
1230 1231  property
1231 1232  .Pq up to a total of 3 copies .
1232 1233  For example if the pool is mirrored,
1233 1234  .Sy copies Ns = Ns 2 ,
1234 1235  and
1235 1236  .Sy redundant_metadata Ns = Ns Sy most ,
1236 1237  then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1237 1238  metadata.
1238 1239  .Pp
1239 1240  When set to
1240 1241  .Sy all ,
1241 1242  ZFS stores an extra copy of all metadata. If a single on-disk block is corrupt,
1242 1243  at worst a single block of user data
1243 1244  .Po which is
1244 1245  .Sy recordsize
1245 1246  bytes long
1246 1247  .Pc
1247 1248  can be lost.
1248 1249  .Pp
1249 1250  When set to
1250 1251  .Sy most ,
1251 1252  ZFS stores an extra copy of most types of metadata. This can improve performance
1252 1253  of random writes, because less metadata must be written. In practice, at worst
1253 1254  about 100 blocks
1254 1255  .Po of
1255 1256  .Sy recordsize
1256 1257  bytes each
1257 1258  .Pc
1258 1259  of user data can be lost if a single on-disk block is corrupt. The exact
1259 1260  behavior of which metadata blocks are stored redundantly may change in future
1260 1261  releases.
1261 1262  .Pp
1262 1263  The default value is
1263 1264  .Sy all .
1264 1265  .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1265 1266  Limits the amount of space a dataset can consume. This property enforces a hard
1266 1267  limit on the amount of space used. This hard limit does not include space used
1267 1268  by descendents, including file systems and snapshots.
1268 1269  .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none
1269 1270  The minimum amount of space guaranteed to a dataset, not including its
1270 1271  descendents. When the amount of space used is below this value, the dataset is
1271 1272  treated as if it were taking up the amount of space specified by
1272 1273  .Sy refreservation .
1273 1274  The
1274 1275  .Sy refreservation
1275 1276  reservation is accounted for in the parent datasets' space used, and counts
1276 1277  against the parent datasets' quotas and reservations.
1277 1278  .Pp
1278 1279  If
1279 1280  .Sy refreservation
1280 1281  is set, a snapshot is only allowed if there is enough free pool space outside of
1281 1282  this reservation to accommodate the current number of
1282 1283  .Qq referenced
1283 1284  bytes in the dataset.
1284 1285  .Pp
1285 1286  This property can also be referred to by its shortened column name,
1286 1287  .Sy refreserv .
1287 1288  .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1288 1289  The minimum amount of space guaranteed to a dataset and its descendents. When
1289 1290  the amount of space used is below this value, the dataset is treated as if it
1290 1291  were taking up the amount of space specified by its reservation. Reservations
1291 1292  are accounted for in the parent datasets' space used, and count against the
1292 1293  parent datasets' quotas and reservations.
1293 1294  .Pp
1294 1295  This property can also be referred to by its shortened column name,
1295 1296  .Sy reserv .
1296 1297  .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1297 1298  Controls what is cached in the secondary cache
1298 1299  .Pq L2ARC .
1299 1300  If this property is set to
1300 1301  .Sy all ,
1301 1302  then both user data and metadata is cached. If this property is set to
1302 1303  .Sy none ,
1303 1304  then neither user data nor metadata is cached. If this property is set to
1304 1305  .Sy metadata ,
1305 1306  then only metadata is cached. The default value is
1306 1307  .Sy all .
1307 1308  .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1308 1309  Controls whether the setuid bit is respected for the file system. The default
1309 1310  value is
1310 1311  .Sy on .
1311 1312  .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1312 1313  Controls whether the file system is shared via SMB, and what options are to be
1313 1314  used. A file system with the
1314 1315  .Sy sharesmb
1315 1316  property set to
1316 1317  .Sy off
1317 1318  is managed through traditional tools such as
1318 1319  .Xr sharemgr 1M .
1319 1320  Otherwise, the file system is automatically shared and unshared with the
1320 1321  .Nm zfs Cm share
1321 1322  and
1322 1323  .Nm zfs Cm unshare
1323 1324  commands. If the property is set to
1324 1325  .Sy on ,
1325 1326  the
1326 1327  .Xr sharemgr 1M
1327 1328  command is invoked with no options. Otherwise, the
1328 1329  .Xr sharemgr 1M
1329 1330  command is invoked with options equivalent to the contents of this property.
1330 1331  .Pp
1331 1332  Because SMB shares requires a resource name, a unique resource name is
1332 1333  constructed from the dataset name. The constructed name is a copy of the dataset
1333 1334  name except that the characters in the dataset name, which would be illegal in
1334 1335  the resource name, are replaced with underscore
1335 1336  .Pq Sy _
1336 1337  characters. A pseudo property
1337 1338  .Qq name
1338 1339  is also supported that allows you to replace the data set name with a specified
1339 1340  name. The specified name is then used to replace the prefix dataset in the case
1340 1341  of inheritance. For example, if the dataset
1341 1342  .Em data/home/john
1342 1343  is set to
1343 1344  .Sy name Ns = Ns Sy john ,
1344 1345  then
1345 1346  .Em data/home/john
1346 1347  has a resource name of
1347 1348  .Sy john .
1348 1349  If a child dataset
1349 1350  .Em data/home/john/backups
1350 1351  is shared, it has a resource name of
1351 1352  .Sy john_backups .
1352 1353  .Pp
1353 1354  When SMB shares are created, the SMB share name appears as an entry in the
1354 1355  .Pa .zfs/shares
1355 1356  directory. You can use the
1356 1357  .Nm ls
1357 1358  or
1358 1359  .Nm chmod
1359 1360  command to display the share-level ACLs on the entries in this directory.
1360 1361  .Pp
1361 1362  When the
1362 1363  .Sy sharesmb
1363 1364  property is changed for a dataset, the dataset and any children inheriting the
1364 1365  property are re-shared with the new options, only if the property was previously
1365 1366  set to
1366 1367  .Sy off ,
1367 1368  or if they were shared before the property was changed. If the new property is
1368 1369  set to
1369 1370  .Sy off ,
1370 1371  the file systems are unshared.
1371 1372  .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1372 1373  Controls whether the file system is shared via NFS, and what options are to be
1373 1374  used. A file system with a
1374 1375  .Sy sharenfs
1375 1376  property of
1376 1377  .Sy off
1377 1378  is managed through traditional tools such as
1378 1379  .Xr share 1M ,
1379 1380  .Xr unshare 1M ,
1380 1381  and
1381 1382  .Xr dfstab 4 .
1382 1383  Otherwise, the file system is automatically shared and unshared with the
1383 1384  .Nm zfs Cm share
1384 1385  and
1385 1386  .Nm zfs Cm unshare
1386 1387  commands. If the property is set to
1387 1388  .Sy on ,
1388 1389  .Xr share 1M
1389 1390  command is invoked with no options. Otherwise, the
1390 1391  .Xr share 1M
1391 1392  command is invoked with options equivalent to the contents of this property.
1392 1393  .Pp
1393 1394  When the
1394 1395  .Sy sharenfs
1395 1396  property is changed for a dataset, the dataset and any children inheriting the
1396 1397  property are re-shared with the new options, only if the property was previously
1397 1398  .Sy off ,
1398 1399  or if they were shared before the property was changed. If the new property is
1399 1400  .Sy off ,
1400 1401  the file systems are unshared.
1401 1402  .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1402 1403  Provide a hint to ZFS about handling of synchronous requests in this dataset. If
1403 1404  .Sy logbias
1404 1405  is set to
1405 1406  .Sy latency
1406 1407  .Pq the default ,
1407 1408  ZFS will use pool log devices
1408 1409  .Pq if configured
1409 1410  to handle the requests at low latency. If
1410 1411  .Sy logbias
1411 1412  is set to
1412 1413  .Sy throughput ,
1413 1414  ZFS will not use configured pool log devices. ZFS will instead optimize
1414 1415  synchronous operations for global pool throughput and efficient use of
1415 1416  resources.
1416 1417  .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1417 1418  Controls whether the
1418 1419  .Pa .zfs
1419 1420  directory is hidden or visible in the root of the file system as discussed in
1420 1421  the
1421 1422  .Sx Snapshots
1422 1423  section. The default value is
1423 1424  .Sy hidden .
1424 1425  .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1425 1426  Controls the behavior of synchronous requests
1426 1427  .Pq e.g. fsync, O_DSYNC .
1427 1428  .Sy standard
1428 1429  is the
1429 1430  .Tn POSIX
1430 1431  specified behavior of ensuring all synchronous requests are written to stable
1431 1432  storage and all devices are flushed to ensure data is not cached by device
1432 1433  controllers
1433 1434  .Pq this is the default .
1434 1435  .Sy always
1435 1436  causes every file system transaction to be written and flushed before its
1436 1437  system call returns. This has a large performance penalty.
1437 1438  .Sy disabled
1438 1439  disables synchronous requests. File system transactions are only committed to
1439 1440  stable storage periodically. This option will give the highest performance.
1440 1441  However, it is very dangerous as ZFS would be ignoring the synchronous
1441 1442  transaction demands of applications such as databases or NFS. Administrators
1442 1443  should only use this option when the risks are understood.
1443 1444  .It Sy version Ns = Ns Em N Ns | Ns Sy current
1444 1445  The on-disk version of this file system, which is independent of the pool
1445 1446  version. This property can only be set to later supported versions. See the
1446 1447  .Nm zfs Cm upgrade
1447 1448  command.
1448 1449  .It Sy volsize Ns = Ns Em size
1449 1450  For volumes, specifies the logical size of the volume. By default, creating a
1450 1451  volume establishes a reservation of equal size. For storage pools with a version
1451 1452  number of 9 or higher, a
1452 1453  .Sy refreservation
1453 1454  is set instead. Any changes to
1454 1455  .Sy volsize
1455 1456  are reflected in an equivalent change to the reservation
1456 1457  .Po or
1457 1458  .Sy refreservation
1458 1459  .Pc .
1459 1460  The
1460 1461  .Sy volsize
1461 1462  can only be set to a multiple of
1462 1463  .Sy volblocksize ,
1463 1464  and cannot be zero.
1464 1465  .Pp
1465 1466  The reservation is kept equal to the volume's logical size to prevent unexpected
1466 1467  behavior for consumers. Without the reservation, the volume could run out of
1467 1468  space, resulting in undefined behavior or data corruption, depending on how the
1468 1469  volume is used. These effects can also occur when the volume size is changed
1469 1470  while it is in use
1470 1471  .Pq particularly when shrinking the size .
1471 1472  Extreme care should be used when adjusting the volume size.
1472 1473  .Pp
1473 1474  Though not recommended, a
1474 1475  .Qq sparse volume
1475 1476  .Po also known as
1476 1477  .Qq thin provisioning
1477 1478  .Pc
1478 1479  can be created by specifying the
1479 1480  .Fl s
1480 1481  option to the
1481 1482  .Nm zfs Cm create Fl V
1482 1483  command, or by changing the reservation after the volume has been created. A
1483 1484  .Qq sparse volume
1484 1485  is a volume where the reservation is less then the volume size. Consequently,
1485 1486  writes to a sparse volume can fail with
1486 1487  .Er ENOSPC
1487 1488  when the pool is low on space. For a sparse volume, changes to
1488 1489  .Sy volsize
1489 1490  are not reflected in the reservation.
1490 1491  .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1491 1492  Controls whether regular files should be scanned for viruses when a file is
1492 1493  opened and closed. In addition to enabling this property, the virus scan
1493 1494  service must also be enabled for virus scanning to occur. The default value is
1494 1495  .Sy off .
1495 1496  .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off
1496 1497  Controls whether extended attributes are enabled for this file system. The
1497 1498  default value is
1498 1499  .Sy on .
1499 1500  .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1500 1501  Controls whether the dataset is managed from a non-global zone. See the
1501 1502  .Sx Zones
1502 1503  section for more information. The default value is
1503 1504  .Sy off .
1504 1505  .El
1505 1506  .Pp
1506 1507  The following three properties cannot be changed after the file system is
1507 1508  created, and therefore, should be set when the file system is created. If the
1508 1509  properties are not set with the
1509 1510  .Nm zfs Cm create
1510 1511  or
1511 1512  .Nm zpool Cm create
1512 1513  commands, these properties are inherited from the parent dataset. If the parent
1513 1514  dataset lacks these properties due to having been created prior to these
1514 1515  features being supported, the new file system will have the default values for
1515 1516  these properties.
1516 1517  .Bl -tag -width ""
1517 1518  .It Xo
1518 1519  .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1519 1520  .Sy insensitive Ns | Ns Sy mixed
1520 1521  .Xc
1521 1522  Indicates whether the file name matching algorithm used by the file system
1522 1523  should be case-sensitive, case-insensitive, or allow a combination of both
1523 1524  styles of matching. The default value for the
1524 1525  .Sy casesensitivity
1525 1526  property is
1526 1527  .Sy sensitive .
1527 1528  Traditionally,
1528 1529  .Ux
1529 1530  and
1530 1531  .Tn POSIX
1531 1532  file systems have case-sensitive file names.
1532 1533  .Pp
1533 1534  The
1534 1535  .Sy mixed
1535 1536  value for the
1536 1537  .Sy casesensitivity
1537 1538  property indicates that the file system can support requests for both
1538 1539  case-sensitive and case-insensitive matching behavior. Currently,
1539 1540  case-insensitive matching behavior on a file system that supports mixed behavior
1540 1541  is limited to the SMB server product. For more information about the
1541 1542  .Sy mixed
1542 1543  value behavior, see the "ZFS Administration Guide".
1543 1544  .It Xo
1544 1545  .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1545 1546  .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1546 1547  .Xc
1547 1548  Indicates whether the file system should perform a
1548 1549  .Sy unicode
1549 1550  normalization of file names whenever two file names are compared, and which
1550 1551  normalization algorithm should be used. File names are always stored unmodified,
1551 1552  names are normalized as part of any comparison process. If this property is set
1552 1553  to a legal value other than
1553 1554  .Sy none ,
1554 1555  and the
1555 1556  .Sy utf8only
1556 1557  property was left unspecified, the
1557 1558  .Sy utf8only
1558 1559  property is automatically set to
1559 1560  .Sy on .
1560 1561  The default value of the
1561 1562  .Sy normalization
1562 1563  property is
1563 1564  .Sy none .
1564 1565  This property cannot be changed after the file system is created.
1565 1566  .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1566 1567  Indicates whether the file system should reject file names that include
1567 1568  characters that are not present in the
1568 1569  .Sy UTF-8
1569 1570  character code set. If this property is explicitly set to
1570 1571  .Sy off ,
1571 1572  the normalization property must either not be explicitly set or be set to
1572 1573  .Sy none .
1573 1574  The default value for the
1574 1575  .Sy utf8only
1575 1576  property is
1576 1577  .Sy off .
1577 1578  This property cannot be changed after the file system is created.
1578 1579  .El
1579 1580  .Pp
1580 1581  The
1581 1582  .Sy casesensitivity ,
1582 1583  .Sy normalization ,
1583 1584  and
1584 1585  .Sy utf8only
1585 1586  properties are also new permissions that can be assigned to non-privileged users
1586 1587  by using the ZFS delegated administration feature.
1587 1588  .Ss "Temporary Mount Point Properties"
1588 1589  When a file system is mounted, either through
1589 1590  .Xr mount 1M
1590 1591  for legacy mounts or the
1591 1592  .Nm zfs Cm mount
1592 1593  command for normal file systems, its mount options are set according to its
1593 1594  properties. The correlation between properties and mount options is as follows:
1594 1595  .Bd -literal
1595 1596      PROPERTY                MOUNT OPTION
1596 1597      devices                 devices/nodevices
1597 1598      exec                    exec/noexec
1598 1599      readonly                ro/rw
1599 1600      setuid                  setuid/nosetuid
1600 1601      xattr                   xattr/noxattr
1601 1602  .Ed
1602 1603  .Pp
1603 1604  In addition, these options can be set on a per-mount basis using the
1604 1605  .Fl o
1605 1606  option, without affecting the property that is stored on disk. The values
1606 1607  specified on the command line override the values stored in the dataset. The
1607 1608  .Sy nosuid
1608 1609  option is an alias for
1609 1610  .Sy nodevices Ns , Ns Sy nosetuid .
1610 1611  These properties are reported as
1611 1612  .Qq temporary
1612 1613  by the
1613 1614  .Nm zfs Cm get
1614 1615  command. If the properties are changed while the dataset is mounted, the new
1615 1616  setting overrides any temporary settings.
1616 1617  .Ss "User Properties"
1617 1618  In addition to the standard native properties, ZFS supports arbitrary user
1618 1619  properties. User properties have no effect on ZFS behavior, but applications or
1619 1620  administrators can use them to annotate datasets
1620 1621  .Pq file systems, volumes, and snapshots .
1621 1622  .Pp
1622 1623  User property names must contain a colon
1623 1624  .Pq Qq Sy \&:
1624 1625  character to distinguish them from native properties. They may contain lowercase
1625 1626  letters, numbers, and the following punctuation characters: colon
1626 1627  .Pq Qq Sy \&: ,
1627 1628  dash
1628 1629  .Pq Qq Sy - ,
1629 1630  period
1630 1631  .Pq Qq Sy \&. ,
1631 1632  and underscore
1632 1633  .Pq Qq Sy _ .
1633 1634  The expected convention is that the property name is divided into two portions
1634 1635  such as
1635 1636  .Em module Ns : Ns Em property ,
1636 1637  but this namespace is not enforced by ZFS.
1637 1638  User property names can be at most 256 characters, and cannot begin with a dash
1638 1639  .Pq Qq Sy - .
1639 1640  .Pp
1640 1641  When making programmatic use of user properties, it is strongly suggested to use
1641 1642  a reversed
1642 1643  .Sy DNS
1643 1644  domain name for the
1644 1645  .Em module
1645 1646  component of property names to reduce the chance that two
1646 1647  independently-developed packages use the same property name for different
1647 1648  purposes.
1648 1649  .Pp
1649 1650  The values of user properties are arbitrary strings, are always inherited, and
1650 1651  are never validated. All of the commands that operate on properties
1651 1652  .Po Nm zfs Cm list ,
1652 1653  .Nm zfs Cm get ,
1653 1654  .Nm zfs Cm set ,
1654 1655  and so forth
1655 1656  .Pc
1656 1657  can be used to manipulate both native properties and user properties. Use the
1657 1658  .Nm zfs Cm inherit
1658 1659  command to clear a user property . If the property is not defined in any parent
1659 1660  dataset, it is removed entirely. Property values are limited to 1024
1660 1661  characters.
1661 1662  .Ss ZFS Volumes as Swap or Dump Devices
1662 1663  During an initial installation a swap device and dump device are created on ZFS
1663 1664  volumes in the ZFS root pool. By default, the swap area size is based on 1/2 the
1664 1665  size of physical memory up to 2 Gbytes. The size of the dump device depends on
1665 1666  the kernel's requirements at installation time. Separate ZFS volumes must be
1666 1667  used for the swap area and dump devices. Do not swap to a file on a ZFS file
1667 1668  system. A ZFS swap file configuration is not supported.
1668 1669  .Pp
1669 1670  If you need to change your swap area or dump device after the system is
1670 1671  installed or upgraded, use the
1671 1672  .Xr swap 1M
1672 1673  and
1673 1674  .Xr dumpadm 1M
1674 1675  commands.
1675 1676  .Sh SUBCOMMANDS
1676 1677  All subcommands that modify state are logged persistently to the pool in their
1677 1678  original form.
1678 1679  .Bl -tag -width ""
1679 1680  .It Nm Fl \?
1680 1681  Displays a help message.
1681 1682  .It Xo
1682 1683  .Nm
1683 1684  .Cm create
1684 1685  .Op Fl p
1685 1686  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1686 1687  .Ar filesystem
1687 1688  .Xc
1688 1689  Creates a new ZFS file system. The file system is automatically mounted
1689 1690  according to the
1690 1691  .Sy mountpoint
1691 1692  property inherited from the parent.
1692 1693  .Bl -tag -width "-o"
1693 1694  .It Fl o Ar property Ns = Ns Ar value
1694 1695  Sets the specified property as if the command
1695 1696  .Nm zfs Cm set Ar property Ns = Ns Ar value
1696 1697  was invoked at the same time the dataset was created. Any editable ZFS property
1697 1698  can also be set at creation time. Multiple
1698 1699  .Fl o
1699 1700  options can be specified. An error results if the same property is specified in
1700 1701  multiple
1701 1702  .Fl o
1702 1703  options.
1703 1704  .It Fl p
1704 1705  Creates all the non-existing parent datasets. Datasets created in this manner
1705 1706  are automatically mounted according to the
1706 1707  .Sy mountpoint
1707 1708  property inherited from their parent. Any property specified on the command line
1708 1709  using the
1709 1710  .Fl o
1710 1711  option is ignored. If the target filesystem already exists, the operation
1711 1712  completes successfully.
1712 1713  .El
1713 1714  .It Xo
1714 1715  .Nm
1715 1716  .Cm create
1716 1717  .Op Fl ps
1717 1718  .Op Fl b Ar blocksize
1718 1719  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1719 1720  .Fl V Ar size Ar volume
1720 1721  .Xc
1721 1722  Creates a volume of the given size. The volume is exported as a block device in
1722 1723  .Pa /dev/zvol/{dsk,rdsk}/path ,
1723 1724  where
1724 1725  .Em path
1725 1726  is the name of the volume in the ZFS namespace. The size represents the logical
1726 1727  size as exported by the device. By default, a reservation of equal size is
1727 1728  created.
1728 1729  .Pp
1729 1730  .Ar size
1730 1731  is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
1731 1732  has an integral number of blocks regardless of
1732 1733  .Sy blocksize .
1733 1734  .Bl -tag -width "-b"
1734 1735  .It Fl b Ar blocksize
1735 1736  Equivalent to
1736 1737  .Fl o Sy volblocksize Ns = Ns Ar blocksize .
1737 1738  If this option is specified in conjunction with
1738 1739  .Fl o Sy volblocksize ,
1739 1740  the resulting behavior is undefined.
1740 1741  .It Fl o Ar property Ns = Ns Ar value
1741 1742  Sets the specified property as if the
1742 1743  .Nm zfs Cm set Ar property Ns = Ns Ar value
1743 1744  command was invoked at the same time the dataset was created. Any editable ZFS
1744 1745  property can also be set at creation time. Multiple
1745 1746  .Fl o
1746 1747  options can be specified. An error results if the same property is specified in
1747 1748  multiple
1748 1749  .Fl o
1749 1750  options.
1750 1751  .It Fl p
1751 1752  Creates all the non-existing parent datasets. Datasets created in this manner
1752 1753  are automatically mounted according to the
1753 1754  .Sy mountpoint
1754 1755  property inherited from their parent. Any property specified on the command line
1755 1756  using the
1756 1757  .Fl o
1757 1758  option is ignored. If the target filesystem already exists, the operation
1758 1759  completes successfully.
1759 1760  .It Fl s
1760 1761  Creates a sparse volume with no reservation. See
1761 1762  .Sy volsize
1762 1763  in the
1763 1764  .Sx Native Properties
1764 1765  section for more information about sparse volumes.
1765 1766  .El
1766 1767  .It Xo
1767 1768  .Nm
1768 1769  .Cm destroy
1769 1770  .Op Fl Rfnprv
1770 1771  .Ar filesystem Ns | Ns Ar volume
1771 1772  .Xc
1772 1773  Destroys the given dataset. By default, the command unshares any file systems
1773 1774  that are currently shared, unmounts any file systems that are currently
1774 1775  mounted, and refuses to destroy a dataset that has active dependents
1775 1776  .Pq children or clones .
1776 1777  .Bl -tag -width "-R"
1777 1778  .It Fl R
1778 1779  Recursively destroy all dependents, including cloned file systems outside the
1779 1780  target hierarchy.
1780 1781  .It Fl f
1781 1782  Force an unmount of any file systems using the
1782 1783  .Nm unmount Fl f
1783 1784  command. This option has no effect on non-file systems or unmounted file
1784 1785  systems.
1785 1786  .It Fl n
1786 1787  Do a dry-run
1787 1788  .Pq Qq No-op
1788 1789  deletion. No data will be deleted. This is useful in conjunction with the
1789 1790  .Fl v
1790 1791  or
1791 1792  .Fl p
1792 1793  flags to determine what data would be deleted.
1793 1794  .It Fl p
1794 1795  Print machine-parsable verbose information about the deleted data.
1795 1796  .It Fl r
1796 1797  Recursively destroy all children.
1797 1798  .It Fl v
1798 1799  Print verbose information about the deleted data.
1799 1800  .El
1800 1801  .Pp
1801 1802  Extreme care should be taken when applying either the
1802 1803  .Fl r
1803 1804  or the
1804 1805  .Fl R
1805 1806  options, as they can destroy large portions of a pool and cause unexpected
1806 1807  behavior for mounted file systems in use.
1807 1808  .It Xo
1808 1809  .Nm
1809 1810  .Cm destroy
1810 1811  .Op Fl Rdnprv
1811 1812  .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
1812 1813  .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
1813 1814  .Xc
1814 1815  The given snapshots are destroyed immediately if and only if the
1815 1816  .Nm zfs Cm destroy
1816 1817  command without the
1817 1818  .Fl d
1818 1819  option would have destroyed it. Such immediate destruction would occur, for
1819 1820  example, if the snapshot had no clones and the user-initiated reference count
1820 1821  were zero.
1821 1822  .Pp
1822 1823  If a snapshot does not qualify for immediate destruction, it is marked for
1823 1824  deferred deletion. In this state, it exists as a usable, visible snapshot until
1824 1825  both of the preconditions listed above are met, at which point it is destroyed.
1825 1826  .Pp
1826 1827  An inclusive range of snapshots may be specified by separating the first and
1827 1828  last snapshots with a percent sign. The first and/or last snapshots may be left
1828 1829  blank, in which case the filesystem's oldest or newest snapshot will be implied.
1829 1830  .Pp
1830 1831  Multiple snapshots
1831 1832  .Pq or ranges of snapshots
1832 1833  of the same filesystem or volume may be specified in a comma-separated list of
1833 1834  snapshots. Only the snapshot's short name
1834 1835  .Po the part after the
1835 1836  .Sy @
1836 1837  .Pc
1837 1838  should be specified when using a range or comma-separated list to identify
1838 1839  multiple snapshots.
1839 1840  .Bl -tag -width "-R"
1840 1841  .It Fl R
1841 1842  Recursively destroy all clones of these snapshots, including the clones,
1842 1843  snapshots, and children. If this flag is specified, the
1843 1844  .Fl d
1844 1845  flag will have no effect.
1845 1846  .It Fl d
1846 1847  Defer snapshot deletion.
1847 1848  .It Fl n
1848 1849  Do a dry-run
1849 1850  .Pq Qq No-op
1850 1851  deletion. No data will be deleted. This is
1851 1852  useful in conjunction with the
1852 1853  .Fl p
1853 1854  or
1854 1855  .Fl v
1855 1856  flags to determine what data would be deleted.
1856 1857  .It Fl p
1857 1858  Print machine-parsable verbose information about the deleted data.
1858 1859  .It Fl r
1859 1860  Destroy
1860 1861  .Pq or mark for deferred deletion
1861 1862  all snapshots with this name in descendent file systems.
1862 1863  .It Fl v
1863 1864  Print verbose information about the deleted data.
1864 1865  .Pp
1865 1866  Extreme care should be taken when applying either the
1866 1867  .Fl r
1867 1868  or the
1868 1869  .Fl R
1869 1870  options, as they can destroy large portions of a pool and cause unexpected
1870 1871  behavior for mounted file systems in use.
1871 1872  .El
1872 1873  .It Xo
1873 1874  .Nm
1874 1875  .Cm destroy
1875 1876  .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
1876 1877  .Xc
1877 1878  The given bookmark is destroyed.
1878 1879  .It Xo
1879 1880  .Nm
1880 1881  .Cm snapshot
1881 1882  .Op Fl r
1882 1883  .Oo Fl o Ar property Ns = Ns value Oc Ns ...
1883 1884  .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
1884 1885  .Xc
1885 1886  Creates snapshots with the given names. All previous modifications by successful
1886 1887  system calls to the file system are part of the snapshots. Snapshots are taken
1887 1888  atomically, so that all snapshots correspond to the same moment in time. See the
1888 1889  .Sx Snapshots
1889 1890  section for details.
1890 1891  .Bl -tag -width "-o"
1891 1892  .It Fl o Ar property Ns = Ns Ar value
1892 1893  Sets the specified property; see
1893 1894  .Nm zfs Cm create
1894 1895  for details.
1895 1896  .It Fl r
1896 1897  Recursively create snapshots of all descendent datasets
1897 1898  .El
1898 1899  .It Xo
1899 1900  .Nm
1900 1901  .Cm rollback
1901 1902  .Op Fl Rfr
1902 1903  .Ar snapshot
1903 1904  .Xc
1904 1905  Roll back the given dataset to a previous snapshot. When a dataset is rolled
1905 1906  back, all data that has changed since the snapshot is discarded, and the dataset
1906 1907  reverts to the state at the time of the snapshot. By default, the command
1907 1908  refuses to roll back to a snapshot other than the most recent one. In order to
1908 1909  do so, all intermediate snapshots and bookmarks must be destroyed by specifying
1909 1910  the
1910 1911  .Fl r
1911 1912  option.
1912 1913  .Pp
1913 1914  The
1914 1915  .Fl rR
1915 1916  options do not recursively destroy the child snapshots of a recursive snapshot.
1916 1917  Only direct snapshots of the specified filesystem are destroyed by either of
1917 1918  these options. To completely roll back a recursive snapshot, you must rollback
1918 1919  the individual child snapshots.
1919 1920  .Bl -tag -width "-R"
1920 1921  .It Fl R
1921 1922  Destroy any more recent snapshots and bookmarks, as well as any clones of those
1922 1923  snapshots.
1923 1924  .It Fl f
1924 1925  Used with the
1925 1926  .Fl R
1926 1927  option to force an unmount of any clone file systems that are to be destroyed.
1927 1928  .It Fl r
1928 1929  Destroy any snapshots and bookmarks more recent than the one specified.
1929 1930  .El
1930 1931  .It Xo
1931 1932  .Nm
1932 1933  .Cm clone
1933 1934  .Op Fl p
1934 1935  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1935 1936  .Ar snapshot Ar filesystem Ns | Ns Ar volume
1936 1937  .Xc
1937 1938  Creates a clone of the given snapshot. See the
1938 1939  .Sx Clones
1939 1940  section for details. The target dataset can be located anywhere in the ZFS
1940 1941  hierarchy, and is created as the same type as the original.
1941 1942  .Bl -tag -width "-o"
1942 1943  .It Fl o Ar property Ns = Ns Ar value
1943 1944  Sets the specified property; see
1944 1945  .Nm zfs Cm create
1945 1946  for details.
1946 1947  .It Fl p
1947 1948  Creates all the non-existing parent datasets. Datasets created in this manner
1948 1949  are automatically mounted according to the
1949 1950  .Sy mountpoint
1950 1951  property inherited from their parent. If the target filesystem or volume already
1951 1952  exists, the operation completes successfully.
1952 1953  .El
1953 1954  .It Xo
1954 1955  .Nm
1955 1956  .Cm promote
1956 1957  .Ar clone-filesystem
1957 1958  .Xc
1958 1959  Promotes a clone file system to no longer be dependent on its
1959 1960  .Qq origin
1960 1961  snapshot. This makes it possible to destroy the file system that the clone was
1961 1962  created from. The clone parent-child dependency relationship is reversed, so
1962 1963  that the origin file system becomes a clone of the specified file system.
1963 1964  .Pp
1964 1965  The snapshot that was cloned, and any snapshots previous to this snapshot, are
1965 1966  now owned by the promoted clone. The space they use moves from the origin file
1966 1967  system to the promoted clone, so enough space must be available to accommodate
1967 1968  these snapshots. No new space is consumed by this operation, but the space
1968 1969  accounting is adjusted. The promoted clone must not have any conflicting
1969 1970  snapshot names of its own. The
1970 1971  .Cm rename
1971 1972  subcommand can be used to rename any conflicting snapshots.
1972 1973  .It Xo
1973 1974  .Nm
1974 1975  .Cm rename
1975 1976  .Op Fl f
1976 1977  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1977 1978  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1978 1979  .br
1979 1980  .Nm
1980 1981  .Cm rename
1981 1982  .Op Fl fp
1982 1983  .Ar filesystem Ns | Ns Ar volume
1983 1984  .Ar filesystem Ns | Ns Ar volume
1984 1985  .Xc
1985 1986  Renames the given dataset. The new target can be located anywhere in the ZFS
1986 1987  hierarchy, with the exception of snapshots. Snapshots can only be renamed within
1987 1988  the parent file system or volume. When renaming a snapshot, the parent file
1988 1989  system of the snapshot does not need to be specified as part of the second
1989 1990  argument. Renamed file systems can inherit new mount points, in which case they
1990 1991  are unmounted and remounted at the new mount point.
1991 1992  .Bl -tag -width "-a"
1992 1993  .It Fl f
1993 1994  Force unmount any filesystems that need to be unmounted in the process.
1994 1995  .It Fl p
1995 1996  Creates all the nonexistent parent datasets. Datasets created in this manner are
1996 1997  automatically mounted according to the
1997 1998  .Sy mountpoint
1998 1999  property inherited from their parent.
1999 2000  .El
2000 2001  .It Xo
2001 2002  .Nm
2002 2003  .Cm rename
2003 2004  .Fl r
2004 2005  .Ar snapshot Ar snapshot
2005 2006  .Xc
2006 2007  Recursively rename the snapshots of all descendent datasets. Snapshots are the
2007 2008  only dataset that can be renamed recursively.
2008 2009  .It Xo
2009 2010  .Nm
2010 2011  .Cm list
2011 2012  .Op Fl r Ns | Ns Fl d Ar depth
2012 2013  .Op Fl Hp
2013 2014  .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2014 2015  .Oo Fl s Ar property Oc Ns ...
2015 2016  .Oo Fl S Ar property Oc Ns ...
2016 2017  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2017 2018  .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2018 2019  .Xc
2019 2020  Lists the property information for the given datasets in tabular form. If
2020 2021  specified, you can list property information by the absolute pathname or the
2021 2022  relative pathname. By default, all file systems and volumes are displayed.
2022 2023  Snapshots are displayed if the
2023 2024  .Sy listsnaps
2024 2025  property is
2025 2026  .Sy on
2026 2027  .Po the default is
2027 2028  .Sy off
2028 2029  .Pc .
2029 2030  The following fields are displayed,
2030 2031  .Sy name Ns , Ns Sy used Ns , Ns Sy available Ns , Ns Sy referenced Ns , Ns
2031 2032  .Sy mountpoint .
2032 2033  .Bl -tag -width "-H"
2033 2034  .It Fl H
2034 2035  Used for scripting mode. Do not print headers and separate fields by a single
2035 2036  tab instead of arbitrary white space.
2036 2037  .It Fl S Ar property
2037 2038  Same as the
2038 2039  .Fl s
2039 2040  option, but sorts by property in descending order.
2040 2041  .It Fl d Ar depth
2041 2042  Recursively display any children of the dataset, limiting the recursion to
2042 2043  .It Fl o Ar property
2043 2044  A comma-separated list of properties to display. The property must be:
2044 2045  .Bl -bullet
2045 2046  .It
2046 2047  One of the properties described in the
2047 2048  .Sx Native Properties
2048 2049  section
2049 2050  .It
2050 2051  A user property
2051 2052  .It
2052 2053  The value
2053 2054  .Sy name
2054 2055  to display the dataset name
2055 2056  .It
2056 2057  The value
2057 2058  .Sy space
2058 2059  to display space usage properties on file systems and volumes. This is a
2059 2060  shortcut for specifying
2060 2061  .Fl o Sy name Ns , Ns Sy avail Ns , Ns Sy used Ns , Ns Sy usedsnap Ns , Ns
2061 2062  .Sy usedds Ns , Ns Sy usedrefreserv Ns , Ns Sy usedchild Fl t
2062 2063  .Sy filesystem Ns , Ns Sy volume
2063 2064  syntax.
2064 2065  .El
2065 2066  .It Fl p
2066 2067  Display numbers in parsable
2067 2068  .Pq exact
2068 2069  values.
2069 2070  .It Fl r
2070 2071  Recursively display any children of the dataset on the command line.
2071 2072  .Ar depth .
2072 2073  A depth of
2073 2074  .Sy 1
2074 2075  will display only the dataset and its direct children.
2075 2076  .It Fl s Ar property
2076 2077  A property for sorting the output by column in ascending order based on the
2077 2078  value of the property. The property must be one of the properties described in
2078 2079  the
2079 2080  .Sx Properties
2080 2081  section, or the special value
2081 2082  .Sy name
2082 2083  to sort by the dataset name. Multiple properties can be specified at one time
2083 2084  using multiple
2084 2085  .Fl s
2085 2086  property options. Multiple
2086 2087  .Fl s
2087 2088  options are evaluated from left to right in decreasing order of importance. The
2088 2089  following is a list of sorting criteria:
2089 2090  .Bl -bullet
2090 2091  .It
2091 2092  Numeric types sort in numeric order.
2092 2093  .It
2093 2094  String types sort in alphabetical order.
2094 2095  .It
2095 2096  Types inappropriate for a row sort that row to the literal bottom, regardless of
2096 2097  the specified ordering.
2097 2098  .El
2098 2099  .Pp
2099 2100  If no sorting options are specified the existing behavior of
2100 2101  .Nm zfs Cm list
2101 2102  is preserved.
2102 2103  .It Fl t Ar type
2103 2104  A comma-separated list of types to display, where
2104 2105  .Ar type
2105 2106  is one of
2106 2107  .Sy filesystem ,
2107 2108  .Sy snapshot ,
2108 2109  .Sy volume ,
2109 2110  .Sy bookmark ,
2110 2111  or
2111 2112  .Sy all .
2112 2113  For example, specifying
2113 2114  .Fl t Sy snapshot
2114 2115  displays only snapshots.
2115 2116  .El
2116 2117  .It Xo
2117 2118  .Nm
2118 2119  .Cm set
2119 2120  .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2120 2121  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2121 2122  .Xc
2122 2123  Sets the property or list of properties to the given value(s) for each dataset.
2123 2124  Only some properties can be edited. See the
2124 2125  .Sx Properties
2125 2126  section for more information on what properties can be set and acceptable
2126 2127  values. Numeric values can be specified as exact values, or in a human-readable
2127 2128  form with a suffix of
2128 2129  .Sy B , K , M , G , T , P , E , Z
2129 2130  .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2130 2131  or zettabytes, respectively
2131 2132  .Pc .
2132 2133  User properties can be set on snapshots. For more information, see the
2133 2134  .Sx User Properties
2134 2135  section.
2135 2136  .It Xo
2136 2137  .Nm
2137 2138  .Cm get
2138 2139  .Op Fl r Ns | Ns Fl d Ar depth
2139 2140  .Op Fl Hp
2140 2141  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2141 2142  .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2142 2143  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2143 2144  .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2144 2145  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2145 2146  .Xc
2146 2147  Displays properties for the given datasets. If no datasets are specified, then
2147 2148  the command displays properties for all datasets on the system. For each
2148 2149  property, the following columns are displayed:
2149 2150  .Bd -literal
2150 2151      name      Dataset name
2151 2152      property  Property name
2152 2153      value     Property value
2153 2154      source    Property source. Can either be local, default,
2154 2155                temporary, inherited, or none (-).
2155 2156  .Ed
2156 2157  .Pp
2157 2158  All columns are displayed by default, though this can be controlled by using the
2158 2159  .Fl o
2159 2160  option. This command takes a comma-separated list of properties as described in
2160 2161  the
2161 2162  .Sx Native Properties
2162 2163  and
2163 2164  .Sx User Properties
2164 2165  sections.
2165 2166  .Pp
2166 2167  The special value
2167 2168  .Sy all
2168 2169  can be used to display all properties that apply to the given dataset's type
2169 2170  .Pq filesystem, volume, snapshot, or bookmark .
2170 2171  .Bl -tag -width "-H"
2171 2172  .It Fl H
2172 2173  Display output in a form more easily parsed by scripts. Any headers are omitted,
2173 2174  and fields are explicitly separated by a single tab instead of an arbitrary
2174 2175  amount of space.
2175 2176  .It Fl d Ar depth
2176 2177  Recursively display any children of the dataset, limiting the recursion to
2177 2178  .Ar depth .
2178 2179  A depth of
2179 2180  .Sy 1
2180 2181  will display only the dataset and its direct children.
2181 2182  .It Fl o Ar field
2182 2183  A comma-separated list of columns to display.
2183 2184  .Sy name Ns , Ns Sy property Ns , Ns Sy value Ns , Ns Sy source
2184 2185  is the default value.
2185 2186  .It Fl p
2186 2187  Display numbers in parsable
2187 2188  .Pq exact
2188 2189  values.
2189 2190  .It Fl r
2190 2191  Recursively display properties for any children.
2191 2192  .It Fl s Ar source
2192 2193  A comma-separated list of sources to display. Those properties coming from a
2193 2194  source other than those in this list are ignored. Each source must be one of the
2194 2195  following:
2195 2196  .Sy local ,
2196 2197  .Sy default ,
2197 2198  .Sy inherited ,
2198 2199  .Sy temporary ,
2199 2200  and
2200 2201  .Sy none .
2201 2202  The default value is all sources.
2202 2203  .It Fl t Ar type
2203 2204  A comma-separated list of types to display, where
2204 2205  .Ar type
2205 2206  is one of
2206 2207  .Sy filesystem ,
2207 2208  .Sy snapshot ,
2208 2209  .Sy volume ,
2209 2210  .Sy bookmark ,
2210 2211  or
2211 2212  .Sy all .
2212 2213  .El
2213 2214  .It Xo
2214 2215  .Nm
2215 2216  .Cm inherit
2216 2217  .Op Fl rS
2217 2218  .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2218 2219  .Xc
2219 2220  Clears the specified property, causing it to be inherited from an ancestor,
2220 2221  restored to default if no ancestor has the property set, or with the
2221 2222  .Fl S
2222 2223  option reverted to the received value if one exists. See the
2223 2224  .Sx Properties
2224 2225  section for a listing of default values, and details on which properties can be
2225 2226  inherited.
2226 2227  .Bl -tag -width "-r"
2227 2228  .It Fl r
2228 2229  Recursively inherit the given property for all children.
2229 2230  .It Fl S
2230 2231  Revert the property to the received value if one exists; otherwise operate as
2231 2232  if the
2232 2233  .Fl S
2233 2234  option was not specified.
2234 2235  .El
2235 2236  .It Xo
2236 2237  .Nm
2237 2238  .Cm upgrade
2238 2239  .Xc
2239 2240  Displays a list of file systems that are not the most recent version.
2240 2241  .It Xo
2241 2242  .Nm
2242 2243  .Cm upgrade
2243 2244  .Fl v
2244 2245  .Xc
2245 2246  Displays a list of currently supported file system versions.
2246 2247  .It Xo
2247 2248  .Nm
2248 2249  .Cm upgrade
2249 2250  .Op Fl r
2250 2251  .Op Fl V Ar version
2251 2252  .Fl a | Ar filesystem
2252 2253  .Xc
2253 2254  Upgrades file systems to a new on-disk version. Once this is done, the file
2254 2255  systems will no longer be accessible on systems running older versions of the
2255 2256  software.
2256 2257  .Nm zfs Cm send
2257 2258  streams generated from new snapshots of these file systems cannot be accessed on
2258 2259  systems running older versions of the software.
2259 2260  .Pp
2260 2261  In general, the file system version is independent of the pool version. See
2261 2262  .Xr zpool 1M
2262 2263  for information on the
2263 2264  .Nm zpool Cm upgrade
2264 2265  command.
2265 2266  .Pp
2266 2267  In some cases, the file system version and the pool version are interrelated and
2267 2268  the pool version must be upgraded before the file system version can be upgraded.
2268 2269  .Bl -tag -width "-V"
2269 2270  .It Fl V Ar version
2270 2271  Upgrade to the specified
2271 2272  .Ar version .
2272 2273  If the
2273 2274  .Fl V
2274 2275  flag is not specified, this command upgrades to the most recent version. This
2275 2276  option can only be used to increase the version number, and only up to the most
2276 2277  recent version supported by this software.
2277 2278  .It Fl a
2278 2279  Upgrade all file systems on all imported pools.
2279 2280  .It Ar filesystem
2280 2281  Upgrade the specified file system.
2281 2282  .It Fl r
2282 2283  Upgrade the specified file system and all descendent file systems.
2283 2284  .El
2284 2285  .It Xo
2285 2286  .Nm
2286 2287  .Cm userspace
2287 2288  .Op Fl Hinp
2288 2289  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2289 2290  .Oo Fl s Ar field Oc Ns ...
2290 2291  .Oo Fl S Ar field Oc Ns ...
2291 2292  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2292 2293  .Ar filesystem Ns | Ns Ar snapshot
2293 2294  .Xc
2294 2295  Displays space consumed by, and quotas on, each user in the specified filesystem
2295 2296  or snapshot. This corresponds to the
2296 2297  .Sy userused@ Ns Em user
2297 2298  and
2298 2299  .Sy userquota@ Ns Em user
2299 2300  properties.
2300 2301  .Bl -tag -width "-H"
2301 2302  .It Fl H
2302 2303  Do not print headers, use tab-delimited output.
2303 2304  .It Fl S Ar field
2304 2305  Sort by this field in reverse order. See
2305 2306  .Fl s .
2306 2307  .It Fl i
2307 2308  Translate SID to POSIX ID. The POSIX ID may be ephemeral if no mapping exists.
2308 2309  Normal POSIX interfaces
2309 2310  .Po for example,
2310 2311  .Xr stat 2 ,
2311 2312  .Nm ls Fl l
2312 2313  .Pc
2313 2314  perform this translation, so the
2314 2315  .Fl i
2315 2316  option allows the output from
2316 2317  .Nm zfs Cm userspace
2317 2318  to be compared directly with those utilities. However,
2318 2319  .Fl i
2319 2320  may lead to confusion if some files were created by an SMB user before a
2320 2321  SMB-to-POSIX name mapping was established. In such a case, some files will be
2321 2322  owned by the SMB entity and some by the POSIX entity. However, the
2322 2323  .Fl i
2323 2324  option will report that the POSIX entity has the total usage and quota for both.
2324 2325  .It Fl n
2325 2326  Print numeric ID instead of user/group name.
2326 2327  .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2327 2328  Display only the specified fields from the following set:
2328 2329  .Sy type ,
2329 2330  .Sy name ,
2330 2331  .Sy used ,
2331 2332  .Sy quota .
2332 2333  The default is to display all fields.
2333 2334  .It Fl p
2334 2335  Use exact
2335 2336  .Pq parsable
2336 2337  numeric output.
2337 2338  .It Fl s Ar field
2338 2339  Sort output by this field. The
2339 2340  .Fl s
2340 2341  and
2341 2342  .Fl S
2342 2343  flags may be specified multiple times to sort first by one field, then by
2343 2344  another. The default is
2344 2345  .Fl s Sy type Fl s Sy name .
2345 2346  .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2346 2347  Print only the specified types from the following set:
2347 2348  .Sy all ,
2348 2349  .Sy posixuser ,
2349 2350  .Sy smbuser ,
2350 2351  .Sy posixgroup ,
2351 2352  .Sy smbgroup .
2352 2353  The default is
2353 2354  .Fl t Sy posixuser Ns , Ns Sy smbuser .
2354 2355  The default can be changed to include group types.
2355 2356  .El
2356 2357  .It Xo
2357 2358  .Nm
2358 2359  .Cm groupspace
2359 2360  .Op Fl Hinp
2360 2361  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2361 2362  .Oo Fl s Ar field Oc Ns ...
2362 2363  .Oo Fl S Ar field Oc Ns ...
2363 2364  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2364 2365  .Ar filesystem Ns | Ns Ar snapshot
2365 2366  .Xc
2366 2367  Displays space consumed by, and quotas on, each group in the specified
2367 2368  filesystem or snapshot. This subcommand is identical to
2368 2369  .Nm zfs Cm userspace ,
2369 2370  except that the default types to display are
2370 2371  .Fl t Sy posixgroup Ns , Ns Sy smbgroup .
2371 2372  .It Xo
2372 2373  .Nm
2373 2374  .Cm mount
2374 2375  .Xc
2375 2376  Displays all ZFS file systems currently mounted.
2376 2377  .It Xo
2377 2378  .Nm
2378 2379  .Cm mount
2379 2380  .Op Fl Ov
2380 2381  .Op Fl o Ar options
2381 2382  .Fl a | Ar filesystem
2382 2383  .Xc
2383 2384  Mounts ZFS file systems.
2384 2385  .Bl -tag -width "-O"
2385 2386  .It Fl O
2386 2387  Perform an overlay mount. See
2387 2388  .Xr mount 1M
2388 2389  for more information.
2389 2390  .It Fl a
2390 2391  Mount all available ZFS file systems. Invoked automatically as part of the boot
2391 2392  process.
2392 2393  .It Ar filesystem
2393 2394  Mount the specified filesystem.
2394 2395  .It Fl o Ar options
2395 2396  An optional, comma-separated list of mount options to use temporarily for the
2396 2397  duration of the mount. See the
2397 2398  .Sx Temporary Mount Point Properties
2398 2399  section for details.
2399 2400  .It Fl v
2400 2401  Report mount progress.
2401 2402  .El
2402 2403  .It Xo
2403 2404  .Nm
2404 2405  .Cm unmount
2405 2406  .Op Fl f
2406 2407  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2407 2408  .Xc
2408 2409  Unmounts currently mounted ZFS file systems.
2409 2410  .Bl -tag -width "-a"
2410 2411  .It Fl a
2411 2412  Unmount all available ZFS file systems. Invoked automatically as part of the
2412 2413  shutdown process.
2413 2414  .It Ar filesystem Ns | Ns Ar mountpoint
2414 2415  Unmount the specified filesystem. The command can also be given a path to a ZFS
2415 2416  file system mount point on the system.
2416 2417  .It Fl f
2417 2418  Forcefully unmount the file system, even if it is currently in use.
2418 2419  .El
2419 2420  .It Xo
2420 2421  .Nm
2421 2422  .Cm share
2422 2423  .Fl a | Ar filesystem
2423 2424  .Xc
2424 2425  Shares available ZFS file systems.
2425 2426  .Bl -tag -width "-a"
2426 2427  .It Fl a
2427 2428  Share all available ZFS file systems. Invoked automatically as part of the boot
2428 2429  process.
2429 2430  .It Ar filesystem
2430 2431  Share the specified filesystem according to the
2431 2432  .Sy sharenfs
2432 2433  and
2433 2434  .Sy sharesmb
2434 2435  properties. File systems are shared when the
2435 2436  .Sy sharenfs
2436 2437  or
2437 2438  .Sy sharesmb
2438 2439  property is set.
2439 2440  .El
2440 2441  .It Xo
2441 2442  .Nm
2442 2443  .Cm unshare
2443 2444  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2444 2445  .Xc
2445 2446  Unshares currently shared ZFS file systems.
2446 2447  .Bl -tag -width "-a"
2447 2448  .It Fl a
2448 2449  Unshare all available ZFS file systems. Invoked automatically as part of the
2449 2450  shutdown process.
2450 2451  .It Ar filesystem Ns | Ns Ar mountpoint
2451 2452  Unshare the specified filesystem. The command can also be given a path to a ZFS
2452 2453  file system shared on the system.
2453 2454  .El
2454 2455  .It Xo
2455 2456  .Nm
2456 2457  .Cm bookmark
2457 2458  .Ar snapshot bookmark
2458 2459  .Xc
2459 2460  Creates a bookmark of the given snapshot. Bookmarks mark the point in time when
2460 2461  the snapshot was created, and can be used as the incremental source for a
2461 2462  .Nm zfs Cm send

2462 2463  command.
2463 2464  .Pp
2464 2465  This feature must be enabled to be used. See
2465 2466  .Xr zpool-features 5
2466 2467  for details on ZFS feature flags and the
2467 2468  .Sy bookmarks
2468 2469  feature.
2469 2470  .It Xo
2470 2471  .Nm
2471 2472  .Cm send
2472      -.Op Fl DLPRenpv
     2473 +.Op Fl DFLPRenpv
2473 2474  .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
2474 2475  .Ar snapshot
2475 2476  .Xc
2476 2477  Creates a stream representation of the second
2477 2478  .Ar snapshot ,
2478 2479  which is written to standard output. The output can be redirected to a file or
2479 2480  to a different system
2480 2481  .Po for example, using
2481 2482  .Xr ssh 1
2482 2483  .Pc .

2483 2484  By default, a full stream is generated.
2484 2485  .Bl -tag -width "-D"
2485 2486  .It Fl D
2486 2487  Generate a deduplicated stream. Blocks which would have been sent multiple times
2487 2488  in the send stream will only be sent once. The receiving system must also
2488 2489  support this feature to recieve a deduplicated stream. This flag can be used
2489 2490  regardless of the dataset's
2490 2491  .Sy dedup
2491 2492  property, but performance will be much better if the filesystem uses a
2492 2493  dedup-capable checksum
2493 2494  .Po for example,
2494 2495  .Sy sha256
2495 2496  .Pc .
2496 2497  .It Fl I Ar snapshot
2497 2498  Generate a stream package that sends all intermediary snapshots from the first
2498 2499  snapshot to the second snapshot. For example,
2499 2500  .Fl I Em @a Em fs@d
2500 2501  is similar to
2501 2502  .Fl i Em @a Em fs@b Ns ; Fl i Em @b Em fs@c Ns ; Fl i Em @c Em fs@d .
2502 2503  The incremental source may be specified as with the
2503 2504  .Fl i
2504 2505  option.
2505 2506  .It Fl L
2506 2507  Generate a stream which may contain blocks larger than 128KB. This flag has no
2507 2508  effect if the
2508 2509  .Sy large_blocks
2509 2510  pool feature is disabled, or if the
2510 2511  .Sy recordsize
2511 2512  property of this filesystem has never been set above 128KB. The receiving system
2512 2513  must have the
2513 2514  .Sy large_blocks
2514 2515  pool feature enabled as well. See
2515 2516  .Xr zpool-features 5
2516 2517  for details on ZFS feature flags and the
2517 2518  .Sy large_blocks
2518 2519  feature.
2519 2520  .It Fl P
2520 2521  Print machine-parsable verbose information about the stream package generated.
2521 2522  .It Fl R
2522 2523  Generate a replication stream package, which will replicate the specified
2523 2524  file system, and all descendent file systems, up to the named snapshot. When
2524 2525  received, all properties, snapshots, descendent file systems, and clones are
2525 2526  preserved.
2526 2527  .Pp
2527 2528  If the
2528 2529  .Fl i
2529 2530  or
2530 2531  .Fl I
2531 2532  flags are used in conjunction with the
2532 2533  .Fl R
2533 2534  flag, an incremental replication stream is generated. The current values of
2534 2535  properties, and current snapshot and file system names are set when the stream
2535 2536  is received. If the
2536 2537  .Fl F
2537 2538  flag is specified when this stream is received, snapshots and file systems that
2538 2539  do not exist on the sending side are destroyed.
2539 2540  .It Fl e
2540 2541  Generate a more compact stream by using
2541 2542  .Sy WRITE_EMBEDDED
2542 2543  records for blocks which are stored more compactly on disk by the
2543 2544  .Sy embedded_data
2544 2545  pool feature. This flag has no effect if the
2545 2546  .Sy embedded_data

2546 2547  feature is disabled. The receiving system must have the
2547 2548  .Sy embedded_data
2548 2549  feature enabled. If the
2549 2550  .Sy lz4_compress
2550 2551  feature is active on the sending system, then the receiving system must have
2551 2552  that feature enabled as well. See
2552 2553  .Xr zpool-features 5
2553 2554  for details on ZFS feature flags and the
2554 2555  .Sy embedded_data
2555 2556  feature.
     2557 +.It Fl F
     2558 +Generate a stream which omits free records.  The stream will be more compact
     2559 +but the receiving system will not be able to receive the stream as a clone.
2556 2560  .It Fl i Ar snapshot
2557 2561  Generate an incremental stream from the first
2558 2562  .Ar snapshot
2559 2563  .Pq the incremental source
2560 2564  to the second
2561 2565  .Ar snapshot
2562 2566  .Pq the incremental target .
2563 2567  The incremental source can be specified as the last component of the snapshot
2564 2568  name
2565 2569  .Po the

2566 2570  .Sy @
2567 2571  character and following
2568 2572  .Pc
2569 2573  and it is assumed to be from the same file system as the incremental target.
2570 2574  .Pp
2571 2575  If the destination is a clone, the source may be the origin snapshot, which must
2572 2576  be fully specified
2573 2577  .Po for example,
2574 2578  .Em pool/fs@origin ,
2575 2579  not just
2576 2580  .Em @origin
2577 2581  .Pc .
2578 2582  .It Fl n
2579 2583  Do a dry-run
2580 2584  .Pq Qq No-op
2581 2585  send. Do not generate any actual send data. This is useful in conjunction with
2582 2586  the
2583 2587  .Fl v
2584 2588  or
2585 2589  .Fl P
2586 2590  flags to determine what data will be sent. In this case, the verbose output will
2587 2591  be written to standard output
2588 2592  .Po contrast with a non-dry-run, where the stream is written to standard output
2589 2593  and the verbose output goes to standard error
2590 2594  .Pc .
2591 2595  .It Fl p
2592 2596  Include the dataset's properties in the stream. This flag is implicit when
2593 2597  .Fl R
2594 2598  is specified. The receiving system must also support this feature.

2595 2599  .It Fl v
2596 2600  Print verbose information about the stream package generated. This information
2597 2601  includes a per-second report of how much data has been sent.
2598 2602  .Pp
2599 2603  The format of the stream is committed. You will be able to receive your streams
2600 2604  on future versions of ZFS .
2601 2605  .El
2602 2606  .It Xo
2603 2607  .Nm
2604 2608  .Cm send
2605      -.Op Fl Le
     2609 +.Op Fl FLe
2606 2610  .Op Fl i Ar snapshot Ns | Ns Ar bookmark
2607 2611  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2608 2612  .Xc
2609 2613  Generate a send stream, which may be of a filesystem, and may be incremental
2610 2614  from a bookmark. If the destination is a filesystem or volume, the pool must be
2611 2615  read-only, or the filesystem must not be mounted. When the stream generated from
2612 2616  a filesystem or volume is received, the default snapshot name will be
2613 2617  .Qq --head-- .
2614 2618  .Bl -tag -width "-L"
2615 2619  .It Fl L

2616 2620  Generate a stream which may contain blocks larger than 128KB. This flag has no
2617 2621  effect if the
2618 2622  .Sy large_blocks
2619 2623  pool feature is disabled, or if the
2620 2624  .Sy recordsize
2621 2625  property of this filesystem has never been set above 128KB. The receiving system
2622 2626  must have the
2623 2627  .Sy large_blocks
2624 2628  pool feature enabled as well. See
2625 2629  .Xr zpool-features 5
2626 2630  for details on ZFS feature flags and the
2627 2631  .Sy large_blocks
2628 2632  feature.
2629 2633  .It Fl e
2630 2634  Generate a more compact stream by using
2631 2635  .Sy WRITE_EMBEDDED
2632 2636  records for blocks which are stored more compactly on disk by the
2633 2637  .Sy embedded_data
2634 2638  pool feature. This flag has no effect if the
2635 2639  .Sy embedded_data

2636 2640  feature is disabled. The receiving system must have the
2637 2641  .Sy embedded_data
2638 2642  feature enabled. If the
2639 2643  .Sy lz4_compress
2640 2644  feature is active on the sending system, then the receiving system must have
2641 2645  that feature enabled as well. See
2642 2646  .Xr zpool-features 5
2643 2647  for details on ZFS feature flags and the
2644 2648  .Sy embedded_data
2645 2649  feature.
     2650 +.It Fl F
     2651 +Generate a stream which omits free records.  The stream will be more compact
     2652 +but the receiving system will not be able to receive the stream as a clone.
2646 2653  .It Fl i Ar snapshot Ns | Ns Ar bookmark
2647 2654  Generate an incremental send stream. The incremental source must be an earlier
2648 2655  snapshot in the destination's history. It will commonly be an earlier snapshot
2649 2656  in the destination's file system, in which case it can be specified as the last
2650 2657  component of the name
2651 2658  .Po the
2652 2659  .Sy #
2653 2660  or
2654 2661  .Sy @
2655 2662  character and following

2656 2663  .Pc .
2657 2664  .Pp
2658 2665  If the incremental target is a clone, the incremental source can be the origin
2659 2666  snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
2660 2667  origin, etc.
2661 2668  .El
2662 2669  .It Xo
2663 2670  .Nm
2664 2671  .Cm send
2665 2672  .Op Fl Penv
2666 2673  .Fl t
2667 2674  .Ar receive_resume_token
2668 2675  .Xc
2669 2676  Creates a send stream which resumes an interrupted receive.  The
2670 2677  .Ar receive_resume_token
2671 2678  is the value of this property on the filesystem
2672 2679  or volume that was being received into.  See the documentation for
2673 2680  .Sy zfs receive -s
2674 2681  for more details.
2675 2682  .It Xo
2676 2683  .Nm
2677 2684  .Cm receive
2678 2685  .Op Fl Fnsuv
2679 2686  .Op Fl o Sy origin Ns = Ns Ar snapshot
2680 2687  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2681 2688  .br
2682 2689  .Nm
2683 2690  .Cm receive
2684 2691  .Op Fl Fnsuv
2685 2692  .Op Fl d Ns | Ns Fl e
2686 2693  .Op Fl o Sy origin Ns = Ns Ar snapshot
2687 2694  .Ar filesystem
2688 2695  .Xc
2689 2696  Creates a snapshot whose contents are as specified in the stream provided on
2690 2697  standard input. If a full stream is received, then a new file system is created
2691 2698  as well. Streams are created using the
2692 2699  .Nm zfs Cm send
2693 2700  subcommand, which by default creates a full stream.
2694 2701  .Nm zfs Cm recv
2695 2702  can be used as an alias for
2696 2703  .Nm zfs Cm receive.
2697 2704  .Pp
2698 2705  If an incremental stream is received, then the destination file system must
2699 2706  already exist, and its most recent snapshot must match the incremental stream's
2700 2707  source. For
2701 2708  .Sy zvols ,
2702 2709  the destination device link is destroyed and recreated, which means the
2703 2710  .Sy zvol
2704 2711  cannot be accessed during the
2705 2712  .Cm receive
2706 2713  operation.
2707 2714  .Pp
2708 2715  When a snapshot replication package stream that is generated by using the
2709 2716  .Nm zfs Cm send Fl R
2710 2717  command is received, any snapshots that do not exist on the sending location are
2711 2718  destroyed by using the
2712 2719  .Nm zfs Cm destroy Fl d
2713 2720  command.
2714 2721  .Pp
2715 2722  The name of the snapshot
2716 2723  .Pq and file system, if a full stream is received
2717 2724  that this subcommand creates depends on the argument type and the use of the
2718 2725  .Fl d
2719 2726  or
2720 2727  .Fl e
2721 2728  options.
2722 2729  .Pp
2723 2730  If the argument is a snapshot name, the specified
2724 2731  .Ar snapshot
2725 2732  is created. If the argument is a file system or volume name, a snapshot with the
2726 2733  same name as the sent snapshot is created within the specified
2727 2734  .Ar filesystem
2728 2735  or
2729 2736  .Ar volume .
2730 2737  If neither of the
2731 2738  .Fl d
2732 2739  or
2733 2740  .Fl e
2734 2741  options are specified, the provided target snapshot name is used exactly as
2735 2742  provided.
2736 2743  .Pp
2737 2744  The
2738 2745  .Fl d
2739 2746  and
2740 2747  .Fl e
2741 2748  options cause the file system name of the target snapshot to be determined by
2742 2749  appending a portion of the sent snapshot's name to the specified target
2743 2750  .Ar filesystem .
2744 2751  If the
2745 2752  .Fl d
2746 2753  option is specified, all but the first element of the sent snapshot's file
2747 2754  system path
2748 2755  .Pq usually the pool name
2749 2756  is used and any required intermediate file systems within the specified one are
2750 2757  created. If the
2751 2758  .Fl e
2752 2759  option is specified, then only the last element of the sent snapshot's file
2753 2760  system name
2754 2761  .Pq i.e. the name of the source file system itself
2755 2762  is used as the target file system name.
2756 2763  .Bl -tag -width "-F"
2757 2764  .It Fl F
2758 2765  Force a rollback of the file system to the most recent snapshot before
2759 2766  performing the receive operation. If receiving an incremental replication stream
2760 2767  .Po for example, one generated by
2761 2768  .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
2762 2769  .Pc ,
2763 2770  destroy snapshots and file systems that do not exist on the sending side.
2764 2771  .It Fl d
2765 2772  Discard the first element of the sent snapshot's file system name, using the
2766 2773  remaining elements to determine the name of the target file system for the new
2767 2774  snapshot as described in the paragraph above.
2768 2775  .It Fl e
2769 2776  Discard all but the last element of the sent snapshot's file system name, using
2770 2777  that element to determine the name of the target file system for the new
2771 2778  snapshot as described in the paragraph above.
2772 2779  .It Fl n
2773 2780  Do not actually receive the stream. This can be useful in conjunction with the
2774 2781  .Fl v
2775 2782  option to verify the name the receive operation would use.
2776 2783  .It Fl o Sy origin Ns = Ns Ar snapshot
2777 2784  Forces the stream to be received as a clone of the given snapshot.
2778 2785  If the stream is a full send stream, this will create the filesystem
2779 2786  described by the stream as a clone of the specified snapshot. Which
2780 2787  snapshot was specified will not affect the success or failure of the
2781 2788  receive, as long as the snapshot does exist.  If the stream is an
2782 2789  incremental send stream, all the normal verification will be performed.
2783 2790  .It Fl u
2784 2791  File system that is associated with the received stream is not mounted.
2785 2792  .It Fl v
2786 2793  Print verbose information about the stream and the time required to perform the
2787 2794  receive operation.
2788 2795  .It Fl s
2789 2796  If the receive is interrupted, save the partially received state, rather
2790 2797  than deleting it.  Interruption may be due to premature termination of
2791 2798  the stream
2792 2799  .Po e.g. due to network failure or failure of the remote system
2793 2800  if the stream is being read over a network connection
2794 2801  .Pc ,
2795 2802  a checksum error in the stream, termination of the
2796 2803  .Nm zfs Cm receive
2797 2804  process, or unclean shutdown of the system.
2798 2805  .Pp
2799 2806  The receive can be resumed with a stream generated by
2800 2807  .Nm zfs Cm send Fl t Ar token ,
2801 2808  where the
2802 2809  .Ar token
2803 2810  is the value of the
2804 2811  .Sy receive_resume_token
2805 2812  property of the filesystem or volume which is received into.
2806 2813  .Pp
2807 2814  To use this flag, the storage pool must have the
2808 2815  .Sy extensible_dataset
2809 2816  feature enabled.  See
2810 2817  .Xr zpool-features 5
2811 2818  for details on ZFS feature flags.
2812 2819  .El
2813 2820  .It Xo
2814 2821  .Nm
2815 2822  .Cm receive
2816 2823  .Fl A
2817 2824  .Ar filesystem Ns | Ns Ar volume
2818 2825  .Xc
2819 2826  Abort an interrupted
2820 2827  .Nm zfs Cm receive Fl s ,
2821 2828  deleting its saved partially received state.
2822 2829  .It Xo
2823 2830  .Nm
2824 2831  .Cm allow
2825 2832  .Ar filesystem Ns | Ns Ar volume
2826 2833  .Xc
2827 2834  Displays permissions that have been delegated on the specified filesystem or
2828 2835  volume. See the other forms of
2829 2836  .Nm zfs Cm allow
2830 2837  for more information.
2831 2838  .It Xo
2832 2839  .Nm
2833 2840  .Cm allow
2834 2841  .Op Fl dglu
2835 2842  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
2836 2843  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2837 2844  .Ar setname Oc Ns ...
2838 2845  .Ar filesystem Ns | Ns Ar volume
2839 2846  .br
2840 2847  .Nm
2841 2848  .Cm allow
2842 2849  .Op Fl dl
2843 2850  .Fl e Ns | Ns Sy everyone
2844 2851  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2845 2852  .Ar setname Oc Ns ...
2846 2853  .Ar filesystem Ns | Ns Ar volume
2847 2854  .Xc
2848 2855  Delegates ZFS administration permission for the file systems to non-privileged
2849 2856  users.
2850 2857  .Bl -tag -width "-d"
2851 2858  .It Fl d
2852 2859  Allow only for the descendent file systems.
2853 2860  .It Fl e Ns | Ns Sy everyone
2854 2861  Specifies that the permissions be delegated to everyone.
2855 2862  .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
2856 2863  Explicitly specify that permissions are delegated to the group.
2857 2864  .It Fl l
2858 2865  Allow
2859 2866  .Qq locally
2860 2867  only for the specified file system.
2861 2868  .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
2862 2869  Explicitly specify that permissions are delegated to the user.
2863 2870  .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
2864 2871  Specifies to whom the permissions are delegated. Multiple entities can be
2865 2872  specified as a comma-separated list. If neither of the
2866 2873  .Fl gu
2867 2874  options are specified, then the argument is interpreted preferentially as the
2868 2875  keyword
2869 2876  .Sy everyone ,
2870 2877  then as a user name, and lastly as a group name. To specify a user or group
2871 2878  named
2872 2879  .Qq everyone ,
2873 2880  use the
2874 2881  .Fl g
2875 2882  or
2876 2883  .Fl u
2877 2884  options. To specify a group with the same name as a user, use the
2878 2885  .Fl g
2879 2886  options.
2880 2887  .It Xo
2881 2888  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2882 2889  .Ar setname Oc Ns ...
2883 2890  .Xc
2884 2891  The permissions to delegate. Multiple permissions may be specified as a
2885 2892  comma-separated list. Permission names are the same as ZFS subcommand and
2886 2893  property names. See the property list below. Property set names,
2887 2894  which begin with
2888 2895  .Sy @ ,
2889 2896  may be specified. See the
2890 2897  .Fl s
2891 2898  form below for details.
2892 2899  .El
2893 2900  .Pp
2894 2901  If neither of the
2895 2902  .Fl dl
2896 2903  options are specified, or both are, then the permissions are allowed for the
2897 2904  file system or volume, and all of its descendents.
2898 2905  .Pp
2899 2906  Permissions are generally the ability to use a ZFS subcommand or change a ZFS
2900 2907  property. The following permissions are available:
2901 2908  .Bd -literal
2902 2909  NAME             TYPE           NOTES
2903 2910  allow            subcommand     Must also have the permission that is being
2904 2911                                  allowed
2905 2912  clone            subcommand     Must also have the 'create' ability and 'mount'
2906 2913                                  ability in the origin file system
2907 2914  create           subcommand     Must also have the 'mount' ability
2908 2915  destroy          subcommand     Must also have the 'mount' ability
2909 2916  diff             subcommand     Allows lookup of paths within a dataset
2910 2917                                  given an object number, and the ability to
2911 2918                                  create snapshots necessary to 'zfs diff'.
2912 2919  mount            subcommand     Allows mount/umount of ZFS datasets
2913 2920  promote          subcommand     Must also have the 'mount'
2914 2921                                  and 'promote' ability in the origin file system
2915 2922  receive          subcommand     Must also have the 'mount' and 'create' ability
2916 2923  rename           subcommand     Must also have the 'mount' and 'create'
2917 2924                                  ability in the new parent
2918 2925  rollback         subcommand     Must also have the 'mount' ability
2919 2926  send             subcommand
2920 2927  share            subcommand     Allows sharing file systems over NFS or SMB
2921 2928                                  protocols
2922 2929  snapshot         subcommand     Must also have the 'mount' ability
2923 2930  
2924 2931  groupquota       other          Allows accessing any groupquota@... property
2925 2932  groupused        other          Allows reading any groupused@... property
2926 2933  userprop         other          Allows changing any user property
2927 2934  userquota        other          Allows accessing any userquota@... property
2928 2935  userused         other          Allows reading any userused@... property
2929 2936  
2930 2937  aclinherit       property
2931 2938  aclmode          property
2932 2939  atime            property
2933 2940  canmount         property
2934 2941  casesensitivity  property
2935 2942  checksum         property
2936 2943  compression      property
2937 2944  copies           property
2938 2945  devices          property
2939 2946  exec             property
2940 2947  filesystem_limit property
2941 2948  mountpoint       property
2942 2949  nbmand           property
2943 2950  normalization    property
2944 2951  primarycache     property
2945 2952  quota            property
2946 2953  readonly         property
2947 2954  recordsize       property
2948 2955  refquota         property
2949 2956  refreservation   property
2950 2957  reservation      property
2951 2958  secondarycache   property
2952 2959  setuid           property
2953 2960  sharenfs         property
2954 2961  sharesmb         property
2955 2962  snapdir          property
2956 2963  snapshot_limit   property
2957 2964  utf8only         property
2958 2965  version          property
2959 2966  volblocksize     property
2960 2967  volsize          property
2961 2968  vscan            property
2962 2969  xattr            property
2963 2970  zoned            property
2964 2971  .Ed
2965 2972  .It Xo
2966 2973  .Nm
2967 2974  .Cm allow
2968 2975  .Fl c
2969 2976  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2970 2977  .Ar setname Oc Ns ...
2971 2978  .Ar filesystem Ns | Ns Ar volume
2972 2979  .Xc
2973 2980  Sets
2974 2981  .Qq create time
2975 2982  permissions. These permissions are granted
2976 2983  .Pq locally
2977 2984  to the creator of any newly-created descendent file system.
2978 2985  .It Xo
2979 2986  .Nm
2980 2987  .Cm allow
2981 2988  .Fl s No @ Ns Ar setname
2982 2989  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2983 2990  .Ar setname Oc Ns ...
2984 2991  .Ar filesystem Ns | Ns Ar volume
2985 2992  .Xc
2986 2993  Defines or adds permissions to a permission set. The set can be used by other
2987 2994  .Nm zfs Cm allow
2988 2995  commands for the specified file system and its descendents. Sets are evaluated
2989 2996  dynamically, so changes to a set are immediately reflected. Permission sets
2990 2997  follow the same naming restrictions as ZFS file systems, but the name must begin
2991 2998  with
2992 2999  .Sy @ ,
2993 3000  and can be no more than 64 characters long.
2994 3001  .It Xo
2995 3002  .Nm
2996 3003  .Cm unallow
2997 3004  .Op Fl dglru
2998 3005  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
2999 3006  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3000 3007  .Ar setname Oc Ns ... Oc
3001 3008  .Ar filesystem Ns | Ns Ar volume
3002 3009  .br
3003 3010  .Nm
3004 3011  .Cm unallow
3005 3012  .Op Fl dlr
3006 3013  .Fl e Ns | Ns Sy everyone
3007 3014  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3008 3015  .Ar setname Oc Ns ... Oc
3009 3016  .Ar filesystem Ns | Ns Ar volume
3010 3017  .br
3011 3018  .Nm
3012 3019  .Cm unallow
3013 3020  .Op Fl r
3014 3021  .Fl c
3015 3022  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3016 3023  .Ar setname Oc Ns ... Oc
3017 3024  .Ar filesystem Ns | Ns Ar volume
3018 3025  .Xc
3019 3026  Removes permissions that were granted with the
3020 3027  .Nm zfs Cm allow
3021 3028  command. No permissions are explicitly denied, so other permissions granted are
3022 3029  still in effect. For example, if the permission is granted by an ancestor. If no
3023 3030  permissions are specified, then all permissions for the specified
3024 3031  .Ar user ,
3025 3032  .Ar group ,
3026 3033  or
3027 3034  .Sy everyone
3028 3035  are removed. Specifying
3029 3036  .Sy everyone
3030 3037  .Po or using the
3031 3038  .Fl e
3032 3039  option
3033 3040  .Pc
3034 3041  only removes the permissions that were granted to everyone, not all permissions
3035 3042  for every user and group. See the
3036 3043  .Nm zfs Cm allow
3037 3044  command for a description of the
3038 3045  .Fl ldugec
3039 3046  options.
3040 3047  .Bl -tag -width "-r"
3041 3048  .It Fl r
3042 3049  Recursively remove the permissions from this file system and all descendents.
3043 3050  .El
3044 3051  .It Xo
3045 3052  .Nm
3046 3053  .Cm unallow
3047 3054  .Op Fl r
3048 3055  .Fl s @ Ns Ar setname
3049 3056  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3050 3057  .Ar setname Oc Ns ... Oc
3051 3058  .Ar filesystem Ns | Ns Ar volume
3052 3059  .Xc
3053 3060  Removes permissions from a permission set. If no permissions are specified, then
3054 3061  all permissions are removed, thus removing the set entirely.
3055 3062  .It Xo
3056 3063  .Nm
3057 3064  .Cm hold
3058 3065  .Op Fl r
3059 3066  .Ar tag Ar snapshot Ns ...
3060 3067  .Xc
3061 3068  Adds a single reference, named with the
3062 3069  .Ar tag
3063 3070  argument, to the specified snapshot or snapshots. Each snapshot has its own tag
3064 3071  namespace, and tags must be unique within that space.
3065 3072  .Pp
3066 3073  If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3067 3074  .Nm zfs Cm destroy
3068 3075  command return
3069 3076  .Er EBUSY .
3070 3077  .Bl -tag -width "-r"
3071 3078  .It Fl r
3072 3079  Specifies that a hold with the given tag is applied recursively to the snapshots
3073 3080  of all descendent file systems.
3074 3081  .El
3075 3082  .It Xo
3076 3083  .Nm
3077 3084  .Cm holds
3078 3085  .Op Fl r
3079 3086  .Ar snapshot Ns ...
3080 3087  .Xc
3081 3088  Lists all existing user references for the given snapshot or snapshots.
3082 3089  .Bl -tag -width "-r"
3083 3090  .It Fl r
3084 3091  Lists the holds that are set on the named descendent snapshots, in addition to
3085 3092  listing the holds on the named snapshot.
3086 3093  .El
3087 3094  .It Xo
3088 3095  .Nm
3089 3096  .Cm release
3090 3097  .Op Fl r
3091 3098  .Ar tag Ar snapshot Ns ...
3092 3099  .Xc
3093 3100  Removes a single reference, named with the
3094 3101  .Ar tag
3095 3102  argument, from the specified snapshot or snapshots. The tag must already exist
3096 3103  for each snapshot. If a hold exists on a snapshot, attempts to destroy that
3097 3104  snapshot by using the
3098 3105  .Nm zfs Cm destroy
3099 3106  command return
3100 3107  .Er EBUSY .
3101 3108  .Bl -tag -width "-r"
3102 3109  .It Fl r
3103 3110  Recursively releases a hold with the given tag on the snapshots of all
3104 3111  descendent file systems.
3105 3112  .El
3106 3113  .It Xo
3107 3114  .Nm
3108 3115  .Cm diff
3109 3116  .Op Fl FHt
3110 3117  .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3111 3118  .Xc
3112 3119  Display the difference between a snapshot of a given filesystem and another
3113 3120  snapshot of that filesystem from a later time or the current contents of the
3114 3121  filesystem. The first column is a character indicating the type of change, the
3115 3122  other columns indicate pathname, new pathname
3116 3123  .Pq in case of rename ,
3117 3124  change in link count, and optionally file type and/or change time. The types of
3118 3125  change are:
3119 3126  .Bd -literal
3120 3127  -       The path has been removed
3121 3128  +       The path has been created
3122 3129  M       The path has been modified
3123 3130  R       The path has been renamed
3124 3131  .Ed
3125 3132  .Bl -tag -width "-F"
3126 3133  .It Fl F
3127 3134  Display an indication of the type of file, in a manner similar to the
3128 3135  .Fl
3129 3136  option of
3130 3137  .Xr ls 1 .
3131 3138  .Bd -literal
3132 3139  B       Block device
3133 3140  C       Character device
3134 3141  /       Directory
3135 3142  >       Door
3136 3143  |       Named pipe
3137 3144  @       Symbolic link
3138 3145  P       Event port
3139 3146  =       Socket
3140 3147  F       Regular file
3141 3148  .Ed
3142 3149  .It Fl H
3143 3150  Give more parsable tab-separated output, without header lines and without
3144 3151  arrows.
3145 3152  .It Fl t
3146 3153  Display the path's inode change time as the first column of output.
3147 3154  .El
3148 3155  .El
3149 3156  .Sh EXIT STATUS
3150 3157  The
3151 3158  .Nm
3152 3159  utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
3153 3160  options were specified.
3154 3161  .Sh EXAMPLES
3155 3162  .Bl -tag -width ""
3156 3163  .It Sy Example 1 No Creating a ZFS File System Hierarchy
3157 3164  The following commands create a file system named
3158 3165  .Em pool/home
3159 3166  and a file system named
3160 3167  .Em pool/home/bob .
3161 3168  The mount point
3162 3169  .Pa /export/home
3163 3170  is set for the parent file system, and is automatically inherited by the child
3164 3171  file system.
3165 3172  .Bd -literal
3166 3173  # zfs create pool/home
3167 3174  # zfs set mountpoint=/export/home pool/home
3168 3175  # zfs create pool/home/bob
3169 3176  .Ed
3170 3177  .It Sy Example 2 No Creating a ZFS Snapshot
3171 3178  The following command creates a snapshot named
3172 3179  .Sy yesterday .
3173 3180  This snapshot is mounted on demand in the
3174 3181  .Pa .zfs/snapshot
3175 3182  directory at the root of the
3176 3183  .Em pool/home/bob
3177 3184  file system.
3178 3185  .Bd -literal
3179 3186  # zfs snapshot pool/home/bob@yesterday
3180 3187  .Ed
3181 3188  .It Sy Example 3 No Creating and Destroying Multiple Snapshots
3182 3189  The following command creates snapshots named
3183 3190  .Sy yesterday
3184 3191  of
3185 3192  .Em pool/home
3186 3193  and all of its descendent file systems. Each snapshot is mounted on demand in
3187 3194  the
3188 3195  .Pa .zfs/snapshot
3189 3196  directory at the root of its file system. The second command destroys the newly
3190 3197  created snapshots.
3191 3198  .Bd -literal
3192 3199  # zfs snapshot -r pool/home@yesterday
3193 3200  # zfs destroy -r pool/home@yesterday
3194 3201  .Ed
3195 3202  .It Sy Example 4 No Disabling and Enabling File System Compression
3196 3203  The following command disables the
3197 3204  .Sy compression
3198 3205  property for all file systems under
3199 3206  .Em pool/home .
3200 3207  The next command explicitly enables
3201 3208  .Sy compression
3202 3209  for
3203 3210  .Em pool/home/anne .
3204 3211  .Bd -literal
3205 3212  # zfs set compression=off pool/home
3206 3213  # zfs set compression=on pool/home/anne
3207 3214  .Ed
3208 3215  .It Sy Example 5 No Listing ZFS Datasets
3209 3216  The following command lists all active file systems and volumes in the system.
3210 3217  Snapshots are displayed if the
3211 3218  .Sy listsnaps
3212 3219  property is
3213 3220  .Sy on .
3214 3221  The default is
3215 3222  .Sy off .
3216 3223  See
3217 3224  .Xr zpool 1M
3218 3225  for more information on pool properties.
3219 3226  .Bd -literal
3220 3227  # zfs list
3221 3228  NAME                      USED  AVAIL  REFER  MOUNTPOINT
3222 3229  pool                      450K   457G    18K  /pool
3223 3230  pool/home                 315K   457G    21K  /export/home
3224 3231  pool/home/anne             18K   457G    18K  /export/home/anne
3225 3232  pool/home/bob             276K   457G   276K  /export/home/bob
3226 3233  .Ed
3227 3234  .It Sy Example 6 No Setting a Quota on a ZFS File System
3228 3235  The following command sets a quota of 50 Gbytes for
3229 3236  .Em pool/home/bob .
3230 3237  .Bd -literal
3231 3238  # zfs set quota=50G pool/home/bob
3232 3239  .Ed
3233 3240  .It Sy Example 7 No Listing ZFS Properties
3234 3241  The following command lists all properties for
3235 3242  .Em pool/home/bob .
3236 3243  .Bd -literal
3237 3244  # zfs get all pool/home/bob
3238 3245  NAME           PROPERTY              VALUE                  SOURCE
3239 3246  pool/home/bob  type                  filesystem             -
3240 3247  pool/home/bob  creation              Tue Jul 21 15:53 2009  -
3241 3248  pool/home/bob  used                  21K                    -
3242 3249  pool/home/bob  available             20.0G                  -
3243 3250  pool/home/bob  referenced            21K                    -
3244 3251  pool/home/bob  compressratio         1.00x                  -
3245 3252  pool/home/bob  mounted               yes                    -
3246 3253  pool/home/bob  quota                 20G                    local
3247 3254  pool/home/bob  reservation           none                   default
3248 3255  pool/home/bob  recordsize            128K                   default
3249 3256  pool/home/bob  mountpoint            /pool/home/bob         default
3250 3257  pool/home/bob  sharenfs              off                    default
3251 3258  pool/home/bob  checksum              on                     default
3252 3259  pool/home/bob  compression           on                     local
3253 3260  pool/home/bob  atime                 on                     default
3254 3261  pool/home/bob  devices               on                     default
3255 3262  pool/home/bob  exec                  on                     default
3256 3263  pool/home/bob  setuid                on                     default
3257 3264  pool/home/bob  readonly              off                    default
3258 3265  pool/home/bob  zoned                 off                    default
3259 3266  pool/home/bob  snapdir               hidden                 default
3260 3267  pool/home/bob  aclmode               discard                default
3261 3268  pool/home/bob  aclinherit            restricted             default
3262 3269  pool/home/bob  canmount              on                     default
3263 3270  pool/home/bob  xattr                 on                     default
3264 3271  pool/home/bob  copies                1                      default
3265 3272  pool/home/bob  version               4                      -
3266 3273  pool/home/bob  utf8only              off                    -
3267 3274  pool/home/bob  normalization         none                   -
3268 3275  pool/home/bob  casesensitivity       sensitive              -
3269 3276  pool/home/bob  vscan                 off                    default
3270 3277  pool/home/bob  nbmand                off                    default
3271 3278  pool/home/bob  sharesmb              off                    default
3272 3279  pool/home/bob  refquota              none                   default
3273 3280  pool/home/bob  refreservation        none                   default
3274 3281  pool/home/bob  primarycache          all                    default
3275 3282  pool/home/bob  secondarycache        all                    default
3276 3283  pool/home/bob  usedbysnapshots       0                      -
3277 3284  pool/home/bob  usedbydataset         21K                    -
3278 3285  pool/home/bob  usedbychildren        0                      -
3279 3286  pool/home/bob  usedbyrefreservation  0                      -
3280 3287  .Ed
3281 3288  .Pp
3282 3289  The following command gets a single property value.
3283 3290  .Bd -literal
3284 3291  # zfs get -H -o value compression pool/home/bob
3285 3292  on
3286 3293  .Ed
3287 3294  The following command lists all properties with local settings for
3288 3295  .Em pool/home/bob .
3289 3296  .Bd -literal
3290 3297  # zfs get -r -s local -o name,property,value all pool/home/bob
3291 3298  NAME           PROPERTY              VALUE
3292 3299  pool/home/bob  quota                 20G
3293 3300  pool/home/bob  compression           on
3294 3301  .Ed
3295 3302  .It Sy Example 8 No Rolling Back a ZFS File System
3296 3303  The following command reverts the contents of
3297 3304  .Em pool/home/anne
3298 3305  to the snapshot named
3299 3306  .Sy yesterday ,
3300 3307  deleting all intermediate snapshots.
3301 3308  .Bd -literal
3302 3309  # zfs rollback -r pool/home/anne@yesterday
3303 3310  .Ed
3304 3311  .It Sy Example 9 No Creating a ZFS Clone
3305 3312  The following command creates a writable file system whose initial contents are
3306 3313  the same as
3307 3314  .Em pool/home/bob@yesterday .
3308 3315  .Bd -literal
3309 3316  # zfs clone pool/home/bob@yesterday pool/clone
3310 3317  .Ed
3311 3318  .It Sy Example 10 No Promoting a ZFS Clone
3312 3319  The following commands illustrate how to test out changes to a file system, and
3313 3320  then replace the original file system with the changed one, using clones, clone
3314 3321  promotion, and renaming:
3315 3322  .Bd -literal
3316 3323  # zfs create pool/project/production
3317 3324    populate /pool/project/production with data
3318 3325  # zfs snapshot pool/project/production@today
3319 3326  # zfs clone pool/project/production@today pool/project/beta
3320 3327    make changes to /pool/project/beta and test them
3321 3328  # zfs promote pool/project/beta
3322 3329  # zfs rename pool/project/production pool/project/legacy
3323 3330  # zfs rename pool/project/beta pool/project/production
3324 3331    once the legacy version is no longer needed, it can be destroyed
3325 3332  # zfs destroy pool/project/legacy
3326 3333  .Ed
3327 3334  .It Sy Example 11 No Inheriting ZFS Properties
3328 3335  The following command causes
3329 3336  .Em pool/home/bob
3330 3337  and
3331 3338  .Em pool/home/anne
3332 3339  to inherit the
3333 3340  .Sy checksum
3334 3341  property from their parent.
3335 3342  .Bd -literal
3336 3343  # zfs inherit checksum pool/home/bob pool/home/anne
3337 3344  .Ed
3338 3345  .It Sy Example 12 No Remotely Replicating ZFS Data
3339 3346  The following commands send a full stream and then an incremental stream to a
3340 3347  remote machine, restoring them into
3341 3348  .Em poolB/received/fs@a
3342 3349  and
3343 3350  .Em poolB/received/fs@b ,
3344 3351  respectively.
3345 3352  .Em poolB
3346 3353  must contain the file system
3347 3354  .Em poolB/received ,
3348 3355  and must not initially contain
3349 3356  .Em poolB/received/fs .
3350 3357  .Bd -literal
3351 3358  # zfs send pool/fs@a | \e
3352 3359    ssh host zfs receive poolB/received/fs@a
3353 3360  # zfs send -i a pool/fs@b | \e
3354 3361    ssh host zfs receive poolB/received/fs
3355 3362  .Ed
3356 3363  .It Sy Example 13 No Using the zfs receive -d Option
3357 3364  The following command sends a full stream of
3358 3365  .Em poolA/fsA/fsB@snap
3359 3366  to a remote machine, receiving it into
3360 3367  .Em poolB/received/fsA/fsB@snap .
3361 3368  The
3362 3369  .Em fsA/fsB@snap
3363 3370  portion of the received snapshot's name is determined from the name of the sent
3364 3371  snapshot.
3365 3372  .Em poolB
3366 3373  must contain the file system
3367 3374  .Em poolB/received .
3368 3375  If
3369 3376  .Em poolB/received/fsA
3370 3377  does not exist, it is created as an empty file system.
3371 3378  .Bd -literal
3372 3379  # zfs send poolA/fsA/fsB@snap | \e
3373 3380    ssh host zfs receive -d poolB/received
3374 3381  .Ed
3375 3382  .It Sy Example 14 No Setting User Properties
3376 3383  The following example sets the user-defined
3377 3384  .Sy com.example:department
3378 3385  property for a dataset.
3379 3386  .Bd -literal
3380 3387  # zfs set com.example:department=12345 tank/accounting
3381 3388  .Ed
3382 3389  .It Sy Example 15 No Performing a Rolling Snapshot
3383 3390  The following example shows how to maintain a history of snapshots with a
3384 3391  consistent naming scheme. To keep a week's worth of snapshots, the user
3385 3392  destroys the oldest snapshot, renames the remaining snapshots, and then creates
3386 3393  a new snapshot, as follows:
3387 3394  .Bd -literal
3388 3395  # zfs destroy -r pool/users@7daysago
3389 3396  # zfs rename -r pool/users@6daysago @7daysago
3390 3397  # zfs rename -r pool/users@5daysago @6daysago
3391 3398  # zfs rename -r pool/users@yesterday @5daysago
3392 3399  # zfs rename -r pool/users@yesterday @4daysago
3393 3400  # zfs rename -r pool/users@yesterday @3daysago
3394 3401  # zfs rename -r pool/users@yesterday @2daysago
3395 3402  # zfs rename -r pool/users@today @yesterday
3396 3403  # zfs snapshot -r pool/users@today
3397 3404  .Ed
3398 3405  .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
3399 3406  The following commands show how to set
3400 3407  .Sy sharenfs
3401 3408  property options to enable
3402 3409  .Sy rw
3403 3410  access for a set of
3404 3411  .Sy IP
3405 3412  addresses and to enable root access for system
3406 3413  .Sy neo
3407 3414  on the
3408 3415  .Em tank/home
3409 3416  file system.
3410 3417  .Bd -literal
3411 3418  # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
3412 3419  .Ed
3413 3420  .Pp
3414 3421  If you are using
3415 3422  .Sy DNS
3416 3423  for host name resolution, specify the fully qualified hostname.
3417 3424  .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
3418 3425  The following example shows how to set permissions so that user
3419 3426  .Sy cindys
3420 3427  can create, destroy, mount, and take snapshots on
3421 3428  .Em tank/cindys .
3422 3429  The permissions on
3423 3430  .Em tank/cindys
3424 3431  are also displayed.
3425 3432  .Bd -literal
3426 3433  # zfs allow cindys create,destroy,mount,snapshot tank/cindys
3427 3434  # zfs allow tank/cindys
3428 3435  ---- Permissions on tank/cindys --------------------------------------
3429 3436  Local+Descendent permissions:
3430 3437          user cindys create,destroy,mount,snapshot
3431 3438  .Ed
3432 3439  .Pp
3433 3440  Because the
3434 3441  .Em tank/cindys
3435 3442  mount point permission is set to 755 by default, user
3436 3443  .Sy cindys
3437 3444  will be unable to mount file systems under
3438 3445  .Em tank/cindys .
3439 3446  Add an
3440 3447  .Sy ACE
3441 3448  similar to the following syntax to provide mount point access:
3442 3449  .Bd -literal
3443 3450  # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
3444 3451  .Ed
3445 3452  .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
3446 3453  The following example shows how to grant anyone in the group
3447 3454  .Sy staff
3448 3455  to create file systems in
3449 3456  .Em tank/users .
3450 3457  This syntax also allows staff members to destroy their own file systems, but not
3451 3458  destroy anyone else's file system. The permissions on
3452 3459  .Em tank/users
3453 3460  are also displayed.
3454 3461  .Bd -literal
3455 3462  # zfs allow staff create,mount tank/users
3456 3463  # zfs allow -c destroy tank/users
3457 3464  # zfs allow tank/users
3458 3465  ---- Permissions on tank/users ---------------------------------------
3459 3466  Permission sets:
3460 3467          destroy
3461 3468  Local+Descendent permissions:
3462 3469          group staff create,mount
3463 3470  .Ed
3464 3471  .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
3465 3472  The following example shows how to define and grant a permission set on the
3466 3473  .Em tank/users
3467 3474  file system. The permissions on
3468 3475  .Em tank/users
3469 3476  are also displayed.
3470 3477  .Bd -literal
3471 3478  # zfs allow -s @pset create,destroy,snapshot,mount tank/users
3472 3479  # zfs allow staff @pset tank/users
3473 3480  # zfs allow tank/users
3474 3481  ---- Permissions on tank/users ---------------------------------------
3475 3482  Permission sets:
3476 3483          @pset create,destroy,mount,snapshot
3477 3484  Local+Descendent permissions:
3478 3485          group staff @pset
3479 3486  .Ed
3480 3487  .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
3481 3488  The following example shows to grant the ability to set quotas and reservations
3482 3489  on the
3483 3490  .Em users/home
3484 3491  file system. The permissions on
3485 3492  .Em users/home
3486 3493  are also displayed.
3487 3494  .Bd -literal
3488 3495  # zfs allow cindys quota,reservation users/home
3489 3496  # zfs allow users/home
3490 3497  ---- Permissions on users/home ---------------------------------------
3491 3498  Local+Descendent permissions:
3492 3499          user cindys quota,reservation
3493 3500  cindys% zfs set quota=10G users/home/marks
3494 3501  cindys% zfs get quota users/home/marks
3495 3502  NAME              PROPERTY  VALUE  SOURCE
3496 3503  users/home/marks  quota     10G    local
3497 3504  .Ed
3498 3505  .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
3499 3506  The following example shows how to remove the snapshot permission from the
3500 3507  .Sy staff
3501 3508  group on the
3502 3509  .Em tank/users
3503 3510  file system. The permissions on
3504 3511  .Em tank/users
3505 3512  are also displayed.
3506 3513  .Bd -literal
3507 3514  # zfs unallow staff snapshot tank/users
3508 3515  # zfs allow tank/users
3509 3516  ---- Permissions on tank/users ---------------------------------------
3510 3517  Permission sets:
3511 3518          @pset create,destroy,mount,snapshot
3512 3519  Local+Descendent permissions:
3513 3520          group staff @pset
3514 3521  .Ed
3515 3522  .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
3516 3523  The following example shows how to see what has changed between a prior
3517 3524  snapshot of a ZFS dataset and its current state. The
3518 3525  .Fl F
3519 3526  option is used to indicate type information for the files affected.
3520 3527  .Bd -literal
3521 3528  # zfs diff -F tank/test@before tank/test
3522 3529  M       /       /tank/test/
3523 3530  M       F       /tank/test/linked      (+1)
3524 3531  R       F       /tank/test/oldname -> /tank/test/newname
3525 3532  -       F       /tank/test/deleted
3526 3533  +       F       /tank/test/created
3527 3534  M       F       /tank/test/modified
3528 3535  .Ed
3529 3536  .El
3530 3537  .Sh INTERFACE STABILITY
3531 3538  .Sy Commited .
3532 3539  .Sh SEE ALSO
3533 3540  .Xr gzip 1 ,
3534 3541  .Xr ssh 1 ,
3535 3542  .Xr mount 1M ,
3536 3543  .Xr share 1M ,
3537 3544  .Xr sharemgr 1M ,
3538 3545  .Xr unshare 1M ,
3539 3546  .Xr zonecfg 1M ,
3540 3547  .Xr zpool 1M ,
3541 3548  .Xr chmod 2 ,
3542 3549  .Xr stat 2 ,
3543 3550  .Xr write 2 ,
3544 3551  .Xr fsync 3C ,
3545 3552  .Xr dfstab 4 ,
3546 3553  .Xr acl 5 ,
3547 3554  .Xr attributes 5

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX