Add more details to the description of the fsid_guid dataset property
6333 ZFS should let the user specify or modify the fsid_guid of a dataset

          --- 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, 2014 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   29  .\"
  30   30  .Dd June 8, 2015
  31   31  .Dt ZFS 1M
  32   32  .Os
  33   33  .Sh NAME
  34   34  .Nm zfs
  35   35  .Nd configures ZFS file systems
  36   36  .Sh SYNOPSIS
  37   37  .Nm
  38   38  .Op Fl \?
  39   39  .Nm
  40   40  .Cm create
  41   41  .Op Fl p
  42   42  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  43   43  .Ar filesystem
  44   44  .Nm
  45   45  .Cm create
  46   46  .Op Fl ps
  47   47  .Op Fl b Ar blocksize
  48   48  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  49   49  .Fl V Ar size Ar volume
  50   50  .Nm
  51   51  .Cm destroy
  52   52  .Op Fl Rfnprv
  53   53  .Ar filesystem Ns | Ns Ar volume
  54   54  .Nm
  55   55  .Cm destroy
  56   56  .Op Fl Rdnprv
  57   57  .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
  58   58  .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
  59   59  .Nm
  60   60  .Cm destroy
  61   61  .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
  62   62  .Nm
  63   63  .Cm snapshot
  64   64  .Op Fl r
  65   65  .Oo Fl o Ar property Ns = Ns value Oc Ns ...
  66   66  .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
  67   67  .Nm
  68   68  .Cm rollback
  69   69  .Op Fl Rfr
  70   70  .Ar snapshot
  71   71  .Nm
  72   72  .Cm clone
  73   73  .Op Fl p
  74   74  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  75   75  .Ar snapshot Ar filesystem Ns | Ns Ar volume
  76   76  .Nm
  77   77  .Cm promote
  78   78  .Ar clone-filesystem
  79   79  .Nm
  80   80  .Cm rename
  81   81  .Op Fl f
  82   82  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  83   83  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  84   84  .Nm
  85   85  .Cm rename
  86   86  .Op Fl fp
  87   87  .Ar filesystem Ns | Ns Ar volume
  88   88  .Ar filesystem Ns | Ns Ar volume
  89   89  .Nm
  90   90  .Cm rename
  91   91  .Fl r
  92   92  .Ar snapshot Ar snapshot
  93   93  .Nm
  94   94  .Cm list
  95   95  .Op Fl r Ns | Ns Fl d Ar depth
  96   96  .Op Fl Hp
  97   97  .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
  98   98  .Oo Fl s Ar property Oc Ns ...
  99   99  .Oo Fl S Ar property Oc Ns ...
 100  100  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 101  101  .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
 102  102  .Nm
 103  103  .Cm set
 104  104  .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
 105  105  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 106  106  .Nm
 107  107  .Cm get
 108  108  .Op Fl r Ns | Ns Fl d Ar depth
 109  109  .Op Fl Hp
 110  110  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 111  111  .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
 112  112  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 113  113  .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
 114  114  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 115  115  .Nm
 116  116  .Cm inherit
 117  117  .Op Fl rS
 118  118  .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 119  119  .Nm
 120  120  .Cm upgrade
 121  121  .Nm
 122  122  .Cm upgrade
 123  123  .Fl v
 124  124  .Nm
 125  125  .Cm upgrade
 126  126  .Op Fl r
 127  127  .Op Fl V Ar version
 128  128  .Fl a | Ar filesystem
 129  129  .Nm
 130  130  .Cm userspace
 131  131  .Op Fl Hinp
 132  132  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 133  133  .Oo Fl s Ar field Oc Ns ...
 134  134  .Oo Fl S Ar field Oc Ns ...
 135  135  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 136  136  .Ar filesystem Ns | Ns Ar snapshot
 137  137  .Nm
 138  138  .Cm groupspace
 139  139  .Op Fl Hinp
 140  140  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 141  141  .Oo Fl s Ar field Oc Ns ...
 142  142  .Oo Fl S Ar field Oc Ns ...
 143  143  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 144  144  .Ar filesystem Ns | Ns Ar snapshot
 145  145  .Nm
 146  146  .Cm mount
 147  147  .Nm
 148  148  .Cm mount
 149  149  .Op Fl Ov
 150  150  .Op Fl o Ar options
 151  151  .Fl a | Ar filesystem
 152  152  .Nm
 153  153  .Cm unmount
 154  154  .Op Fl f
 155  155  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
 156  156  .Nm
 157  157  .Cm share
 158  158  .Fl a | Ar filesystem
 159  159  .Nm
 160  160  .Cm unshare
 161  161  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
 162  162  .Nm
 163  163  .Cm bookmark
 164  164  .Ar snapshot bookmark
 165  165  .Nm
 166  166  .Cm send
 167  167  .Op Fl DLPRenpv
 168  168  .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
 169  169  .Ar snapshot
 170  170  .Nm
 171  171  .Cm send
 172  172  .Op Fl Le
 173  173  .Op Fl i Ar snapshot Ns | Ns Ar bookmark
 174  174  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
 175  175  .Nm
 176  176  .Cm send
 177  177  .Op Fl Penv
 178  178  .Fl t Ar receive_resume_token
 179  179  .Nm
 180  180  .Cm receive
 181  181  .Op Fl Fnsuv
 182  182  .Op Fl o Sy origin Ns = Ns Ar snapshot
 183  183  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
 184  184  .Nm
 185  185  .Cm receive
 186  186  .Op Fl Fnsuv
 187  187  .Op Fl d Ns | Ns Fl e
 188  188  .Op Fl o Sy origin Ns = Ns Ar snapshot
 189  189  .Ar filesystem
 190  190  .Nm
 191  191  .Cm receive
 192  192  .Fl A
 193  193  .Ar filesystem Ns | Ns Ar volume
 194  194  .Nm
 195  195  .Cm allow
 196  196  .Ar filesystem Ns | Ns Ar volume
 197  197  .Nm
 198  198  .Cm allow
 199  199  .Op Fl dglu
 200  200  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
 201  201  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 202  202  .Ar setname Oc Ns ...
 203  203  .Ar filesystem Ns | Ns Ar volume
 204  204  .Nm
 205  205  .Cm allow
 206  206  .Op Fl dl
 207  207  .Fl e Ns | Ns Sy everyone
 208  208  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 209  209  .Ar setname Oc Ns ...
 210  210  .Ar filesystem Ns | Ns Ar volume
 211  211  .Nm
 212  212  .Cm allow
 213  213  .Fl c
 214  214  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 215  215  .Ar setname Oc Ns ...
 216  216  .Ar filesystem Ns | Ns Ar volume
 217  217  .Nm
 218  218  .Cm allow
 219  219  .Fl s No @ Ns Ar setname
 220  220  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 221  221  .Ar setname Oc Ns ...
 222  222  .Ar filesystem Ns | Ns Ar volume
 223  223  .Nm
 224  224  .Cm unallow
 225  225  .Op Fl dglru
 226  226  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
 227  227  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 228  228  .Ar setname Oc Ns ... Oc
 229  229  .Ar filesystem Ns | Ns Ar volume
 230  230  .Nm
 231  231  .Cm unallow
 232  232  .Op Fl dlr
 233  233  .Fl e Ns | Ns Sy everyone
 234  234  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 235  235  .Ar setname Oc Ns ... Oc
 236  236  .Ar filesystem Ns | Ns Ar volume
 237  237  .Nm
 238  238  .Cm unallow
 239  239  .Op Fl r
 240  240  .Fl c
 241  241  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 242  242  .Ar setname Oc Ns ... Oc
 243  243  .Ar filesystem Ns | Ns Ar volume
 244  244  .Nm
 245  245  .Cm unallow
 246  246  .Op Fl r
 247  247  .Fl s @ Ns Ar setname
 248  248  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 249  249  .Ar setname Oc Ns ... Oc
 250  250  .Ar filesystem Ns | Ns Ar volume
 251  251  .Nm
 252  252  .Cm hold
 253  253  .Op Fl r
 254  254  .Ar tag Ar snapshot Ns ...
 255  255  .Nm
 256  256  .Cm holds
 257  257  .Op Fl r
 258  258  .Ar snapshot Ns ...
 259  259  .Nm
 260  260  .Cm release
 261  261  .Op Fl r
 262  262  .Ar tag Ar snapshot Ns ...
 263  263  .Nm
 264  264  .Cm diff
 265  265  .Op Fl FHt
 266  266  .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
 267  267  .Sh DESCRIPTION
 268  268  The
 269  269  .Nm
 270  270  command configures ZFS datasets within a ZFS storage pool, as described in
 271  271  .Xr zpool 1M .
 272  272  A dataset is identified by a unique path within the ZFS namespace. For example:
 273  273  .Bd -literal
 274  274  pool/{filesystem,volume,snapshot}
 275  275  .Ed
 276  276  .Pp
 277  277  where the maximum length of a dataset name is
 278  278  .Dv MAXNAMELEN
 279  279  .Pq 256 bytes .
 280  280  .Pp
 281  281  A dataset can be one of the following:
 282  282  .Bl -tag -width "file system"
 283  283  .It Sy file system
 284  284  A ZFS dataset of type
 285  285  .Sy filesystem
 286  286  can be mounted within the standard system namespace and behaves like other file
 287  287  systems. While ZFS file systems are designed to be POSIX compliant, known issues
 288  288  exist that prevent compliance in some cases. Applications that depend on
 289  289  standards conformance might fail due to non-standard behavior when checking file
 290  290  system free space.
 291  291  .It Sy volume
 292  292  A logical volume exported as a raw or block device. This type of dataset should
 293  293  only be used under special circumstances. File systems are typically used in
 294  294  most environments.
 295  295  .It Sy snapshot
 296  296  A read-only version of a file system or volume at a given point in time. It is
 297  297  specified as
 298  298  .Ar filesystem Ns @ Ns Ar name
 299  299  or
 300  300  .Ar volume Ns @ Ns Ar name .
 301  301  .El
 302  302  .Ss ZFS File System Hierarchy
 303  303  A ZFS storage pool is a logical collection of devices that provide space for
 304  304  datasets. A storage pool is also the root of the ZFS file system hierarchy.
 305  305  .Pp
 306  306  The root of the pool can be accessed as a file system, such as mounting and
 307  307  unmounting, taking snapshots, and setting properties. The physical storage
 308  308  characteristics, however, are managed by the
 309  309  .Xr zpool 1M
 310  310  command.
 311  311  .Pp
 312  312  See
 313  313  .Xr zpool 1M
 314  314  for more information on creating and administering pools.
 315  315  .Ss Snapshots
 316  316  A snapshot is a read-only copy of a file system or volume. Snapshots can be
 317  317  created extremely quickly, and initially consume no additional space within the
 318  318  pool. As data within the active dataset changes, the snapshot consumes more
 319  319  data than would otherwise be shared with the active dataset.
 320  320  .Pp
 321  321  Snapshots can have arbitrary names. Snapshots of volumes can be cloned or
 322  322  rolled back, but cannot be accessed independently.
 323  323  .Pp
 324  324  File system snapshots can be accessed under the
 325  325  .Pa .zfs/snapshot
 326  326  directory in the root of the file system. Snapshots are automatically mounted on
 327  327  demand and may be unmounted at regular intervals. The visibility of the
 328  328  .Pa .zfs
 329  329  directory can be controlled by the
 330  330  snapdir
 331  331  property.
 332  332  .Ss Clones
 333  333  A clone is a writable volume or file system whose initial contents are the same
 334  334  as another dataset. As with snapshots, creating a clone is nearly instantaneous,
 335  335  and initially consumes no additional space.
 336  336  .Pp
 337  337  Clones can only be created from a snapshot. When a snapshot is cloned, it
 338  338  creates an implicit dependency between the parent and child. Even though the
 339  339  clone is created somewhere else in the dataset hierarchy, the original snapshot
 340  340  cannot be destroyed as long as a clone exists. The
 341  341  .Sy origin
 342  342  property exposes this dependency, and the
 343  343  .Cm destroy
 344  344  command lists any such dependencies, if they exist.
 345  345  .Pp
 346  346  The clone parent-child dependency relationship can be reversed by using the
 347  347  .Cm promote
 348  348  subcommand. This causes the
 349  349  .Qq origin
 350  350  file system to become a clone of the specified file system, which makes it
 351  351  possible to destroy the file system that the clone was created from.
 352  352  .Ss "Mount Points"
 353  353  Creating a ZFS file system is a simple operation, so the number of file systems
 354  354  per system is likely to be numerous. To cope with this, ZFS automatically
 355  355  manages mounting and unmounting file systems without the need to edit the
 356  356  .Pa /etc/vfstab
 357  357  file. All automatically managed file systems are mounted by ZFS at boot time.
 358  358  .Pp
 359  359  By default, file systems are mounted under
 360  360  .Pa /path ,
 361  361  where
 362  362  .Ar path
 363  363  is the name of the file system in the ZFS namespace. Directories are created and
 364  364  destroyed as needed.
 365  365  .Pp
 366  366  A file system can also have a mount point set in the
 367  367  .Sy mountpoint
 368  368  property. This directory is created as needed, and ZFS automatically mounts the
 369  369  file system when the
 370  370  .Nm zfs Cm mount Fl a
 371  371  command is invoked
 372  372  .Po without editing
 373  373  .Pa /etc/vfstab
 374  374  .Pc .
 375  375  The
 376  376  .Sy mountpoint
 377  377  property can be inherited, so if
 378  378  .Em pool/home
 379  379  has a mount point of
 380  380  .Pa /export/stuff ,
 381  381  then
 382  382  .Em pool/home/user
 383  383  automatically inherits a mount point of
 384  384  .Pa /export/stuff/user .
 385  385  .Pp
 386  386  A file system
 387  387  .Sy mountpoint
 388  388  property of
 389  389  .Sy none
 390  390  prevents the file system from being mounted.
 391  391  .Pp
 392  392  If needed, ZFS file systems can also be managed with traditional tools
 393  393  .Po
 394  394  .Nm mount ,
 395  395  .Nm umount ,
 396  396  .Pa /etc/vfstab
 397  397  .Pc .
 398  398  If a file system's mount point is set to
 399  399  .Sy legacy ,
 400  400  ZFS makes no attempt to manage the file system, and the administrator is
 401  401  responsible for mounting and unmounting the file system.
 402  402  .Ss "Zones"
 403  403  A ZFS file system can be added to a non-global zone by using the
 404  404  .Nm zonecfg Cm add Sy fs
 405  405  subcommand. A ZFS file system that is added to a non-global zone must have its
 406  406  .Sy mountpoint
 407  407  property set to
 408  408  .Sy legacy .
 409  409  .Pp
 410  410  The physical properties of an added file system are controlled by the global
 411  411  administrator. However, the zone administrator can create, modify, or destroy
 412  412  files within the added file system, depending on how the file system is mounted.
 413  413  .Pp
 414  414  A dataset can also be delegated to a non-global zone by using the
 415  415  .Nm zonecfg Cm add Sy dataset
 416  416  subcommand. You cannot delegate a dataset to one zone and the children of the
 417  417  same dataset to another zone. The zone administrator can change properties of
 418  418  the dataset or any of its children. However, the
 419  419  .Sy quota ,
 420  420  .Sy filesystem_limit
 421  421  and
 422  422  .Sy snapshot_limit
 423  423  properties of the delegated dataset can be modified only by the global
 424  424  administrator.
 425  425  .Pp
 426  426  A ZFS volume can be added as a device to a non-global zone by using the
 427  427  .Nm zonecfg Cm add Sy device
 428  428  subcommand. However, its physical properties can be modified only by the global
 429  429  administrator.
 430  430  .Pp
 431  431  For more information about
 432  432  .Nm zonecfg
 433  433  syntax, see
 434  434  .Xr zonecfg 1M .
 435  435  .Pp
 436  436  After a dataset is delegated to a non-global zone, the
 437  437  .Sy zoned
 438  438  property is automatically set. A zoned file system cannot be mounted in the
 439  439  global zone, since the zone administrator might have to set the mount point to
 440  440  an unacceptable value.
 441  441  .Pp
 442  442  The global administrator can forcibly clear the
 443  443  .Sy zoned
 444  444  property, though this should be done with extreme care. The global administrator
 445  445  should verify that all the mount points are acceptable before clearing the
 446  446  property.
 447  447  .Ss Native Properties
 448  448  Properties are divided into two types, native properties and user-defined
 449  449  .Po or
 450  450  .Qq user
 451  451  .Pc
 452  452  properties. Native properties either export internal statistics or control ZFS
 453  453  behavior. In addition, native properties are either editable or read-only. User
 454  454  properties have no effect on ZFS behavior, but you can use them to annotate
 455  455  datasets in a way that is meaningful in your environment. For more information
 456  456  about user properties, see the
 457  457  .Sx User Properties
 458  458  section, below.
 459  459  .Pp
 460  460  Every dataset has a set of properties that export statistics about the dataset
 461  461  as well as control various behaviors. Properties are inherited from the parent
 462  462  unless overridden by the child. Some properties apply only to certain types of
 463  463  datasets
 464  464  .Pq file systems, volumes, or snapshots .
 465  465  .Pp
 466  466  The values of numeric properties can be specified using human-readable suffixes
 467  467  .Po for example,
 468  468  .Sy k ,
 469  469  .Sy KB ,
 470  470  .Sy M ,
 471  471  .Sy Gb ,
 472  472  and so forth, up to
 473  473  .Sy Z
 474  474  for zettabyte
 475  475  .Pc .
 476  476  The following are all valid
 477  477  .Pq and equal
 478  478  specifications:
 479  479  .Li 1536M, 1.5g, 1.50GB .
 480  480  .Pp
 481  481  The values of non-numeric properties are case sensitive and must be lowercase,
 482  482  except for
 483  483  .Sy mountpoint ,
 484  484  .Sy sharenfs ,
 485  485  and
 486  486  .Sy sharesmb .
 487  487  .Pp
 488  488  The following native properties consist of read-only statistics about the
 489  489  dataset. These properties can be neither set, nor inherited. Native properties
 490  490  apply to all dataset types unless otherwise noted.
 491  491  .Bl -tag -width "usedbyrefreservation"
 492  492  .It Sy available
 493  493  The amount of space available to the dataset and all its children, assuming that
 494  494  there is no other activity in the pool. Because space is shared within a pool,
 495  495  availability can be limited by any number of factors, including physical pool
 496  496  size, quotas, reservations, or other datasets within the pool.
 497  497  .Pp
 498  498  This property can also be referred to by its shortened column name,
 499  499  .Sy avail .
 500  500  .It Sy compressratio
 501  501  For non-snapshots, the compression ratio achieved for the
 502  502  .Sy used
 503  503  space of this dataset, expressed as a multiplier. The
 504  504  .Sy used
 505  505  property includes descendant datasets, and, for clones, does not include the
 506  506  space shared with the origin snapshot. For snapshots, the
 507  507  .Sy compressratio
 508  508  is the same as the
 509  509  .Sy refcompressratio
 510  510  property. Compression can be turned on by running:
 511  511  .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
 512  512  The default value is
 513  513  .Sy off .
 514  514  .It Sy creation
 515  515  The time this dataset was created.
 516  516  .It Sy clones
 517  517  For snapshots, this property is a comma-separated list of filesystems or volumes
 518  518  which are clones of this snapshot. The clones'
 519  519  .Sy origin
 520  520  property is this snapshot. If the
 521  521  .Sy clones
 522  522  property is not empty, then this snapshot can not be destroyed
 523  523  .Po even with the
 524  524  .Fl r
 525  525  or
 526  526  .Fl f
 527  527  options
 528  528  .Pc .
 529  529  .It Sy defer_destroy
 530  530  This property is
 531  531  .Sy on
 532  532  if the snapshot has been marked for deferred destroy by using the
 533  533  .Nm zfs Cm destroy Fl d
 534  534  command. Otherwise, the property is
 535  535  .Sy off .
 536  536  .It Sy filesystem_count
 537  537  The total number of filesystems and volumes that exist under this location in
 538  538  the dataset tree. This value is only available when a
 539  539  .Sy filesystem_limit
 540  540  has been set somewhere in the tree under which the dataset resides.
 541  541  .It Sy logicalreferenced
 542  542  The amount of space that is
 543  543  .Qq logically
 544  544  accessible by this dataset. See the
 545  545  .Sy referenced
 546  546  property. The logical space ignores the effect of the
 547  547  .Sy compression
 548  548  and
 549  549  .Sy copies
 550  550  properties, giving a quantity closer to the amount of data that applications
 551  551  see. However, it does include space consumed by metadata.
 552  552  .Pp
 553  553  This property can also be referred to by its shortened column name,
 554  554  .Sy lrefer .
 555  555  .It Sy logicalused
 556  556  The amount of space that is
 557  557  .Qq logically
 558  558  consumed by this dataset and all its descendents. See the
 559  559  .Sy used
 560  560  property. The logical space ignores the effect of the
 561  561  .Sy compression
 562  562  and
 563  563  .Sy copies
 564  564  properties, giving a quantity closer to the amount of data that applications
 565  565  see. However, it does include space consumed by metadata.
 566  566  .Pp
 567  567  This property can also be referred to by its shortened column name,
 568  568  .Sy lused .
 569  569  .It Sy mounted
 570  570  For file systems, indicates whether the file system is currently mounted. This
 571  571  property can be either
 572  572  .Sy yes
 573  573  or
 574  574  .Sy no .
 575  575  .It Sy origin
 576  576  For cloned file systems or volumes, the snapshot from which the clone was
 577  577  created. See also the
 578  578  .Sy clones
 579  579  property.
 580  580  .It Sy receive_resume_token
 581  581  For filesystems or volumes which have saved partially-completed state from
 582  582  .Sy zfs receive -s ,
 583  583  this opaque token can be provided to
 584  584  .Sy zfs send -t
 585  585  to resume and complete the
 586  586  .Sy zfs receive .
 587  587  .It Sy referenced
 588  588  The amount of data that is accessible by this dataset, which may or may not be
 589  589  shared with other datasets in the pool. When a snapshot or clone is created, it
 590  590  initially references the same amount of space as the file system or snapshot it
 591  591  was created from, since its contents are identical.
 592  592  .Pp
 593  593  This property can also be referred to by its shortened column name,
 594  594  .Sy refer .
 595  595  .It Sy refcompressratio
 596  596  The compression ratio achieved for the
 597  597  .Sy referenced
 598  598  space of this dataset, expressed as a multiplier. See also the
 599  599  .Sy compressratio
 600  600  property.
 601  601  .It Sy snapshot_count
 602  602  The total number of snapshots that exist under this location in the dataset
 603  603  tree. This value is only available when a
 604  604  .Sy snapshot_limit
 605  605  has been set somewhere in the tree under which the dataset resides.
 606  606  .It Sy type
 607  607  The type of dataset:
 608  608  .Sy filesystem ,
 609  609  .Sy volume ,
 610  610  or
 611  611  .Sy snapshot .
 612  612  .It Sy used
 613  613  The amount of space consumed by this dataset and all its descendents. This is
 614  614  the value that is checked against this dataset's quota and reservation. The
 615  615  space used does not include this dataset's reservation, but does take into
 616  616  account the reservations of any descendent datasets. The amount of space that a
 617  617  dataset consumes from its parent, as well as the amount of space that are freed
 618  618  if this dataset is recursively destroyed, is the greater of its space used and
 619  619  its reservation.
 620  620  .Pp
 621  621  When snapshots
 622  622  .Po see the
 623  623  .Sx Snapshots
 624  624  section
 625  625  .Pc
 626  626  are created, their space is initially shared between the snapshot and
 627  627  the file system, and possibly with previous snapshots. As the file system
 628  628  changes, space that was previously shared becomes unique to the snapshot, and
 629  629  counted in the snapshot's space used. Additionally, deleting snapshots can
 630  630  increase the amount of space unique to
 631  631  .Pq and used by
 632  632  other snapshots.
 633  633  .Pp
 634  634  The amount of space used, available, or referenced does not take into account
 635  635  pending changes. Pending changes are generally accounted for within a few
 636  636  seconds. Committing a change to a disk using
 637  637  .Xr fsync 3C
 638  638  or
 639  639  .Dv O_SYNC
 640  640  does not necessarily guarantee that the space usage information is updated
 641  641  immediately.
 642  642  .It Sy usedby*
 643  643  The
 644  644  .Sy usedby*
 645  645  properties decompose the
 646  646  .Sy used
 647  647  properties into the various reasons that space is used. Specifically,
 648  648  .Sy used No =
 649  649  .Sy usedbychildren No +
 650  650  .Sy usedbydataset No +
 651  651  .Sy usedbyrefreservation No +
 652  652  .Sy usedbysnapshots .
 653  653  These properties are only available for datasets created on
 654  654  .Nm zpool
 655  655  .Qo version 13 Qc
 656  656  pools.
 657  657  .It Sy usedbychildren
 658  658  The amount of space used by children of this dataset, which would be freed if
 659  659  all the dataset's children were destroyed.
 660  660  .It Sy usedbydataset
 661  661  The amount of space used by this dataset itself, which would be freed if the
 662  662  dataset were destroyed
 663  663  .Po after first removing any
 664  664  .Sy refreservation
 665  665  and destroying any necessary snapshots or descendents
 666  666  .Pc .
 667  667  .It Sy usedbyrefreservation
 668  668  The amount of space used by a
 669  669  .Sy refreservation
 670  670  set on this dataset, which would be freed if the
 671  671  .Sy refreservation
 672  672  was removed.
 673  673  .It Sy usedbysnapshots
 674  674  The amount of space consumed by snapshots of this dataset. In particular, it is
 675  675  the amount of space that would be freed if all of this dataset's snapshots were
 676  676  destroyed. Note that this is not simply the sum of the snapshots'
 677  677  .Sy used
 678  678  properties because space can be shared by multiple snapshots.
 679  679  .It Sy userused Ns @ Ns Em user
 680  680  The amount of space consumed by the specified user in this dataset. Space is
 681  681  charged to the owner of each file, as displayed by
 682  682  .Nm ls Fl l .
 683  683  The amount of space charged is displayed by
 684  684  .Nm du
 685  685  and
 686  686  .Nm ls Fl s .
 687  687  See the
 688  688  .Nm zfs Cm userspace
 689  689  subcommand for more information.
 690  690  .Pp
 691  691  Unprivileged users can access only their own space usage. The root user, or a
 692  692  user who has been granted the
 693  693  .Sy userused
 694  694  privilege with
 695  695  .Nm zfs Cm allow ,
 696  696  can access everyone's usage.
 697  697  .Pp
 698  698  The
 699  699  .Sy userused Ns @ Ns Em ...
 700  700  properties are not displayed by
 701  701  .Nm zfs Cm get Sy all .
 702  702  The user's name must be appended after the @ symbol, using one of the following
 703  703  forms:
 704  704  .Bl -bullet -width ""
 705  705  .It
 706  706  .Em POSIX name
 707  707  .Po for example,
 708  708  .Sy joe
 709  709  .Pc
 710  710  .It
 711  711  .Em POSIX numeric ID
 712  712  .Po for example,
 713  713  .Sy 789
 714  714  .Pc
 715  715  .It
 716  716  .Em SID name
 717  717  .Po for example,
 718  718  .Sy joe.smith@mydomain
 719  719  .Pc
 720  720  .It
 721  721  .Em SID numeric ID
 722  722  .Po for example,
 723  723  .Sy S-1-123-456-789
 724  724  .Pc
 725  725  .El
 726  726  .It Sy userrefs
 727  727  This property is set to the number of user holds on this snapshot. User holds
 728  728  are set by using the
 729  729  .Nm zfs Cm hold
 730  730  command.
 731  731  .It Sy groupused Ns @ Ns Em group
 732  732  The amount of space consumed by the specified group in this dataset. Space is
 733  733  charged to the group of each file, as displayed by
 734  734  .Nm ls Fl l .
 735  735  See the
 736  736  .Sy userused Ns @ Ns Em user
 737  737  property for more information.
 738  738  .Pp
 739  739  Unprivileged users can only access their own groups' space usage. The root user,
 740  740  or a user who has been granted the
 741  741  .Sy groupused
 742  742  privilege with
 743  743  .Nm zfs Cm allow ,
 744  744  can access all groups' usage.
 745  745  .It Sy volblocksize Ns = Ns Em blocksize
 746  746  For volumes, specifies the block size of the volume. The
 747  747  .Sy blocksize
 748  748  cannot be changed once the volume has been written, so it should be set at
 749  749  volume creation time. The default
 750  750  .Sy blocksize
 751  751  for volumes is 8 Kbytes. Any power of 2 from 512 bytes to 128 Kbytes is valid.
 752  752  .Pp
 753  753  This property can also be referred to by its shortened column name,
 754  754  .Sy volblock .
 755  755  .It Sy written
 756  756  The amount of
 757  757  .Sy referenced
 758  758  space written to this dataset since the previous snapshot.
 759  759  .It Sy written Ns @ Ns Em snapshot
 760  760  The amount of
 761  761  .Sy referenced
 762  762  space written to this dataset since the specified snapshot. This is the space
 763  763  that is referenced by this dataset but was not referenced by the specified
 764  764  snapshot.
 765  765  .Pp
 766  766  The
 767  767  .Em snapshot
 768  768  may be specified as a short snapshot name
 769  769  .Po just the part after the
 770  770  .Sy @
 771  771  .Pc ,
 772  772  in which case it will be interpreted as a snapshot in the same filesystem as
 773  773  this dataset. The
 774  774  .Em snapshot
 775  775  may be a full snapshot name
 776  776  .No Po Em filesystem Ns @ Ns Em snapshot Pc ,
 777  777  which for clones may be a snapshot in the origin's filesystem
 778  778  .Pq or the origin of the origin's filesystem, etc.
 779  779  .El
 780  780  .Pp
 781  781  The following native properties can be used to change the behavior of a ZFS
 782  782  dataset.
 783  783  .Bl -tag -width ""
 784  784  .It Xo
 785  785  .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
 786  786  .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
 787  787  .Xc
 788  788  Controls how
 789  789  .Sy ACE Ns s
 790  790  are inherited when files and directories are created.
 791  791  .Bl -tag -width "passthrough-x"
 792  792  .It Sy discard
 793  793  does not inherit any
 794  794  .Sy ACE Ns s .
 795  795  .It Sy noallow
 796  796  only inherits inheritable
 797  797  .Sy ACE Ns s
 798  798  that specify
 799  799  .Qq deny
 800  800  permissions.
 801  801  .It Sy restricted
 802  802  default, removes the
 803  803  .Sy write_acl
 804  804  and
 805  805  .Sy write_owner
 806  806  permissions when the
 807  807  .Sy ACE
 808  808  is inherited.
 809  809  .It Sy passthrough
 810  810  inherits all inheritable
 811  811  .Sy ACE Ns s
 812  812  without any modifications.
 813  813  .It Sy passthrough-x
 814  814  same meaning as
 815  815  .Sy passthrough ,
 816  816  except that the
 817  817  .Sy owner@ ,
 818  818  .Sy group@ ,
 819  819  and
 820  820  .Sy everyone@
 821  821  .Sy ACE Ns s
 822  822  inherit the execute permission only if the file creation mode also requests the
 823  823  execute bit.
 824  824  .El
 825  825  .Pp
 826  826  When the property value is set to
 827  827  .Sy passthrough ,
 828  828  files are created with a mode determined by the inheritable
 829  829  .Sy ACE Ns s .
 830  830  If no inheritable
 831  831  .Sy ACE Ns s
 832  832  exist that affect the mode, then the mode is set in accordance to the requested
 833  833  mode from the application.
 834  834  .It Xo
 835  835  .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
 836  836  .Sy passthrough Ns | Ns Sy restricted
 837  837  .Xc
 838  838  Controls how an
 839  839  .Sy ACL
 840  840  is modified during
 841  841  .Xr chmod 2 .
 842  842  .Bl -tag -width "passthrough"
 843  843  .It Sy discard
 844  844  default, deletes all
 845  845  .Sy ACE Ns s
 846  846  that do not represent the mode of the file.
 847  847  .It Sy groupmask
 848  848  reduces permissions granted in all
 849  849  .Sy ALLOW
 850  850  entries found in the
 851  851  .Sy ACL
 852  852  such that they are no greater than the group permissions specified by
 853  853  .Xr chmod 2 .
 854  854  .It Sy passthrough
 855  855  indicates that no changes are made to the
 856  856  .Sy ACL
 857  857  other than creating or updating the necessary
 858  858  .Sy ACE Ns s
 859  859  to represent the new mode of the file or directory.
 860  860  .It Sy restricted
 861  861  causes the
 862  862  .Xr chmod 2
 863  863  operation to return an error when used on any file or directory which has a
 864  864  non-trivial
 865  865  .Sy ACE Ns s
 866  866  whose entries can not be represented by a mode.
 867  867  .El
 868  868  .Pp
 869  869  .Xr chmod 2
 870  870  is required to change the set user ID, set group ID, or sticky bits on a file or
 871  871  directory, as they do not have equivalent
 872  872  .Sy ACE Ns s.
 873  873  In order to use
 874  874  .Xr chmod 2
 875  875  on a file or directory with a non-trivial
 876  876  .Sy ACL
 877  877  when
 878  878  .Sy aclmode
 879  879  is set to
 880  880  .Sy restricted ,
 881  881  you must first remove all
 882  882  .Sy ACE Ns s
 883  883  which do not represent the current mode.
 884  884  .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
 885  885  Controls whether the access time for files is updated when they are read.
 886  886  Turning this property off avoids producing write traffic when reading files and
 887  887  can result in significant performance gains, though it might confuse mailers
 888  888  and other similar utilities. The default value is
 889  889  .Sy on .
 890  890  .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
 891  891  If this property is set to
 892  892  .Sy off ,
 893  893  the file system cannot be mounted, and is ignored by
 894  894  .Nm zfs Cm mount Fl a .
 895  895  Setting this property to
 896  896  .Sy off
 897  897  is similar to setting the
 898  898  .Sy mountpoint
 899  899  property to
 900  900  .Sy none ,
 901  901  except that the dataset still has a normal
 902  902  .Sy mountpoint
 903  903  property, which can be inherited. Setting this property to
 904  904  .Sy off
 905  905  allows datasets to be used solely as a mechanism to inherit properties. One
 906  906  example of setting
 907  907  .Sy canmount Ns = Ns Sy off
 908  908  is to have two datasets with the same
 909  909  .Sy mountpoint ,
 910  910  so that the children of both datasets appear in the same directory, but might
 911  911  have different inherited characteristics.
 912  912  .Pp
 913  913  When set to
 914  914  .Sy noauto ,
 915  915  a dataset can only be mounted and unmounted explicitly. The dataset is not
 916  916  mounted automatically when the dataset is created or imported, nor is it mounted
 917  917  by the
 918  918  .Nm zfs Cm mount Fl a
 919  919  command or unmounted by the
 920  920  .Nm zfs Cm unmount Fl a
 921  921  command.
 922  922  .Pp
 923  923  This property is not inherited.
 924  924  .It Xo
 925  925  .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
 926  926  .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
 927  927  .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
 928  928  .Xc
 929  929  Controls the checksum used to verify data integrity. The default value is
 930  930  .Sy on ,
 931  931  which automatically selects an appropriate algorithm
 932  932  .Po currently,
 933  933  .Sy fletcher4 ,
 934  934  but this may change in future releases
 935  935  .Pc .
 936  936  The value
 937  937  .Sy off
 938  938  disables integrity checking on user data. The value
 939  939  .Sy noparity
 940  940  not only disables integrity but also disables maintaining parity for user data.
 941  941  This setting is used internally by a dump device residing on a RAID-Z pool and
 942  942  should not be used by any other dataset. Disabling checksums is
 943  943  .Sy NOT
 944  944  a recommended practice.
 945  945  .Pp
 946  946  The
 947  947  .Sy sha512 ,
 948  948  .Sy skein ,
 949  949  and
 950  950  .Sy edonr
 951  951  checksum algorithms require enabling the appropriate features on the
 952  952  pool. Please see
 953  953  .Xr zpool-features 5
 954  954  for more information on these algorithms.
 955  955  .Pp
 956  956  Changing this property affects only newly-written data.
 957  957  .It Xo
 958  958  .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
 959  959  .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
 960  960  .Xc
 961  961  Controls the compression algorithm used for this dataset.
 962  962  .Pp
 963  963  Setting compression to
 964  964  .Sy on
 965  965  indicates that the current default compression algorithm should be used. The
 966  966  default balances compression and decompression speed, with compression ratio and
 967  967  is expected to work well on a wide variety of workloads.  Unlike all other
 968  968  settings for this property,
 969  969  .Sy on
 970  970  does not select a fixed compression type. As new compression algorithms are
 971  971  added to ZFS and enabled on a pool, the default compression algorithm may
 972  972  change. The current default compression algorthm is either
 973  973  .Sy lzjb
 974  974  or, if the
 975  975  .Sy lz4_compress
 976  976  feature is enabled,
 977  977  .Sy lz4 .
 978  978  .Pp
 979  979  The
 980  980  .Sy lz4
 981  981  compression algorithm is a high-performance replacement for the
 982  982  .Sy lzjb
 983  983  algorithm. It features significantly faster compression and decompression, as
 984  984  well as a moderately higher compression ratio than
 985  985  .Sy lzjb ,
 986  986  but can only be used on pools with the
 987  987  .Sy lz4_compress
 988  988  feature set to
 989  989  .Sy enabled .
 990  990  See
 991  991  .Xr zpool-features 5
 992  992  for details on ZFS feature flags and the
 993  993  .Sy lz4_compress
 994  994  feature.
 995  995  .Pp
 996  996  The
 997  997  .Sy lzjb
 998  998  compression algorithm is optimized for performance while providing decent data
 999  999  compression.
1000 1000  .Pp
1001 1001  The
1002 1002  .Sy gzip
1003 1003  compression algorithm uses the same compression as the
1004 1004  .Xr gzip 1
1005 1005  command. You can specify the
1006 1006  .Sy gzip
1007 1007  level by using the value
1008 1008  .Sy gzip- Ns Em N ,
1009 1009  where
1010 1010  .Em N
1011 1011  is an integer from 1
1012 1012  .Pq fastest
1013 1013  to 9
1014 1014  .Pq best compression ratio .
1015 1015  Currently,
1016 1016  .Sy gzip
1017 1017  is equivalent to
1018 1018  .Sy gzip-6
1019 1019  .Po which is also the default for
1020 1020  .Xr gzip 1
1021 1021  .Pc .
1022 1022  .Pp
1023 1023  The
1024 1024  .Sy zle
1025 1025  compression algorithm compresses runs of zeros.
1026 1026  .Pp
1027 1027  This property can also be referred to by its shortened column name
1028 1028  \fBcompress\fR. Changing this property affects only newly-written data.
1029 1029  .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1030 1030  Controls the number of copies of data stored for this dataset. These copies are
1031 1031  in addition to any redundancy provided by the pool, for example, mirroring or
1032 1032  RAID-Z. The copies are stored on different disks, if possible. The space used
1033 1033  by multiple copies is charged to the associated file and dataset, changing the
1034 1034  .Sy used
1035 1035  property and counting against quotas and reservations.
1036 1036  .Pp
1037 1037  Changing this property only affects newly-written data. Therefore, set this
1038 1038  property at file system creation time by using the
1039 1039  .Fl o Sy copies Ns = Ns Ar N
1040 1040  option.
1041 1041  .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1042 1042  Controls whether device nodes can be opened on this file system. The default
1043 1043  value is
1044 1044  .Sy on .
1045 1045  .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1046 1046  Controls whether processes can be executed from within this file system. The
1047 1047  default value is
1048 1048  .Sy on .
1049 1049  .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1050 1050  Limits the number of filesystems and volumes that can exist under this point in
1051 1051  the dataset tree. The limit is not enforced if the user is allowed to change
1052 1052  the limit. Setting a
1053 1053  .Sy filesystem_limit

1054 1054  to
1055 1055  .Sy on
1056 1056  a descendent of a filesystem that already has a
1057 1057  .Sy filesystem_limit
1058 1058  does not override the ancestor's
1059 1059  .Sy filesystem_limit ,
1060 1060  but rather imposes an additional limit. This feature must be enabled to be used
1061 1061  .Po see
1062 1062  .Xr zpool-features 5
1063 1063  .Pc .
     1064 +.It Sy fsid_guid Ns = Ns Sy value Ns
     1065 +Sets the dataset fsid_guid. The fsid_guid is a 64-bit unsigned integer, used to
     1066 +construct the vfs id when mounting a dataset.
     1067 +This property should only be set if you need the vfs id to be identical on two
     1068 +systems, for example in a NFS migration scenario.
     1069 +When the fsid_guid is changed for a file system, the file system and any
     1070 +children that inherit the mountpoint are unmounted, then remounted. If the
     1071 +file system was shared, existing NFS clients will require a remount.
1064 1072  .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1065 1073  Controls the mount point used for this file system. See the
1066 1074  .Sx Mount Points
1067 1075  section for more information on how this property is used.
1068 1076  .Pp
1069 1077  When the
1070 1078  .Sy mountpoint
1071 1079  property is changed for a file system, the file system and any children that
1072 1080  inherit the mount point are unmounted. If the new value is
1073 1081  .Sy legacy ,

1074 1082  then they remain unmounted. Otherwise, they are automatically remounted in the
1075 1083  new location if the property was previously
1076 1084  .Sy legacy
1077 1085  or
1078 1086  .Sy none ,
1079 1087  or if they were mounted before the property was changed. In addition, any shared
1080 1088  file systems are unshared and shared in the new location.
1081 1089  .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1082 1090  Controls whether the file system should be mounted with
1083 1091  .Sy nbmand
1084 1092  .Pq Non Blocking mandatory locks .
1085 1093  This is used for SMB clients. Changes to this property only take effect when the
1086 1094  file system is umounted and remounted. See
1087 1095  .Xr mount 1M
1088 1096  for more information on
1089 1097  .Sy nbmand
1090 1098  mounts.
1091 1099  .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1092 1100  Controls what is cached in the primary cache
1093 1101  .Pq ARC .
1094 1102  If this property is set to
1095 1103  .Sy all ,
1096 1104  then both user data and metadata is cached. If this property is set to
1097 1105  .Sy none ,
1098 1106  then neither user data nor metadata is cached. If this property is set to
1099 1107  .Sy metadata ,
1100 1108  then only metadata is cached. The default value is
1101 1109  .Sy all .
1102 1110  .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1103 1111  Limits the amount of space a dataset and its descendents can consume. This
1104 1112  property enforces a hard limit on the amount of space used. This includes all
1105 1113  space consumed by descendents, including file systems and snapshots. Setting a
1106 1114  quota on a descendent of a dataset that already has a quota does not override
1107 1115  the ancestor's quota, but rather imposes an additional limit.
1108 1116  .Pp
1109 1117  Quotas cannot be set on volumes, as the
1110 1118  .Sy volsize
1111 1119  property acts as an implicit quota.
1112 1120  .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1113 1121  Limits the number of snapshots that can be created on a dataset and its
1114 1122  descendents. Setting a
1115 1123  .Sy snapshot_limit
1116 1124  on a descendent of a dataset that already has a
1117 1125  .Sy snapshot_limit
1118 1126  does not override the ancestor's
1119 1127  .Sy snapshot_limit ,
1120 1128  but rather imposes an additional limit. The limit is not enforced if the user is
1121 1129  allowed to change the limit. For example, this means that recursive snapshots
1122 1130  taken from the global zone are counted against each delegated dataset within
1123 1131  a zone. This feature must be enabled to be used
1124 1132  .Po see
1125 1133  .Xr zpool-features 5
1126 1134  .Pc .
1127 1135  .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1128 1136  Limits the amount of space consumed by the specified user. User space
1129 1137  consumption is identified by the
1130 1138  .Sy userspace@ Ns Em user
1131 1139  property.
1132 1140  .Pp
1133 1141  Enforcement of user quotas may be delayed by several seconds. This delay means
1134 1142  that a user might exceed their quota before the system notices that they are
1135 1143  over quota and begins to refuse additional writes with the
1136 1144  .Er EDQUOT
1137 1145  error message. See the
1138 1146  .Nm zfs Cm userspace
1139 1147  subcommand for more information.
1140 1148  .Pp
1141 1149  Unprivileged users can only access their own groups' space usage. The root
1142 1150  user, or a user who has been granted the
1143 1151  .Sy userquota
1144 1152  privilege with
1145 1153  .Nm zfs Cm allow ,
1146 1154  can get and set everyone's quota.
1147 1155  .Pp
1148 1156  This property is not available on volumes, on file systems before version 4, or
1149 1157  on pools before version 15. The
1150 1158  .Sy userquota@ Ns Em ...
1151 1159  properties are not displayed by
1152 1160  .Nm zfs Cm get Sy all .
1153 1161  The user's name must be appended after the
1154 1162  .Sy @
1155 1163  symbol, using one of the following forms:
1156 1164  .Bl -bullet
1157 1165  .It
1158 1166  .Em POSIX name
1159 1167  .Po for example,
1160 1168  .Sy joe
1161 1169  .Pc
1162 1170  .It
1163 1171  .Em POSIX numeric ID
1164 1172  .Po for example,
1165 1173  .Sy 789
1166 1174  .Pc
1167 1175  .It
1168 1176  .Em SID name
1169 1177  .Po for example,
1170 1178  .Sy joe.smith@mydomain
1171 1179  .Pc
1172 1180  .It
1173 1181  .Em SID numeric ID
1174 1182  .Po for example,
1175 1183  .Sy S-1-123-456-789
1176 1184  .Pc
1177 1185  .El
1178 1186  .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1179 1187  Limits the amount of space consumed by the specified group. Group space
1180 1188  consumption is identified by the
1181 1189  .Sy groupused@ Ns Em group
1182 1190  property.
1183 1191  .Pp
1184 1192  Unprivileged users can access only their own groups' space usage. The root
1185 1193  user, or a user who has been granted the
1186 1194  .Sy groupquota
1187 1195  privilege with
1188 1196  .Nm zfs Cm allow ,
1189 1197  can get and set all groups' quotas.
1190 1198  .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1191 1199  Controls whether this dataset can be modified. The default value is
1192 1200  .Sy off .
1193 1201  .Pp
1194 1202  This property can also be referred to by its shortened column name,
1195 1203  .Sy rdonly .
1196 1204  .It Sy recordsize Ns = Ns Em size
1197 1205  Specifies a suggested block size for files in the file system. This property is
1198 1206  designed solely for use with database workloads that access files in fixed-size
1199 1207  records. ZFS automatically tunes block sizes according to internal algorithms
1200 1208  optimized for typical access patterns.
1201 1209  .Pp
1202 1210  For databases that create very large files but access them in small random
1203 1211  chunks, these algorithms may be suboptimal. Specifying a
1204 1212  .Sy recordsize
1205 1213  greater than or equal to the record size of the database can result in
1206 1214  significant performance gains. Use of this property for general purpose file
1207 1215  systems is strongly discouraged, and may adversely affect performance.
1208 1216  .Pp
1209 1217  The size specified must be a power of two greater than or equal to 512 and less
1210 1218  than or equal to 128 Kbytes. If the
1211 1219  .Sy large_blocks
1212 1220  feature is enabled on the pool, the size may be up to 1 Mbyte. See
1213 1221  .Xr zpool-features 5
1214 1222  for details on ZFS feature flags.
1215 1223  .Pp
1216 1224  Changing the file system's
1217 1225  .Sy recordsize
1218 1226  affects only files created afterward; existing files are unaffected.
1219 1227  .Pp
1220 1228  This property can also be referred to by its shortened column name,
1221 1229  .Sy recsize .
1222 1230  .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1223 1231  Controls what types of metadata are stored redundantly. ZFS stores an extra copy
1224 1232  of metadata, so that if a single block is corrupted, the amount of user data
1225 1233  lost is limited. This extra copy is in addition to any redundancy provided at
1226 1234  the pool level
1227 1235  .Pq e.g. by mirroring or RAID-Z ,
1228 1236  and is in addition to an extra copy specified by the
1229 1237  .Sy copies
1230 1238  property
1231 1239  .Pq up to a total of 3 copies .
1232 1240  For example if the pool is mirrored,
1233 1241  .Sy copies Ns = Ns 2 ,
1234 1242  and
1235 1243  .Sy redundant_metadata Ns = Ns Sy most ,
1236 1244  then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1237 1245  metadata.
1238 1246  .Pp
1239 1247  When set to
1240 1248  .Sy all ,
1241 1249  ZFS stores an extra copy of all metadata. If a single on-disk block is corrupt,
1242 1250  at worst a single block of user data
1243 1251  .Po which is
1244 1252  .Sy recordsize
1245 1253  bytes long
1246 1254  .Pc
1247 1255  can be lost.
1248 1256  .Pp
1249 1257  When set to
1250 1258  .Sy most ,
1251 1259  ZFS stores an extra copy of most types of metadata. This can improve performance
1252 1260  of random writes, because less metadata must be written. In practice, at worst
1253 1261  about 100 blocks
1254 1262  .Po of
1255 1263  .Sy recordsize
1256 1264  bytes each
1257 1265  .Pc
1258 1266  of user data can be lost if a single on-disk block is corrupt. The exact
1259 1267  behavior of which metadata blocks are stored redundantly may change in future
1260 1268  releases.
1261 1269  .Pp
1262 1270  The default value is
1263 1271  .Sy all .
1264 1272  .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1265 1273  Limits the amount of space a dataset can consume. This property enforces a hard
1266 1274  limit on the amount of space used. This hard limit does not include space used
1267 1275  by descendents, including file systems and snapshots.
1268 1276  .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none
1269 1277  The minimum amount of space guaranteed to a dataset, not including its
1270 1278  descendents. When the amount of space used is below this value, the dataset is
1271 1279  treated as if it were taking up the amount of space specified by
1272 1280  .Sy refreservation .
1273 1281  The
1274 1282  .Sy refreservation
1275 1283  reservation is accounted for in the parent datasets' space used, and counts
1276 1284  against the parent datasets' quotas and reservations.
1277 1285  .Pp
1278 1286  If
1279 1287  .Sy refreservation
1280 1288  is set, a snapshot is only allowed if there is enough free pool space outside of
1281 1289  this reservation to accommodate the current number of
1282 1290  .Qq referenced
1283 1291  bytes in the dataset.
1284 1292  .Pp
1285 1293  This property can also be referred to by its shortened column name,
1286 1294  .Sy refreserv .
1287 1295  .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1288 1296  The minimum amount of space guaranteed to a dataset and its descendents. When
1289 1297  the amount of space used is below this value, the dataset is treated as if it
1290 1298  were taking up the amount of space specified by its reservation. Reservations
1291 1299  are accounted for in the parent datasets' space used, and count against the
1292 1300  parent datasets' quotas and reservations.
1293 1301  .Pp
1294 1302  This property can also be referred to by its shortened column name,
1295 1303  .Sy reserv .
1296 1304  .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1297 1305  Controls what is cached in the secondary cache
1298 1306  .Pq L2ARC .
1299 1307  If this property is set to
1300 1308  .Sy all ,
1301 1309  then both user data and metadata is cached. If this property is set to
1302 1310  .Sy none ,
1303 1311  then neither user data nor metadata is cached. If this property is set to
1304 1312  .Sy metadata ,
1305 1313  then only metadata is cached. The default value is
1306 1314  .Sy all .
1307 1315  .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1308 1316  Controls whether the setuid bit is respected for the file system. The default
1309 1317  value is
1310 1318  .Sy on .
1311 1319  .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1312 1320  Controls whether the file system is shared via SMB, and what options are to be
1313 1321  used. A file system with the
1314 1322  .Sy sharesmb
1315 1323  property set to
1316 1324  .Sy off
1317 1325  is managed through traditional tools such as
1318 1326  .Xr sharemgr 1M .
1319 1327  Otherwise, the file system is automatically shared and unshared with the
1320 1328  .Nm zfs Cm share
1321 1329  and
1322 1330  .Nm zfs Cm unshare
1323 1331  commands. If the property is set to
1324 1332  .Sy on ,
1325 1333  the
1326 1334  .Xr sharemgr 1M
1327 1335  command is invoked with no options. Otherwise, the
1328 1336  .Xr sharemgr 1M
1329 1337  command is invoked with options equivalent to the contents of this property.
1330 1338  .Pp
1331 1339  Because SMB shares requires a resource name, a unique resource name is
1332 1340  constructed from the dataset name. The constructed name is a copy of the dataset
1333 1341  name except that the characters in the dataset name, which would be illegal in
1334 1342  the resource name, are replaced with underscore
1335 1343  .Pq Sy _
1336 1344  characters. A pseudo property
1337 1345  .Qq name
1338 1346  is also supported that allows you to replace the data set name with a specified
1339 1347  name. The specified name is then used to replace the prefix dataset in the case
1340 1348  of inheritance. For example, if the dataset
1341 1349  .Em data/home/john
1342 1350  is set to
1343 1351  .Sy name Ns = Ns Sy john ,
1344 1352  then
1345 1353  .Em data/home/john
1346 1354  has a resource name of
1347 1355  .Sy john .
1348 1356  If a child dataset
1349 1357  .Em data/home/john/backups
1350 1358  is shared, it has a resource name of
1351 1359  .Sy john_backups .
1352 1360  .Pp
1353 1361  When SMB shares are created, the SMB share name appears as an entry in the
1354 1362  .Pa .zfs/shares
1355 1363  directory. You can use the
1356 1364  .Nm ls
1357 1365  or
1358 1366  .Nm chmod
1359 1367  command to display the share-level ACLs on the entries in this directory.
1360 1368  .Pp
1361 1369  When the
1362 1370  .Sy sharesmb
1363 1371  property is changed for a dataset, the dataset and any children inheriting the
1364 1372  property are re-shared with the new options, only if the property was previously
1365 1373  set to
1366 1374  .Sy off ,
1367 1375  or if they were shared before the property was changed. If the new property is
1368 1376  set to
1369 1377  .Sy off ,
1370 1378  the file systems are unshared.
1371 1379  .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1372 1380  Controls whether the file system is shared via NFS, and what options are to be
1373 1381  used. A file system with a
1374 1382  .Sy sharenfs
1375 1383  property of
1376 1384  .Sy off
1377 1385  is managed through traditional tools such as
1378 1386  .Xr share 1M ,
1379 1387  .Xr unshare 1M ,
1380 1388  and
1381 1389  .Xr dfstab 4 .
1382 1390  Otherwise, the file system is automatically shared and unshared with the
1383 1391  .Nm zfs Cm share
1384 1392  and
1385 1393  .Nm zfs Cm unshare
1386 1394  commands. If the property is set to
1387 1395  .Sy on ,
1388 1396  .Xr share 1M
1389 1397  command is invoked with no options. Otherwise, the
1390 1398  .Xr share 1M
1391 1399  command is invoked with options equivalent to the contents of this property.
1392 1400  .Pp
1393 1401  When the
1394 1402  .Sy sharenfs
1395 1403  property is changed for a dataset, the dataset and any children inheriting the
1396 1404  property are re-shared with the new options, only if the property was previously
1397 1405  .Sy off ,
1398 1406  or if they were shared before the property was changed. If the new property is
1399 1407  .Sy off ,
1400 1408  the file systems are unshared.
1401 1409  .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1402 1410  Provide a hint to ZFS about handling of synchronous requests in this dataset. If
1403 1411  .Sy logbias
1404 1412  is set to
1405 1413  .Sy latency
1406 1414  .Pq the default ,
1407 1415  ZFS will use pool log devices
1408 1416  .Pq if configured
1409 1417  to handle the requests at low latency. If
1410 1418  .Sy logbias
1411 1419  is set to
1412 1420  .Sy throughput ,
1413 1421  ZFS will not use configured pool log devices. ZFS will instead optimize
1414 1422  synchronous operations for global pool throughput and efficient use of
1415 1423  resources.
1416 1424  .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1417 1425  Controls whether the
1418 1426  .Pa .zfs
1419 1427  directory is hidden or visible in the root of the file system as discussed in
1420 1428  the
1421 1429  .Sx Snapshots
1422 1430  section. The default value is
1423 1431  .Sy hidden .
1424 1432  .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1425 1433  Controls the behavior of synchronous requests
1426 1434  .Pq e.g. fsync, O_DSYNC .
1427 1435  .Sy standard
1428 1436  is the
1429 1437  .Tn POSIX
1430 1438  specified behavior of ensuring all synchronous requests are written to stable
1431 1439  storage and all devices are flushed to ensure data is not cached by device
1432 1440  controllers
1433 1441  .Pq this is the default .
1434 1442  .Sy always
1435 1443  causes every file system transaction to be written and flushed before its
1436 1444  system call returns. This has a large performance penalty.
1437 1445  .Sy disabled
1438 1446  disables synchronous requests. File system transactions are only committed to
1439 1447  stable storage periodically. This option will give the highest performance.
1440 1448  However, it is very dangerous as ZFS would be ignoring the synchronous
1441 1449  transaction demands of applications such as databases or NFS. Administrators
1442 1450  should only use this option when the risks are understood.
1443 1451  .It Sy version Ns = Ns Em N Ns | Ns Sy current
1444 1452  The on-disk version of this file system, which is independent of the pool
1445 1453  version. This property can only be set to later supported versions. See the
1446 1454  .Nm zfs Cm upgrade
1447 1455  command.
1448 1456  .It Sy volsize Ns = Ns Em size
1449 1457  For volumes, specifies the logical size of the volume. By default, creating a
1450 1458  volume establishes a reservation of equal size. For storage pools with a version
1451 1459  number of 9 or higher, a
1452 1460  .Sy refreservation
1453 1461  is set instead. Any changes to
1454 1462  .Sy volsize
1455 1463  are reflected in an equivalent change to the reservation
1456 1464  .Po or
1457 1465  .Sy refreservation
1458 1466  .Pc .
1459 1467  The
1460 1468  .Sy volsize
1461 1469  can only be set to a multiple of
1462 1470  .Sy volblocksize ,
1463 1471  and cannot be zero.
1464 1472  .Pp
1465 1473  The reservation is kept equal to the volume's logical size to prevent unexpected
1466 1474  behavior for consumers. Without the reservation, the volume could run out of
1467 1475  space, resulting in undefined behavior or data corruption, depending on how the
1468 1476  volume is used. These effects can also occur when the volume size is changed
1469 1477  while it is in use
1470 1478  .Pq particularly when shrinking the size .
1471 1479  Extreme care should be used when adjusting the volume size.
1472 1480  .Pp
1473 1481  Though not recommended, a
1474 1482  .Qq sparse volume
1475 1483  .Po also known as
1476 1484  .Qq thin provisioning
1477 1485  .Pc
1478 1486  can be created by specifying the
1479 1487  .Fl s
1480 1488  option to the
1481 1489  .Nm zfs Cm create Fl V
1482 1490  command, or by changing the reservation after the volume has been created. A
1483 1491  .Qq sparse volume
1484 1492  is a volume where the reservation is less then the volume size. Consequently,
1485 1493  writes to a sparse volume can fail with
1486 1494  .Er ENOSPC
1487 1495  when the pool is low on space. For a sparse volume, changes to
1488 1496  .Sy volsize
1489 1497  are not reflected in the reservation.
1490 1498  .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1491 1499  Controls whether regular files should be scanned for viruses when a file is
1492 1500  opened and closed. In addition to enabling this property, the virus scan
1493 1501  service must also be enabled for virus scanning to occur. The default value is
1494 1502  .Sy off .
1495 1503  .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off
1496 1504  Controls whether extended attributes are enabled for this file system. The
1497 1505  default value is
1498 1506  .Sy on .
1499 1507  .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1500 1508  Controls whether the dataset is managed from a non-global zone. See the
1501 1509  .Sx Zones
1502 1510  section for more information. The default value is
1503 1511  .Sy off .
1504 1512  .El
1505 1513  .Pp
1506 1514  The following three properties cannot be changed after the file system is
1507 1515  created, and therefore, should be set when the file system is created. If the
1508 1516  properties are not set with the
1509 1517  .Nm zfs Cm create
1510 1518  or
1511 1519  .Nm zpool Cm create
1512 1520  commands, these properties are inherited from the parent dataset. If the parent
1513 1521  dataset lacks these properties due to having been created prior to these
1514 1522  features being supported, the new file system will have the default values for
1515 1523  these properties.
1516 1524  .Bl -tag -width ""
1517 1525  .It Xo
1518 1526  .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1519 1527  .Sy insensitive Ns | Ns Sy mixed
1520 1528  .Xc
1521 1529  Indicates whether the file name matching algorithm used by the file system
1522 1530  should be case-sensitive, case-insensitive, or allow a combination of both
1523 1531  styles of matching. The default value for the
1524 1532  .Sy casesensitivity
1525 1533  property is
1526 1534  .Sy sensitive .
1527 1535  Traditionally,
1528 1536  .Ux
1529 1537  and
1530 1538  .Tn POSIX
1531 1539  file systems have case-sensitive file names.
1532 1540  .Pp
1533 1541  The
1534 1542  .Sy mixed
1535 1543  value for the
1536 1544  .Sy casesensitivity
1537 1545  property indicates that the file system can support requests for both
1538 1546  case-sensitive and case-insensitive matching behavior. Currently,
1539 1547  case-insensitive matching behavior on a file system that supports mixed behavior
1540 1548  is limited to the SMB server product. For more information about the
1541 1549  .Sy mixed
1542 1550  value behavior, see the "ZFS Administration Guide".
1543 1551  .It Xo
1544 1552  .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1545 1553  .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1546 1554  .Xc
1547 1555  Indicates whether the file system should perform a
1548 1556  .Sy unicode
1549 1557  normalization of file names whenever two file names are compared, and which
1550 1558  normalization algorithm should be used. File names are always stored unmodified,
1551 1559  names are normalized as part of any comparison process. If this property is set
1552 1560  to a legal value other than
1553 1561  .Sy none ,
1554 1562  and the
1555 1563  .Sy utf8only
1556 1564  property was left unspecified, the
1557 1565  .Sy utf8only
1558 1566  property is automatically set to
1559 1567  .Sy on .
1560 1568  The default value of the
1561 1569  .Sy normalization
1562 1570  property is
1563 1571  .Sy none .
1564 1572  This property cannot be changed after the file system is created.
1565 1573  .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1566 1574  Indicates whether the file system should reject file names that include
1567 1575  characters that are not present in the
1568 1576  .Sy UTF-8
1569 1577  character code set. If this property is explicitly set to
1570 1578  .Sy off ,
1571 1579  the normalization property must either not be explicitly set or be set to
1572 1580  .Sy none .
1573 1581  The default value for the
1574 1582  .Sy utf8only
1575 1583  property is
1576 1584  .Sy off .
1577 1585  This property cannot be changed after the file system is created.
1578 1586  .El
1579 1587  .Pp
1580 1588  The
1581 1589  .Sy casesensitivity ,
1582 1590  .Sy normalization ,
1583 1591  and
1584 1592  .Sy utf8only
1585 1593  properties are also new permissions that can be assigned to non-privileged users
1586 1594  by using the ZFS delegated administration feature.
1587 1595  .Ss "Temporary Mount Point Properties"
1588 1596  When a file system is mounted, either through
1589 1597  .Xr mount 1M
1590 1598  for legacy mounts or the
1591 1599  .Nm zfs Cm mount
1592 1600  command for normal file systems, its mount options are set according to its
1593 1601  properties. The correlation between properties and mount options is as follows:
1594 1602  .Bd -literal
1595 1603      PROPERTY                MOUNT OPTION
1596 1604      devices                 devices/nodevices
1597 1605      exec                    exec/noexec
1598 1606      readonly                ro/rw
1599 1607      setuid                  setuid/nosetuid
1600 1608      xattr                   xattr/noxattr
1601 1609  .Ed
1602 1610  .Pp
1603 1611  In addition, these options can be set on a per-mount basis using the
1604 1612  .Fl o
1605 1613  option, without affecting the property that is stored on disk. The values
1606 1614  specified on the command line override the values stored in the dataset. The
1607 1615  .Sy nosuid
1608 1616  option is an alias for
1609 1617  .Sy nodevices Ns , Ns Sy nosetuid .
1610 1618  These properties are reported as
1611 1619  .Qq temporary
1612 1620  by the
1613 1621  .Nm zfs Cm get
1614 1622  command. If the properties are changed while the dataset is mounted, the new
1615 1623  setting overrides any temporary settings.
1616 1624  .Ss "User Properties"
1617 1625  In addition to the standard native properties, ZFS supports arbitrary user
1618 1626  properties. User properties have no effect on ZFS behavior, but applications or
1619 1627  administrators can use them to annotate datasets
1620 1628  .Pq file systems, volumes, and snapshots .
1621 1629  .Pp
1622 1630  User property names must contain a colon
1623 1631  .No Po Ns Sy \&:  Ns Pc
1624 1632  character to distinguish them from native properties. They may contain lowercase
1625 1633  letters, numbers, and the following punctuation characters: colon
1626 1634  .Pq Qq Sy \&: ,
1627 1635  dash
1628 1636  .Pq Qq Sy - ,
1629 1637  period
1630 1638  .Pq Qq Sy \&. ,
1631 1639  and underscore
1632 1640  .Pq Qq Sy _ .
1633 1641  The expected convention is that the property name is divided into two portions
1634 1642  such as
1635 1643  .Em module Ns : Ns Em property ,
1636 1644  but this namespace is not enforced by ZFS.
1637 1645  User property names can be at most 256 characters, and cannot begin with a dash
1638 1646  .Pq Qq Sy - .
1639 1647  .Pp
1640 1648  When making programmatic use of user properties, it is strongly suggested to use
1641 1649  a reversed
1642 1650  .Sy DNS
1643 1651  domain name for the
1644 1652  .Em module
1645 1653  component of property names to reduce the chance that two
1646 1654  independently-developed packages use the same property name for different
1647 1655  purposes.
1648 1656  .Pp
1649 1657  The values of user properties are arbitrary strings, are always inherited, and
1650 1658  are never validated. All of the commands that operate on properties
1651 1659  .Po Nm zfs Cm list ,
1652 1660  .Nm zfs Cm get ,
1653 1661  .Nm zfs Cm set ,
1654 1662  and so forth
1655 1663  .Pc
1656 1664  can be used to manipulate both native properties and user properties. Use the
1657 1665  .Nm zfs Cm inherit
1658 1666  command to clear a user property . If the property is not defined in any parent
1659 1667  dataset, it is removed entirely. Property values are limited to 1024
1660 1668  characters.
1661 1669  .Ss ZFS Volumes as Swap or Dump Devices
1662 1670  During an initial installation a swap device and dump device are created on ZFS
1663 1671  volumes in the ZFS root pool. By default, the swap area size is based on 1/2 the
1664 1672  size of physical memory up to 2 Gbytes. The size of the dump device depends on
1665 1673  the kernel's requirements at installation time. Separate ZFS volumes must be
1666 1674  used for the swap area and dump devices. Do not swap to a file on a ZFS file
1667 1675  system. A ZFS swap file configuration is not supported.
1668 1676  .Pp
1669 1677  If you need to change your swap area or dump device after the system is
1670 1678  installed or upgraded, use the
1671 1679  .Xr swap 1M
1672 1680  and
1673 1681  .Xr dumpadm 1M
1674 1682  commands.
1675 1683  .Sh SUBCOMMANDS
1676 1684  All subcommands that modify state are logged persistently to the pool in their
1677 1685  original form.
1678 1686  .Bl -tag -width ""
1679 1687  .It Nm Fl \?
1680 1688  Displays a help message.
1681 1689  .It Xo
1682 1690  .Nm
1683 1691  .Cm create
1684 1692  .Op Fl p
1685 1693  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1686 1694  .Ar filesystem
1687 1695  .Xc
1688 1696  Creates a new ZFS file system. The file system is automatically mounted
1689 1697  according to the
1690 1698  .Sy mountpoint
1691 1699  property inherited from the parent.
1692 1700  .Bl -tag -width "-o"
1693 1701  .It Fl o Ar property Ns = Ns Ar value
1694 1702  Sets the specified property as if the command
1695 1703  .Nm zfs Cm set Ar property Ns = Ns Ar value
1696 1704  was invoked at the same time the dataset was created. Any editable ZFS property
1697 1705  can also be set at creation time. Multiple
1698 1706  .Fl o
1699 1707  options can be specified. An error results if the same property is specified in
1700 1708  multiple
1701 1709  .Fl o
1702 1710  options.
1703 1711  .It Fl p
1704 1712  Creates all the non-existing parent datasets. Datasets created in this manner
1705 1713  are automatically mounted according to the
1706 1714  .Sy mountpoint
1707 1715  property inherited from their parent. Any property specified on the command line
1708 1716  using the
1709 1717  .Fl o
1710 1718  option is ignored. If the target filesystem already exists, the operation
1711 1719  completes successfully.
1712 1720  .El
1713 1721  .It Xo
1714 1722  .Nm
1715 1723  .Cm create
1716 1724  .Op Fl ps
1717 1725  .Op Fl b Ar blocksize
1718 1726  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1719 1727  .Fl V Ar size Ar volume
1720 1728  .Xc
1721 1729  Creates a volume of the given size. The volume is exported as a block device in
1722 1730  .Pa /dev/zvol/{dsk,rdsk}/path ,
1723 1731  where
1724 1732  .Em path
1725 1733  is the name of the volume in the ZFS namespace. The size represents the logical
1726 1734  size as exported by the device. By default, a reservation of equal size is
1727 1735  created.
1728 1736  .Pp
1729 1737  .Ar size
1730 1738  is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
1731 1739  has an integral number of blocks regardless of
1732 1740  .Sy blocksize .
1733 1741  .Bl -tag -width "-b"
1734 1742  .It Fl b Ar blocksize
1735 1743  Equivalent to
1736 1744  .Fl o Sy volblocksize Ns = Ns Ar blocksize .
1737 1745  If this option is specified in conjunction with
1738 1746  .Fl o Sy volblocksize ,
1739 1747  the resulting behavior is undefined.
1740 1748  .It Fl o Ar property Ns = Ns Ar value
1741 1749  Sets the specified property as if the
1742 1750  .Nm zfs Cm set Ar property Ns = Ns Ar value
1743 1751  command was invoked at the same time the dataset was created. Any editable ZFS
1744 1752  property can also be set at creation time. Multiple
1745 1753  .Fl o
1746 1754  options can be specified. An error results if the same property is specified in
1747 1755  multiple
1748 1756  .Fl o
1749 1757  options.
1750 1758  .It Fl p
1751 1759  Creates all the non-existing parent datasets. Datasets created in this manner
1752 1760  are automatically mounted according to the
1753 1761  .Sy mountpoint
1754 1762  property inherited from their parent. Any property specified on the command line
1755 1763  using the
1756 1764  .Fl o
1757 1765  option is ignored. If the target filesystem already exists, the operation
1758 1766  completes successfully.
1759 1767  .It Fl s
1760 1768  Creates a sparse volume with no reservation. See
1761 1769  .Sy volsize
1762 1770  in the
1763 1771  .Sx Native Properties
1764 1772  section for more information about sparse volumes.
1765 1773  .El
1766 1774  .It Xo
1767 1775  .Nm
1768 1776  .Cm destroy
1769 1777  .Op Fl Rfnprv
1770 1778  .Ar filesystem Ns | Ns Ar volume
1771 1779  .Xc
1772 1780  Destroys the given dataset. By default, the command unshares any file systems
1773 1781  that are currently shared, unmounts any file systems that are currently
1774 1782  mounted, and refuses to destroy a dataset that has active dependents
1775 1783  .Pq children or clones .
1776 1784  .Bl -tag -width "-R"
1777 1785  .It Fl R
1778 1786  Recursively destroy all dependents, including cloned file systems outside the
1779 1787  target hierarchy.
1780 1788  .It Fl f
1781 1789  Force an unmount of any file systems using the
1782 1790  .Nm unmount Fl f
1783 1791  command. This option has no effect on non-file systems or unmounted file
1784 1792  systems.
1785 1793  .It Fl n
1786 1794  Do a dry-run
1787 1795  .Pq Qq No-op
1788 1796  deletion. No data will be deleted. This is useful in conjunction with the
1789 1797  .Fl v
1790 1798  or
1791 1799  .Fl p
1792 1800  flags to determine what data would be deleted.
1793 1801  .It Fl p
1794 1802  Print machine-parsable verbose information about the deleted data.
1795 1803  .It Fl r
1796 1804  Recursively destroy all children.
1797 1805  .It Fl v
1798 1806  Print verbose information about the deleted data.
1799 1807  .El
1800 1808  .Pp
1801 1809  Extreme care should be taken when applying either the
1802 1810  .Fl r
1803 1811  or the
1804 1812  .Fl R
1805 1813  options, as they can destroy large portions of a pool and cause unexpected
1806 1814  behavior for mounted file systems in use.
1807 1815  .It Xo
1808 1816  .Nm
1809 1817  .Cm destroy
1810 1818  .Op Fl Rdnprv
1811 1819  .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
1812 1820  .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
1813 1821  .Xc
1814 1822  The given snapshots are destroyed immediately if and only if the
1815 1823  .Nm zfs Cm destroy
1816 1824  command without the
1817 1825  .Fl d
1818 1826  option would have destroyed it. Such immediate destruction would occur, for
1819 1827  example, if the snapshot had no clones and the user-initiated reference count
1820 1828  were zero.
1821 1829  .Pp
1822 1830  If a snapshot does not qualify for immediate destruction, it is marked for
1823 1831  deferred deletion. In this state, it exists as a usable, visible snapshot until
1824 1832  both of the preconditions listed above are met, at which point it is destroyed.
1825 1833  .Pp
1826 1834  An inclusive range of snapshots may be specified by separating the first and
1827 1835  last snapshots with a percent sign. The first and/or last snapshots may be left
1828 1836  blank, in which case the filesystem's oldest or newest snapshot will be implied.
1829 1837  .Pp
1830 1838  Multiple snapshots
1831 1839  .Pq or ranges of snapshots
1832 1840  of the same filesystem or volume may be specified in a comma-separated list of
1833 1841  snapshots. Only the snapshot's short name
1834 1842  .Po the part after the
1835 1843  .Sy @
1836 1844  .Pc
1837 1845  should be specified when using a range or comma-separated list to identify
1838 1846  multiple snapshots.
1839 1847  .Bl -tag -width "-R"
1840 1848  .It Fl R
1841 1849  Recursively destroy all clones of these snapshots, including the clones,
1842 1850  snapshots, and children. If this flag is specified, the
1843 1851  .Fl d
1844 1852  flag will have no effect.
1845 1853  .It Fl d
1846 1854  Defer snapshot deletion.
1847 1855  .It Fl n
1848 1856  Do a dry-run
1849 1857  .Pq Qq No-op
1850 1858  deletion. No data will be deleted. This is
1851 1859  useful in conjunction with the
1852 1860  .Fl p
1853 1861  or
1854 1862  .Fl v
1855 1863  flags to determine what data would be deleted.
1856 1864  .It Fl p
1857 1865  Print machine-parsable verbose information about the deleted data.
1858 1866  .It Fl r
1859 1867  Destroy
1860 1868  .Pq or mark for deferred deletion
1861 1869  all snapshots with this name in descendent file systems.
1862 1870  .It Fl v
1863 1871  Print verbose information about the deleted data.
1864 1872  .Pp
1865 1873  Extreme care should be taken when applying either the
1866 1874  .Fl r
1867 1875  or the
1868 1876  .Fl R
1869 1877  options, as they can destroy large portions of a pool and cause unexpected
1870 1878  behavior for mounted file systems in use.
1871 1879  .El
1872 1880  .It Xo
1873 1881  .Nm
1874 1882  .Cm destroy
1875 1883  .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
1876 1884  .Xc
1877 1885  The given bookmark is destroyed.
1878 1886  .It Xo
1879 1887  .Nm
1880 1888  .Cm snapshot
1881 1889  .Op Fl r
1882 1890  .Oo Fl o Ar property Ns = Ns value Oc Ns ...
1883 1891  .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
1884 1892  .Xc
1885 1893  Creates snapshots with the given names. All previous modifications by successful
1886 1894  system calls to the file system are part of the snapshots. Snapshots are taken
1887 1895  atomically, so that all snapshots correspond to the same moment in time. See the
1888 1896  .Sx Snapshots
1889 1897  section for details.
1890 1898  .Bl -tag -width "-o"
1891 1899  .It Fl o Ar property Ns = Ns Ar value
1892 1900  Sets the specified property; see
1893 1901  .Nm zfs Cm create
1894 1902  for details.
1895 1903  .It Fl r
1896 1904  Recursively create snapshots of all descendent datasets
1897 1905  .El
1898 1906  .It Xo
1899 1907  .Nm
1900 1908  .Cm rollback
1901 1909  .Op Fl Rfr
1902 1910  .Ar snapshot
1903 1911  .Xc
1904 1912  Roll back the given dataset to a previous snapshot. When a dataset is rolled
1905 1913  back, all data that has changed since the snapshot is discarded, and the dataset
1906 1914  reverts to the state at the time of the snapshot. By default, the command
1907 1915  refuses to roll back to a snapshot other than the most recent one. In order to
1908 1916  do so, all intermediate snapshots and bookmarks must be destroyed by specifying
1909 1917  the
1910 1918  .Fl r
1911 1919  option.
1912 1920  .Pp
1913 1921  The
1914 1922  .Fl rR
1915 1923  options do not recursively destroy the child snapshots of a recursive snapshot.
1916 1924  Only direct snapshots of the specified filesystem are destroyed by either of
1917 1925  these options. To completely roll back a recursive snapshot, you must rollback
1918 1926  the individual child snapshots.
1919 1927  .Bl -tag -width "-R"
1920 1928  .It Fl R
1921 1929  Destroy any more recent snapshots and bookmarks, as well as any clones of those
1922 1930  snapshots.
1923 1931  .It Fl f
1924 1932  Used with the
1925 1933  .Fl R
1926 1934  option to force an unmount of any clone file systems that are to be destroyed.
1927 1935  .It Fl r
1928 1936  Destroy any snapshots and bookmarks more recent than the one specified.
1929 1937  .El
1930 1938  .It Xo
1931 1939  .Nm
1932 1940  .Cm clone
1933 1941  .Op Fl p
1934 1942  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1935 1943  .Ar snapshot Ar filesystem Ns | Ns Ar volume
1936 1944  .Xc
1937 1945  Creates a clone of the given snapshot. See the
1938 1946  .Sx Clones
1939 1947  section for details. The target dataset can be located anywhere in the ZFS
1940 1948  hierarchy, and is created as the same type as the original.
1941 1949  .Bl -tag -width "-o"
1942 1950  .It Fl o Ar property Ns = Ns Ar value
1943 1951  Sets the specified property; see
1944 1952  .Nm zfs Cm create
1945 1953  for details.
1946 1954  .It Fl p
1947 1955  Creates all the non-existing parent datasets. Datasets created in this manner
1948 1956  are automatically mounted according to the
1949 1957  .Sy mountpoint
1950 1958  property inherited from their parent. If the target filesystem or volume already
1951 1959  exists, the operation completes successfully.
1952 1960  .El
1953 1961  .It Xo
1954 1962  .Nm
1955 1963  .Cm promote
1956 1964  .Ar clone-filesystem
1957 1965  .Xc
1958 1966  Promotes a clone file system to no longer be dependent on its
1959 1967  .Qq origin
1960 1968  snapshot. This makes it possible to destroy the file system that the clone was
1961 1969  created from. The clone parent-child dependency relationship is reversed, so
1962 1970  that the origin file system becomes a clone of the specified file system.
1963 1971  .Pp
1964 1972  The snapshot that was cloned, and any snapshots previous to this snapshot, are
1965 1973  now owned by the promoted clone. The space they use moves from the origin file
1966 1974  system to the promoted clone, so enough space must be available to accommodate
1967 1975  these snapshots. No new space is consumed by this operation, but the space
1968 1976  accounting is adjusted. The promoted clone must not have any conflicting
1969 1977  snapshot names of its own. The
1970 1978  .Cm rename
1971 1979  subcommand can be used to rename any conflicting snapshots.
1972 1980  .It Xo
1973 1981  .Nm
1974 1982  .Cm rename
1975 1983  .Op Fl f
1976 1984  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1977 1985  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
1978 1986  .br
1979 1987  .Nm
1980 1988  .Cm rename
1981 1989  .Op Fl fp
1982 1990  .Ar filesystem Ns | Ns Ar volume
1983 1991  .Ar filesystem Ns | Ns Ar volume
1984 1992  .Xc
1985 1993  Renames the given dataset. The new target can be located anywhere in the ZFS
1986 1994  hierarchy, with the exception of snapshots. Snapshots can only be renamed within
1987 1995  the parent file system or volume. When renaming a snapshot, the parent file
1988 1996  system of the snapshot does not need to be specified as part of the second
1989 1997  argument. Renamed file systems can inherit new mount points, in which case they
1990 1998  are unmounted and remounted at the new mount point.
1991 1999  .Bl -tag -width "-a"
1992 2000  .It Fl f
1993 2001  Force unmount any filesystems that need to be unmounted in the process.
1994 2002  .It Fl p
1995 2003  Creates all the nonexistent parent datasets. Datasets created in this manner are
1996 2004  automatically mounted according to the
1997 2005  .Sy mountpoint
1998 2006  property inherited from their parent.
1999 2007  .El
2000 2008  .It Xo
2001 2009  .Nm
2002 2010  .Cm rename
2003 2011  .Fl r
2004 2012  .Ar snapshot Ar snapshot
2005 2013  .Xc
2006 2014  Recursively rename the snapshots of all descendent datasets. Snapshots are the
2007 2015  only dataset that can be renamed recursively.
2008 2016  .It Xo
2009 2017  .Nm
2010 2018  .Cm list
2011 2019  .Op Fl r Ns | Ns Fl d Ar depth
2012 2020  .Op Fl Hp
2013 2021  .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2014 2022  .Oo Fl s Ar property Oc Ns ...
2015 2023  .Oo Fl S Ar property Oc Ns ...
2016 2024  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2017 2025  .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2018 2026  .Xc
2019 2027  Lists the property information for the given datasets in tabular form. If
2020 2028  specified, you can list property information by the absolute pathname or the
2021 2029  relative pathname. By default, all file systems and volumes are displayed.
2022 2030  Snapshots are displayed if the
2023 2031  .Sy listsnaps
2024 2032  property is
2025 2033  .Sy on
2026 2034  .Po the default is
2027 2035  .Sy off
2028 2036  .Pc .
2029 2037  The following fields are displayed,
2030 2038  .Sy name Ns , Ns Sy used Ns , Ns Sy available Ns , Ns Sy referenced Ns , Ns
2031 2039  .Sy mountpoint .
2032 2040  .Bl -tag -width "-H"
2033 2041  .It Fl H
2034 2042  Used for scripting mode. Do not print headers and separate fields by a single
2035 2043  tab instead of arbitrary white space.
2036 2044  .It Fl S Ar property
2037 2045  Same as the
2038 2046  .Fl s
2039 2047  option, but sorts by property in descending order.
2040 2048  .It Fl d Ar depth
2041 2049  Recursively display any children of the dataset, limiting the recursion to
2042 2050  .It Fl o Ar property
2043 2051  A comma-separated list of properties to display. The property must be:
2044 2052  .Bl -bullet
2045 2053  .It
2046 2054  One of the properties described in the
2047 2055  .Sx Native Properties
2048 2056  section
2049 2057  .It
2050 2058  A user property
2051 2059  .It
2052 2060  The value
2053 2061  .Sy name
2054 2062  to display the dataset name
2055 2063  .It
2056 2064  The value
2057 2065  .Sy space
2058 2066  to display space usage properties on file systems and volumes. This is a
2059 2067  shortcut for specifying
2060 2068  .Fl o Sy name Ns , Ns Sy avail Ns , Ns Sy used Ns , Ns Sy usedsnap Ns , Ns
2061 2069  .Sy usedds Ns , Ns Sy usedrefreserv Ns , Ns Sy usedchild Fl t
2062 2070  .Sy filesystem Ns , Ns Sy volume
2063 2071  syntax.
2064 2072  .El
2065 2073  .It Fl p
2066 2074  Display numbers in parsable
2067 2075  .Pq exact
2068 2076  values.
2069 2077  .It Fl r
2070 2078  Recursively display any children of the dataset on the command line.
2071 2079  .Ar depth .
2072 2080  A depth of
2073 2081  .Sy 1
2074 2082  will display only the dataset and its direct children.
2075 2083  .It Fl s Ar property
2076 2084  A property for sorting the output by column in ascending order based on the
2077 2085  value of the property. The property must be one of the properties described in
2078 2086  the
2079 2087  .Sx Properties
2080 2088  section, or the special value
2081 2089  .Sy name
2082 2090  to sort by the dataset name. Multiple properties can be specified at one time
2083 2091  using multiple
2084 2092  .Fl s
2085 2093  property options. Multiple
2086 2094  .Fl s
2087 2095  options are evaluated from left to right in decreasing order of importance. The
2088 2096  following is a list of sorting criteria:
2089 2097  .Bl -bullet
2090 2098  .It
2091 2099  Numeric types sort in numeric order.
2092 2100  .It
2093 2101  String types sort in alphabetical order.
2094 2102  .It
2095 2103  Types inappropriate for a row sort that row to the literal bottom, regardless of
2096 2104  the specified ordering.
2097 2105  .El
2098 2106  .Pp
2099 2107  If no sorting options are specified the existing behavior of
2100 2108  .Nm zfs Cm list
2101 2109  is preserved.
2102 2110  .It Fl t Ar type
2103 2111  A comma-separated list of types to display, where
2104 2112  .Ar type
2105 2113  is one of
2106 2114  .Sy filesystem ,
2107 2115  .Sy snapshot ,
2108 2116  .Sy volume ,
2109 2117  .Sy bookmark ,
2110 2118  or
2111 2119  .Sy all .
2112 2120  For example, specifying
2113 2121  .Fl t Sy snapshot
2114 2122  displays only snapshots.
2115 2123  .El
2116 2124  .It Xo
2117 2125  .Nm
2118 2126  .Cm set
2119 2127  .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2120 2128  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2121 2129  .Xc
2122 2130  Sets the property or list of properties to the given value(s) for each dataset.
2123 2131  Only some properties can be edited. See the
2124 2132  .Sx Properties
2125 2133  section for more information on what properties can be set and acceptable
2126 2134  values. Numeric values can be specified as exact values, or in a human-readable
2127 2135  form with a suffix of
2128 2136  .Sy B , K , M , G , T , P , E , Z
2129 2137  .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2130 2138  or zettabytes, respectively
2131 2139  .Pc .
2132 2140  User properties can be set on snapshots. For more information, see the
2133 2141  .Sx User Properties
2134 2142  section.
2135 2143  .It Xo
2136 2144  .Nm
2137 2145  .Cm get
2138 2146  .Op Fl r Ns | Ns Fl d Ar depth
2139 2147  .Op Fl Hp
2140 2148  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2141 2149  .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2142 2150  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2143 2151  .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2144 2152  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2145 2153  .Xc
2146 2154  Displays properties for the given datasets. If no datasets are specified, then
2147 2155  the command displays properties for all datasets on the system. For each
2148 2156  property, the following columns are displayed:
2149 2157  .Bd -literal
2150 2158      name      Dataset name
2151 2159      property  Property name
2152 2160      value     Property value
2153 2161      source    Property source. Can either be local, default,
2154 2162                temporary, inherited, or none (-).
2155 2163  .Ed
2156 2164  .Pp
2157 2165  All columns are displayed by default, though this can be controlled by using the
2158 2166  .Fl o
2159 2167  option. This command takes a comma-separated list of properties as described in
2160 2168  the
2161 2169  .Sx Native Properties
2162 2170  and
2163 2171  .Sx User Properties
2164 2172  sections.
2165 2173  .Pp
2166 2174  The special value
2167 2175  .Sy all
2168 2176  can be used to display all properties that apply to the given dataset's type
2169 2177  .Pq filesystem, volume, snapshot, or bookmark .
2170 2178  .Bl -tag -width "-H"
2171 2179  .It Fl H
2172 2180  Display output in a form more easily parsed by scripts. Any headers are omitted,
2173 2181  and fields are explicitly separated by a single tab instead of an arbitrary
2174 2182  amount of space.
2175 2183  .It Fl d Ar depth
2176 2184  Recursively display any children of the dataset, limiting the recursion to
2177 2185  .Ar depth .
2178 2186  A depth of
2179 2187  .Sy 1
2180 2188  will display only the dataset and its direct children.
2181 2189  .It Fl o Ar field
2182 2190  A comma-separated list of columns to display.
2183 2191  .Sy name Ns , Ns Sy property Ns , Ns Sy value Ns , Ns Sy source
2184 2192  is the default value.
2185 2193  .It Fl p
2186 2194  Display numbers in parsable
2187 2195  .Pq exact
2188 2196  values.
2189 2197  .It Fl r
2190 2198  Recursively display properties for any children.
2191 2199  .It Fl s Ar source
2192 2200  A comma-separated list of sources to display. Those properties coming from a
2193 2201  source other than those in this list are ignored. Each source must be one of the
2194 2202  following:
2195 2203  .Sy local ,
2196 2204  .Sy default ,
2197 2205  .Sy inherited ,
2198 2206  .Sy temporary ,
2199 2207  and
2200 2208  .Sy none .
2201 2209  The default value is all sources.
2202 2210  .It Fl t Ar type
2203 2211  A comma-separated list of types to display, where
2204 2212  .Ar type
2205 2213  is one of
2206 2214  .Sy filesystem ,
2207 2215  .Sy snapshot ,
2208 2216  .Sy volume ,
2209 2217  .Sy bookmark ,
2210 2218  or
2211 2219  .Sy all .
2212 2220  .El
2213 2221  .It Xo
2214 2222  .Nm
2215 2223  .Cm inherit
2216 2224  .Op Fl rS
2217 2225  .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2218 2226  .Xc
2219 2227  Clears the specified property, causing it to be inherited from an ancestor,
2220 2228  restored to default if no ancestor has the property set, or with the
2221 2229  .Fl S
2222 2230  option reverted to the received value if one exists. See the
2223 2231  .Sx Properties
2224 2232  section for a listing of default values, and details on which properties can be
2225 2233  inherited.
2226 2234  .Bl -tag -width "-r"
2227 2235  .It Fl r
2228 2236  Recursively inherit the given property for all children.
2229 2237  .It Fl S
2230 2238  Revert the property to the received value if one exists; otherwise operate as
2231 2239  if the
2232 2240  .Fl S
2233 2241  option was not specified.
2234 2242  .El
2235 2243  .It Xo
2236 2244  .Nm
2237 2245  .Cm upgrade
2238 2246  .Xc
2239 2247  Displays a list of file systems that are not the most recent version.
2240 2248  .It Xo
2241 2249  .Nm
2242 2250  .Cm upgrade
2243 2251  .Fl v
2244 2252  .Xc
2245 2253  Displays a list of currently supported file system versions.
2246 2254  .It Xo
2247 2255  .Nm
2248 2256  .Cm upgrade
2249 2257  .Op Fl r
2250 2258  .Op Fl V Ar version
2251 2259  .Fl a | Ar filesystem
2252 2260  .Xc
2253 2261  Upgrades file systems to a new on-disk version. Once this is done, the file
2254 2262  systems will no longer be accessible on systems running older versions of the
2255 2263  software.
2256 2264  .Nm zfs Cm send
2257 2265  streams generated from new snapshots of these file systems cannot be accessed on
2258 2266  systems running older versions of the software.
2259 2267  .Pp
2260 2268  In general, the file system version is independent of the pool version. See
2261 2269  .Xr zpool 1M
2262 2270  for information on the
2263 2271  .Nm zpool Cm upgrade
2264 2272  command.
2265 2273  .Pp
2266 2274  In some cases, the file system version and the pool version are interrelated and
2267 2275  the pool version must be upgraded before the file system version can be upgraded.
2268 2276  .Bl -tag -width "-V"
2269 2277  .It Fl V Ar version
2270 2278  Upgrade to the specified
2271 2279  .Ar version .
2272 2280  If the
2273 2281  .Fl V
2274 2282  flag is not specified, this command upgrades to the most recent version. This
2275 2283  option can only be used to increase the version number, and only up to the most
2276 2284  recent version supported by this software.
2277 2285  .It Fl a
2278 2286  Upgrade all file systems on all imported pools.
2279 2287  .It Ar filesystem
2280 2288  Upgrade the specified file system.
2281 2289  .It Fl r
2282 2290  Upgrade the specified file system and all descendent file systems.
2283 2291  .El
2284 2292  .It Xo
2285 2293  .Nm
2286 2294  .Cm userspace
2287 2295  .Op Fl Hinp
2288 2296  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2289 2297  .Oo Fl s Ar field Oc Ns ...
2290 2298  .Oo Fl S Ar field Oc Ns ...
2291 2299  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2292 2300  .Ar filesystem Ns | Ns Ar snapshot
2293 2301  .Xc
2294 2302  Displays space consumed by, and quotas on, each user in the specified filesystem
2295 2303  or snapshot. This corresponds to the
2296 2304  .Sy userused@ Ns Em user
2297 2305  and
2298 2306  .Sy userquota@ Ns Em user
2299 2307  properties.
2300 2308  .Bl -tag -width "-H"
2301 2309  .It Fl H
2302 2310  Do not print headers, use tab-delimited output.
2303 2311  .It Fl S Ar field
2304 2312  Sort by this field in reverse order. See
2305 2313  .Fl s .
2306 2314  .It Fl i
2307 2315  Translate SID to POSIX ID. The POSIX ID may be ephemeral if no mapping exists.
2308 2316  Normal POSIX interfaces
2309 2317  .Po for example,
2310 2318  .Xr stat 2 ,
2311 2319  .Nm ls Fl l
2312 2320  .Pc
2313 2321  perform this translation, so the
2314 2322  .Fl i
2315 2323  option allows the output from
2316 2324  .Nm zfs Cm userspace
2317 2325  to be compared directly with those utilities. However,
2318 2326  .Fl i
2319 2327  may lead to confusion if some files were created by an SMB user before a
2320 2328  SMB-to-POSIX name mapping was established. In such a case, some files will be
2321 2329  owned by the SMB entity and some by the POSIX entity. However, the
2322 2330  .Fl i
2323 2331  option will report that the POSIX entity has the total usage and quota for both.
2324 2332  .It Fl n
2325 2333  Print numeric ID instead of user/group name.
2326 2334  .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2327 2335  Display only the specified fields from the following set:
2328 2336  .Sy type ,
2329 2337  .Sy name ,
2330 2338  .Sy used ,
2331 2339  .Sy quota .
2332 2340  The default is to display all fields.
2333 2341  .It Fl p
2334 2342  Use exact
2335 2343  .Pq parsable
2336 2344  numeric output.
2337 2345  .It Fl s Ar field
2338 2346  Sort output by this field. The
2339 2347  .Fl s
2340 2348  and
2341 2349  .Fl S
2342 2350  flags may be specified multiple times to sort first by one field, then by
2343 2351  another. The default is
2344 2352  .Fl s Sy type Fl s Sy name .
2345 2353  .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2346 2354  Print only the specified types from the following set:
2347 2355  .Sy all ,
2348 2356  .Sy posixuser ,
2349 2357  .Sy smbuser ,
2350 2358  .Sy posixgroup ,
2351 2359  .Sy smbgroup .
2352 2360  The default is
2353 2361  .Fl t Sy posixuser Ns , Ns Sy smbuser .
2354 2362  The default can be changed to include group types.
2355 2363  .El
2356 2364  .It Xo
2357 2365  .Nm
2358 2366  .Cm groupspace
2359 2367  .Op Fl Hinp
2360 2368  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2361 2369  .Oo Fl s Ar field Oc Ns ...
2362 2370  .Oo Fl S Ar field Oc Ns ...
2363 2371  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2364 2372  .Ar filesystem Ns | Ns Ar snapshot
2365 2373  .Xc
2366 2374  Displays space consumed by, and quotas on, each group in the specified
2367 2375  filesystem or snapshot. This subcommand is identical to
2368 2376  .Nm zfs Cm userspace ,
2369 2377  except that the default types to display are
2370 2378  .Fl t Sy posixgroup Ns , Ns Sy smbgroup .
2371 2379  .It Xo
2372 2380  .Nm
2373 2381  .Cm mount
2374 2382  .Xc
2375 2383  Displays all ZFS file systems currently mounted.
2376 2384  .It Xo
2377 2385  .Nm
2378 2386  .Cm mount
2379 2387  .Op Fl Ov
2380 2388  .Op Fl o Ar options
2381 2389  .Fl a | Ar filesystem
2382 2390  .Xc
2383 2391  Mounts ZFS file systems.
2384 2392  .Bl -tag -width "-O"
2385 2393  .It Fl O
2386 2394  Perform an overlay mount. See
2387 2395  .Xr mount 1M
2388 2396  for more information.
2389 2397  .It Fl a
2390 2398  Mount all available ZFS file systems. Invoked automatically as part of the boot
2391 2399  process.
2392 2400  .It Ar filesystem
2393 2401  Mount the specified filesystem.
2394 2402  .It Fl o Ar options
2395 2403  An optional, comma-separated list of mount options to use temporarily for the
2396 2404  duration of the mount. See the
2397 2405  .Sx Temporary Mount Point Properties
2398 2406  section for details.
2399 2407  .It Fl v
2400 2408  Report mount progress.
2401 2409  .El
2402 2410  .It Xo
2403 2411  .Nm
2404 2412  .Cm unmount
2405 2413  .Op Fl f
2406 2414  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2407 2415  .Xc
2408 2416  Unmounts currently mounted ZFS file systems.
2409 2417  .Bl -tag -width "-a"
2410 2418  .It Fl a
2411 2419  Unmount all available ZFS file systems. Invoked automatically as part of the
2412 2420  shutdown process.
2413 2421  .It Ar filesystem Ns | Ns Ar mountpoint
2414 2422  Unmount the specified filesystem. The command can also be given a path to a ZFS
2415 2423  file system mount point on the system.
2416 2424  .It Fl f
2417 2425  Forcefully unmount the file system, even if it is currently in use.
2418 2426  .El
2419 2427  .It Xo
2420 2428  .Nm
2421 2429  .Cm share
2422 2430  .Fl a | Ar filesystem
2423 2431  .Xc
2424 2432  Shares available ZFS file systems.
2425 2433  .Bl -tag -width "-a"
2426 2434  .It Fl a
2427 2435  Share all available ZFS file systems. Invoked automatically as part of the boot
2428 2436  process.
2429 2437  .It Ar filesystem
2430 2438  Share the specified filesystem according to the
2431 2439  .Sy sharenfs
2432 2440  and
2433 2441  .Sy sharesmb
2434 2442  properties. File systems are shared when the
2435 2443  .Sy sharenfs
2436 2444  or
2437 2445  .Sy sharesmb
2438 2446  property is set.
2439 2447  .El
2440 2448  .It Xo
2441 2449  .Nm
2442 2450  .Cm unshare
2443 2451  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2444 2452  .Xc
2445 2453  Unshares currently shared ZFS file systems.
2446 2454  .Bl -tag -width "-a"
2447 2455  .It Fl a
2448 2456  Unshare all available ZFS file systems. Invoked automatically as part of the
2449 2457  shutdown process.
2450 2458  .It Ar filesystem Ns | Ns Ar mountpoint
2451 2459  Unshare the specified filesystem. The command can also be given a path to a ZFS
2452 2460  file system shared on the system.
2453 2461  .El
2454 2462  .It Xo
2455 2463  .Nm
2456 2464  .Cm bookmark
2457 2465  .Ar snapshot bookmark
2458 2466  .Xc
2459 2467  Creates a bookmark of the given snapshot. Bookmarks mark the point in time when
2460 2468  the snapshot was created, and can be used as the incremental source for a
2461 2469  .Nm zfs Cm send
2462 2470  command.
2463 2471  .Pp
2464 2472  This feature must be enabled to be used. See
2465 2473  .Xr zpool-features 5
2466 2474  for details on ZFS feature flags and the
2467 2475  .Sy bookmarks
2468 2476  feature.
2469 2477  .It Xo
2470 2478  .Nm
2471 2479  .Cm send
2472 2480  .Op Fl DLPRenpv
2473 2481  .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
2474 2482  .Ar snapshot
2475 2483  .Xc
2476 2484  Creates a stream representation of the second
2477 2485  .Ar snapshot ,
2478 2486  which is written to standard output. The output can be redirected to a file or
2479 2487  to a different system
2480 2488  .Po for example, using
2481 2489  .Xr ssh 1
2482 2490  .Pc .
2483 2491  By default, a full stream is generated.
2484 2492  .Bl -tag -width "-D"
2485 2493  .It Fl D
2486 2494  Generate a deduplicated stream. Blocks which would have been sent multiple times
2487 2495  in the send stream will only be sent once. The receiving system must also
2488 2496  support this feature to recieve a deduplicated stream. This flag can be used
2489 2497  regardless of the dataset's
2490 2498  .Sy dedup
2491 2499  property, but performance will be much better if the filesystem uses a
2492 2500  dedup-capable checksum
2493 2501  .Po for example,
2494 2502  .Sy sha256
2495 2503  .Pc .
2496 2504  .It Fl I Ar snapshot
2497 2505  Generate a stream package that sends all intermediary snapshots from the first
2498 2506  snapshot to the second snapshot. For example,
2499 2507  .Fl I Em @a Em fs@d
2500 2508  is similar to
2501 2509  .Fl i Em @a Em fs@b Ns ; Fl i Em @b Em fs@c Ns ; Fl i Em @c Em fs@d .
2502 2510  The incremental source may be specified as with the
2503 2511  .Fl i
2504 2512  option.
2505 2513  .It Fl L
2506 2514  Generate a stream which may contain blocks larger than 128KB. This flag has no
2507 2515  effect if the
2508 2516  .Sy large_blocks
2509 2517  pool feature is disabled, or if the
2510 2518  .Sy recordsize
2511 2519  property of this filesystem has never been set above 128KB. The receiving system
2512 2520  must have the
2513 2521  .Sy large_blocks
2514 2522  pool feature enabled as well. See
2515 2523  .Xr zpool-features 5
2516 2524  for details on ZFS feature flags and the
2517 2525  .Sy large_blocks
2518 2526  feature.
2519 2527  .It Fl P
2520 2528  Print machine-parsable verbose information about the stream package generated.
2521 2529  .It Fl R
2522 2530  Generate a replication stream package, which will replicate the specified
2523 2531  file system, and all descendent file systems, up to the named snapshot. When
2524 2532  received, all properties, snapshots, descendent file systems, and clones are
2525 2533  preserved.
2526 2534  .Pp
2527 2535  If the
2528 2536  .Fl i
2529 2537  or
2530 2538  .Fl I
2531 2539  flags are used in conjunction with the
2532 2540  .Fl R
2533 2541  flag, an incremental replication stream is generated. The current values of
2534 2542  properties, and current snapshot and file system names are set when the stream
2535 2543  is received. If the
2536 2544  .Fl F
2537 2545  flag is specified when this stream is received, snapshots and file systems that
2538 2546  do not exist on the sending side are destroyed.
2539 2547  .It Fl e
2540 2548  Generate a more compact stream by using
2541 2549  .Sy WRITE_EMBEDDED
2542 2550  records for blocks which are stored more compactly on disk by the
2543 2551  .Sy embedded_data
2544 2552  pool feature. This flag has no effect if the
2545 2553  .Sy embedded_data
2546 2554  feature is disabled. The receiving system must have the
2547 2555  .Sy embedded_data
2548 2556  feature enabled. If the
2549 2557  .Sy lz4_compress
2550 2558  feature is active on the sending system, then the receiving system must have
2551 2559  that feature enabled as well. See
2552 2560  .Xr zpool-features 5
2553 2561  for details on ZFS feature flags and the
2554 2562  .Sy embedded_data
2555 2563  feature.
2556 2564  .It Fl i Ar snapshot
2557 2565  Generate an incremental stream from the first
2558 2566  .Ar snapshot
2559 2567  .Pq the incremental source
2560 2568  to the second
2561 2569  .Ar snapshot
2562 2570  .Pq the incremental target .
2563 2571  The incremental source can be specified as the last component of the snapshot
2564 2572  name
2565 2573  .Po the
2566 2574  .Sy @
2567 2575  character and following
2568 2576  .Pc
2569 2577  and it is assumed to be from the same file system as the incremental target.
2570 2578  .Pp
2571 2579  If the destination is a clone, the source may be the origin snapshot, which must
2572 2580  be fully specified
2573 2581  .Po for example,
2574 2582  .Em pool/fs@origin ,
2575 2583  not just
2576 2584  .Em @origin
2577 2585  .Pc .
2578 2586  .It Fl n
2579 2587  Do a dry-run
2580 2588  .Pq Qq No-op
2581 2589  send. Do not generate any actual send data. This is useful in conjunction with
2582 2590  the
2583 2591  .Fl v
2584 2592  or
2585 2593  .Fl P
2586 2594  flags to determine what data will be sent. In this case, the verbose output will
2587 2595  be written to standard output
2588 2596  .Po contrast with a non-dry-run, where the stream is written to standard output
2589 2597  and the verbose output goes to standard error
2590 2598  .Pc .
2591 2599  .It Fl p
2592 2600  Include the dataset's properties in the stream. This flag is implicit when
2593 2601  .Fl R
2594 2602  is specified. The receiving system must also support this feature.
2595 2603  .It Fl v
2596 2604  Print verbose information about the stream package generated. This information
2597 2605  includes a per-second report of how much data has been sent.
2598 2606  .Pp
2599 2607  The format of the stream is committed. You will be able to receive your streams
2600 2608  on future versions of ZFS .
2601 2609  .El
2602 2610  .It Xo
2603 2611  .Nm
2604 2612  .Cm send
2605 2613  .Op Fl Le
2606 2614  .Op Fl i Ar snapshot Ns | Ns Ar bookmark
2607 2615  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2608 2616  .Xc
2609 2617  Generate a send stream, which may be of a filesystem, and may be incremental
2610 2618  from a bookmark. If the destination is a filesystem or volume, the pool must be
2611 2619  read-only, or the filesystem must not be mounted. When the stream generated from
2612 2620  a filesystem or volume is received, the default snapshot name will be
2613 2621  .Qq --head-- .
2614 2622  .Bl -tag -width "-L"
2615 2623  .It Fl L
2616 2624  Generate a stream which may contain blocks larger than 128KB. This flag has no
2617 2625  effect if the
2618 2626  .Sy large_blocks
2619 2627  pool feature is disabled, or if the
2620 2628  .Sy recordsize
2621 2629  property of this filesystem has never been set above 128KB. The receiving system
2622 2630  must have the
2623 2631  .Sy large_blocks
2624 2632  pool feature enabled as well. See
2625 2633  .Xr zpool-features 5
2626 2634  for details on ZFS feature flags and the
2627 2635  .Sy large_blocks
2628 2636  feature.
2629 2637  .It Fl e
2630 2638  Generate a more compact stream by using
2631 2639  .Sy WRITE_EMBEDDED
2632 2640  records for blocks which are stored more compactly on disk by the
2633 2641  .Sy embedded_data
2634 2642  pool feature. This flag has no effect if the
2635 2643  .Sy embedded_data
2636 2644  feature is disabled. The receiving system must have the
2637 2645  .Sy embedded_data
2638 2646  feature enabled. If the
2639 2647  .Sy lz4_compress
2640 2648  feature is active on the sending system, then the receiving system must have
2641 2649  that feature enabled as well. See
2642 2650  .Xr zpool-features 5
2643 2651  for details on ZFS feature flags and the
2644 2652  .Sy embedded_data
2645 2653  feature.
2646 2654  .It Fl i Ar snapshot Ns | Ns Ar bookmark
2647 2655  Generate an incremental send stream. The incremental source must be an earlier
2648 2656  snapshot in the destination's history. It will commonly be an earlier snapshot
2649 2657  in the destination's file system, in which case it can be specified as the last
2650 2658  component of the name
2651 2659  .Po the
2652 2660  .Sy #
2653 2661  or
2654 2662  .Sy @
2655 2663  character and following
2656 2664  .Pc .
2657 2665  .Pp
2658 2666  If the incremental target is a clone, the incremental source can be the origin
2659 2667  snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
2660 2668  origin, etc.
2661 2669  .El
2662 2670  .It Xo
2663 2671  .Nm
2664 2672  .Cm send
2665 2673  .Op Fl Penv
2666 2674  .Fl t
2667 2675  .Ar receive_resume_token
2668 2676  .Xc
2669 2677  Creates a send stream which resumes an interrupted receive.  The
2670 2678  .Ar receive_resume_token
2671 2679  is the value of this property on the filesystem
2672 2680  or volume that was being received into.  See the documentation for
2673 2681  .Sy zfs receive -s
2674 2682  for more details.
2675 2683  .It Xo
2676 2684  .Nm
2677 2685  .Cm receive
2678 2686  .Op Fl Fnsuv
2679 2687  .Op Fl o Sy origin Ns = Ns Ar snapshot
2680 2688  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2681 2689  .br
2682 2690  .Nm
2683 2691  .Cm receive
2684 2692  .Op Fl Fnsuv
2685 2693  .Op Fl d Ns | Ns Fl e
2686 2694  .Op Fl o Sy origin Ns = Ns Ar snapshot
2687 2695  .Ar filesystem
2688 2696  .Xc
2689 2697  Creates a snapshot whose contents are as specified in the stream provided on
2690 2698  standard input. If a full stream is received, then a new file system is created
2691 2699  as well. Streams are created using the
2692 2700  .Nm zfs Cm send
2693 2701  subcommand, which by default creates a full stream.
2694 2702  .Nm zfs Cm recv
2695 2703  can be used as an alias for
2696 2704  .Nm zfs Cm receive.
2697 2705  .Pp
2698 2706  If an incremental stream is received, then the destination file system must
2699 2707  already exist, and its most recent snapshot must match the incremental stream's
2700 2708  source. For
2701 2709  .Sy zvols ,
2702 2710  the destination device link is destroyed and recreated, which means the
2703 2711  .Sy zvol
2704 2712  cannot be accessed during the
2705 2713  .Cm receive
2706 2714  operation.
2707 2715  .Pp
2708 2716  When a snapshot replication package stream that is generated by using the
2709 2717  .Nm zfs Cm send Fl R
2710 2718  command is received, any snapshots that do not exist on the sending location are
2711 2719  destroyed by using the
2712 2720  .Nm zfs Cm destroy Fl d
2713 2721  command.
2714 2722  .Pp
2715 2723  The name of the snapshot
2716 2724  .Pq and file system, if a full stream is received
2717 2725  that this subcommand creates depends on the argument type and the use of the
2718 2726  .Fl d
2719 2727  or
2720 2728  .Fl e
2721 2729  options.
2722 2730  .Pp
2723 2731  If the argument is a snapshot name, the specified
2724 2732  .Ar snapshot
2725 2733  is created. If the argument is a file system or volume name, a snapshot with the
2726 2734  same name as the sent snapshot is created within the specified
2727 2735  .Ar filesystem
2728 2736  or
2729 2737  .Ar volume .
2730 2738  If neither of the
2731 2739  .Fl d
2732 2740  or
2733 2741  .Fl e
2734 2742  options are specified, the provided target snapshot name is used exactly as
2735 2743  provided.
2736 2744  .Pp
2737 2745  The
2738 2746  .Fl d
2739 2747  and
2740 2748  .Fl e
2741 2749  options cause the file system name of the target snapshot to be determined by
2742 2750  appending a portion of the sent snapshot's name to the specified target
2743 2751  .Ar filesystem .
2744 2752  If the
2745 2753  .Fl d
2746 2754  option is specified, all but the first element of the sent snapshot's file
2747 2755  system path
2748 2756  .Pq usually the pool name
2749 2757  is used and any required intermediate file systems within the specified one are
2750 2758  created. If the
2751 2759  .Fl e
2752 2760  option is specified, then only the last element of the sent snapshot's file
2753 2761  system name
2754 2762  .Pq i.e. the name of the source file system itself
2755 2763  is used as the target file system name.
2756 2764  .Bl -tag -width "-F"
2757 2765  .It Fl F
2758 2766  Force a rollback of the file system to the most recent snapshot before
2759 2767  performing the receive operation. If receiving an incremental replication stream
2760 2768  .Po for example, one generated by
2761 2769  .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
2762 2770  .Pc ,
2763 2771  destroy snapshots and file systems that do not exist on the sending side.
2764 2772  .It Fl d
2765 2773  Discard the first element of the sent snapshot's file system name, using the
2766 2774  remaining elements to determine the name of the target file system for the new
2767 2775  snapshot as described in the paragraph above.
2768 2776  .It Fl e
2769 2777  Discard all but the last element of the sent snapshot's file system name, using
2770 2778  that element to determine the name of the target file system for the new
2771 2779  snapshot as described in the paragraph above.
2772 2780  .It Fl n
2773 2781  Do not actually receive the stream. This can be useful in conjunction with the
2774 2782  .Fl v
2775 2783  option to verify the name the receive operation would use.
2776 2784  .It Fl o Sy origin Ns = Ns Ar snapshot
2777 2785  Forces the stream to be received as a clone of the given snapshot.
2778 2786  This is only valid if the stream is an incremental stream whose source
2779 2787  is the same as the provided origin.
2780 2788  .It Fl u
2781 2789  File system that is associated with the received stream is not mounted.
2782 2790  .It Fl v
2783 2791  Print verbose information about the stream and the time required to perform the
2784 2792  receive operation.
2785 2793  .It Fl s
2786 2794  If the receive is interrupted, save the partially received state, rather
2787 2795  than deleting it.  Interruption may be due to premature termination of
2788 2796  the stream
2789 2797  .Po e.g. due to network failure or failure of the remote system
2790 2798  if the stream is being read over a network connection
2791 2799  .Pc ,
2792 2800  a checksum error in the stream, termination of the
2793 2801  .Nm zfs Cm receive
2794 2802  process, or unclean shutdown of the system.
2795 2803  .Pp
2796 2804  The receive can be resumed with a stream generated by
2797 2805  .Nm zfs Cm send Fl t Ar token ,
2798 2806  where the
2799 2807  .Ar token
2800 2808  is the value of the
2801 2809  .Sy receive_resume_token
2802 2810  property of the filesystem or volume which is received into.
2803 2811  .Pp
2804 2812  To use this flag, the storage pool must have the
2805 2813  .Sy extensible_dataset
2806 2814  feature enabled.  See
2807 2815  .Xr zpool-features 5
2808 2816  for details on ZFS feature flags.
2809 2817  .El
2810 2818  .It Xo
2811 2819  .Nm
2812 2820  .Cm receive
2813 2821  .Fl A
2814 2822  .Ar filesystem Ns | Ns Ar volume
2815 2823  .Xc
2816 2824  Abort an interrupted
2817 2825  .Nm zfs Cm receive Fl s ,
2818 2826  deleting its saved partially received state.
2819 2827  .It Xo
2820 2828  .Nm
2821 2829  .Cm allow
2822 2830  .Ar filesystem Ns | Ns Ar volume
2823 2831  .Xc
2824 2832  Displays permissions that have been delegated on the specified filesystem or
2825 2833  volume. See the other forms of
2826 2834  .Nm zfs Cm allow
2827 2835  for more information.
2828 2836  .It Xo
2829 2837  .Nm
2830 2838  .Cm allow
2831 2839  .Op Fl dglu
2832 2840  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
2833 2841  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2834 2842  .Ar setname Oc Ns ...
2835 2843  .Ar filesystem Ns | Ns Ar volume
2836 2844  .br
2837 2845  .Nm
2838 2846  .Cm allow
2839 2847  .Op Fl dl
2840 2848  .Fl e Ns | Ns Sy everyone
2841 2849  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2842 2850  .Ar setname Oc Ns ...
2843 2851  .Ar filesystem Ns | Ns Ar volume
2844 2852  .Xc
2845 2853  Delegates ZFS administration permission for the file systems to non-privileged
2846 2854  users.
2847 2855  .Bl -tag -width "-d"
2848 2856  .It Fl d
2849 2857  Allow only for the descendent file systems.
2850 2858  .It Fl e Ns | Ns Sy everyone
2851 2859  Specifies that the permissions be delegated to everyone.
2852 2860  .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
2853 2861  Explicitly specify that permissions are delegated to the group.
2854 2862  .It Fl l
2855 2863  Allow
2856 2864  .Qq locally
2857 2865  only for the specified file system.
2858 2866  .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
2859 2867  Explicitly specify that permissions are delegated to the user.
2860 2868  .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
2861 2869  Specifies to whom the permissions are delegated. Multiple entities can be
2862 2870  specified as a comma-separated list. If neither of the
2863 2871  .Fl gu
2864 2872  options are specified, then the argument is interpreted preferentially as the
2865 2873  keyword
2866 2874  .Sy everyone ,
2867 2875  then as a user name, and lastly as a group name. To specify a user or group
2868 2876  named
2869 2877  .Qq everyone ,
2870 2878  use the
2871 2879  .Fl g
2872 2880  or
2873 2881  .Fl u
2874 2882  options. To specify a group with the same name as a user, use the
2875 2883  .Fl g
2876 2884  options.
2877 2885  .It Xo
2878 2886  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2879 2887  .Ar setname Oc Ns ...
2880 2888  .Xc
2881 2889  The permissions to delegate. Multiple permissions may be specified as a
2882 2890  comma-separated list. Permission names are the same as ZFS subcommand and
2883 2891  property names. See the property list below. Property set names,
2884 2892  which begin with
2885 2893  .Sy @ ,
2886 2894  may be specified. See the
2887 2895  .Fl s
2888 2896  form below for details.
2889 2897  .El
2890 2898  .Pp
2891 2899  If neither of the
2892 2900  .Fl dl
2893 2901  options are specified, or both are, then the permissions are allowed for the
2894 2902  file system or volume, and all of its descendents.
2895 2903  .Pp
2896 2904  Permissions are generally the ability to use a ZFS subcommand or change a ZFS
2897 2905  property. The following permissions are available:
2898 2906  .Bd -literal
2899 2907  NAME             TYPE           NOTES
2900 2908  allow            subcommand     Must also have the permission that is being
2901 2909                                  allowed
2902 2910  clone            subcommand     Must also have the 'create' ability and 'mount'
2903 2911                                  ability in the origin file system
2904 2912  create           subcommand     Must also have the 'mount' ability
2905 2913  destroy          subcommand     Must also have the 'mount' ability
2906 2914  diff             subcommand     Allows lookup of paths within a dataset
2907 2915                                  given an object number, and the ability to
2908 2916                                  create snapshots necessary to 'zfs diff'.
2909 2917  mount            subcommand     Allows mount/umount of ZFS datasets
2910 2918  promote          subcommand     Must also have the 'mount'
2911 2919                                  and 'promote' ability in the origin file system
2912 2920  receive          subcommand     Must also have the 'mount' and 'create' ability
2913 2921  rename           subcommand     Must also have the 'mount' and 'create'
2914 2922                                  ability in the new parent
2915 2923  rollback         subcommand     Must also have the 'mount' ability
2916 2924  send             subcommand
2917 2925  share            subcommand     Allows sharing file systems over NFS or SMB
2918 2926                                  protocols
2919 2927  snapshot         subcommand     Must also have the 'mount' ability
2920 2928  
2921 2929  groupquota       other          Allows accessing any groupquota@... property
2922 2930  groupused        other          Allows reading any groupused@... property
2923 2931  userprop         other          Allows changing any user property
2924 2932  userquota        other          Allows accessing any userquota@... property
2925 2933  userused         other          Allows reading any userused@... property
2926 2934  
2927 2935  aclinherit       property
2928 2936  aclmode          property
2929 2937  atime            property
2930 2938  canmount         property
2931 2939  casesensitivity  property
2932 2940  checksum         property
2933 2941  compression      property
2934 2942  copies           property
2935 2943  devices          property
2936 2944  exec             property
2937 2945  filesystem_limit property
2938 2946  mountpoint       property
2939 2947  nbmand           property
2940 2948  normalization    property
2941 2949  primarycache     property
2942 2950  quota            property
2943 2951  readonly         property
2944 2952  recordsize       property
2945 2953  refquota         property
2946 2954  refreservation   property
2947 2955  reservation      property
2948 2956  secondarycache   property
2949 2957  setuid           property
2950 2958  sharenfs         property
2951 2959  sharesmb         property
2952 2960  snapdir          property
2953 2961  snapshot_limit   property
2954 2962  utf8only         property
2955 2963  version          property
2956 2964  volblocksize     property
2957 2965  volsize          property
2958 2966  vscan            property
2959 2967  xattr            property
2960 2968  zoned            property
2961 2969  .Ed
2962 2970  .It Xo
2963 2971  .Nm
2964 2972  .Cm allow
2965 2973  .Fl c
2966 2974  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2967 2975  .Ar setname Oc Ns ...
2968 2976  .Ar filesystem Ns | Ns Ar volume
2969 2977  .Xc
2970 2978  Sets
2971 2979  .Qq create time
2972 2980  permissions. These permissions are granted
2973 2981  .Pq locally
2974 2982  to the creator of any newly-created descendent file system.
2975 2983  .It Xo
2976 2984  .Nm
2977 2985  .Cm allow
2978 2986  .Fl s No @ Ns Ar setname
2979 2987  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2980 2988  .Ar setname Oc Ns ...
2981 2989  .Ar filesystem Ns | Ns Ar volume
2982 2990  .Xc
2983 2991  Defines or adds permissions to a permission set. The set can be used by other
2984 2992  .Nm zfs Cm allow
2985 2993  commands for the specified file system and its descendents. Sets are evaluated
2986 2994  dynamically, so changes to a set are immediately reflected. Permission sets
2987 2995  follow the same naming restrictions as ZFS file systems, but the name must begin
2988 2996  with
2989 2997  .Sy @ ,
2990 2998  and can be no more than 64 characters long.
2991 2999  .It Xo
2992 3000  .Nm
2993 3001  .Cm unallow
2994 3002  .Op Fl dglru
2995 3003  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
2996 3004  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
2997 3005  .Ar setname Oc Ns ... Oc
2998 3006  .Ar filesystem Ns | Ns Ar volume
2999 3007  .br
3000 3008  .Nm
3001 3009  .Cm unallow
3002 3010  .Op Fl dlr
3003 3011  .Fl e Ns | Ns Sy everyone
3004 3012  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3005 3013  .Ar setname Oc Ns ... Oc
3006 3014  .Ar filesystem Ns | Ns Ar volume
3007 3015  .br
3008 3016  .Nm
3009 3017  .Cm unallow
3010 3018  .Op Fl r
3011 3019  .Fl c
3012 3020  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3013 3021  .Ar setname Oc Ns ... Oc
3014 3022  .Ar filesystem Ns | Ns Ar volume
3015 3023  .Xc
3016 3024  Removes permissions that were granted with the
3017 3025  .Nm zfs Cm allow
3018 3026  command. No permissions are explicitly denied, so other permissions granted are
3019 3027  still in effect. For example, if the permission is granted by an ancestor. If no
3020 3028  permissions are specified, then all permissions for the specified
3021 3029  .Ar user ,
3022 3030  .Ar group ,
3023 3031  or
3024 3032  .Sy everyone
3025 3033  are removed. Specifying
3026 3034  .Sy everyone
3027 3035  .Po or using the
3028 3036  .Fl e
3029 3037  option
3030 3038  .Pc
3031 3039  only removes the permissions that were granted to everyone, not all permissions
3032 3040  for every user and group. See the
3033 3041  .Nm zfs Cm allow
3034 3042  command for a description of the
3035 3043  .Fl ldugec
3036 3044  options.
3037 3045  .Bl -tag -width "-r"
3038 3046  .It Fl r
3039 3047  Recursively remove the permissions from this file system and all descendents.
3040 3048  .El
3041 3049  .It Xo
3042 3050  .Nm
3043 3051  .Cm unallow
3044 3052  .Op Fl r
3045 3053  .Fl s @ Ns Ar setname
3046 3054  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3047 3055  .Ar setname Oc Ns ... Oc
3048 3056  .Ar filesystem Ns | Ns Ar volume
3049 3057  .Xc
3050 3058  Removes permissions from a permission set. If no permissions are specified, then
3051 3059  all permissions are removed, thus removing the set entirely.
3052 3060  .It Xo
3053 3061  .Nm
3054 3062  .Cm hold
3055 3063  .Op Fl r
3056 3064  .Ar tag Ar snapshot Ns ...
3057 3065  .Xc
3058 3066  Adds a single reference, named with the
3059 3067  .Ar tag
3060 3068  argument, to the specified snapshot or snapshots. Each snapshot has its own tag
3061 3069  namespace, and tags must be unique within that space.
3062 3070  .Pp
3063 3071  If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3064 3072  .Nm zfs Cm destroy
3065 3073  command return
3066 3074  .Er EBUSY .
3067 3075  .Bl -tag -width "-r"
3068 3076  .It Fl r
3069 3077  Specifies that a hold with the given tag is applied recursively to the snapshots
3070 3078  of all descendent file systems.
3071 3079  .El
3072 3080  .It Xo
3073 3081  .Nm
3074 3082  .Cm holds
3075 3083  .Op Fl r
3076 3084  .Ar snapshot Ns ...
3077 3085  .Xc
3078 3086  Lists all existing user references for the given snapshot or snapshots.
3079 3087  .Bl -tag -width "-r"
3080 3088  .It Fl r
3081 3089  Lists the holds that are set on the named descendent snapshots, in addition to
3082 3090  listing the holds on the named snapshot.
3083 3091  .El
3084 3092  .It Xo
3085 3093  .Nm
3086 3094  .Cm release
3087 3095  .Op Fl r
3088 3096  .Ar tag Ar snapshot Ns ...
3089 3097  .Xc
3090 3098  Removes a single reference, named with the
3091 3099  .Ar tag
3092 3100  argument, from the specified snapshot or snapshots. The tag must already exist
3093 3101  for each snapshot. If a hold exists on a snapshot, attempts to destroy that
3094 3102  snapshot by using the
3095 3103  .Nm zfs Cm destroy
3096 3104  command return
3097 3105  .Er EBUSY .
3098 3106  .Bl -tag -width "-r"
3099 3107  .It Fl r
3100 3108  Recursively releases a hold with the given tag on the snapshots of all
3101 3109  descendent file systems.
3102 3110  .El
3103 3111  .It Xo
3104 3112  .Nm
3105 3113  .Cm diff
3106 3114  .Op Fl FHt
3107 3115  .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3108 3116  .Xc
3109 3117  Display the difference between a snapshot of a given filesystem and another
3110 3118  snapshot of that filesystem from a later time or the current contents of the
3111 3119  filesystem. The first column is a character indicating the type of change, the
3112 3120  other columns indicate pathname, new pathname
3113 3121  .Pq in case of rename ,
3114 3122  change in link count, and optionally file type and/or change time. The types of
3115 3123  change are:
3116 3124  .Bd -literal
3117 3125  -       The path has been removed
3118 3126  +       The path has been created
3119 3127  M       The path has been modified
3120 3128  R       The path has been renamed
3121 3129  .Ed
3122 3130  .Bl -tag -width "-F"
3123 3131  .It Fl F
3124 3132  Display an indication of the type of file, in a manner similar to the
3125 3133  .Fl
3126 3134  option of
3127 3135  .Xr ls 1 .
3128 3136  .Bd -literal
3129 3137  B       Block device
3130 3138  C       Character device
3131 3139  /       Directory
3132 3140  >       Door
3133 3141  |       Named pipe
3134 3142  @       Symbolic link
3135 3143  P       Event port
3136 3144  =       Socket
3137 3145  F       Regular file
3138 3146  .Ed
3139 3147  .It Fl H
3140 3148  Give more parsable tab-separated output, without header lines and without
3141 3149  arrows.
3142 3150  .It Fl t
3143 3151  Display the path's inode change time as the first column of output.
3144 3152  .El
3145 3153  .El
3146 3154  .Sh EXIT STATUS
3147 3155  The
3148 3156  .Nm
3149 3157  utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
3150 3158  options were specified.
3151 3159  .Sh EXAMPLES
3152 3160  .Bl -tag -width ""
3153 3161  .It Sy Example 1 No Creating a ZFS File System Hierarchy
3154 3162  The following commands create a file system named
3155 3163  .Em pool/home
3156 3164  and a file system named
3157 3165  .Em pool/home/bob .
3158 3166  The mount point
3159 3167  .Pa /export/home
3160 3168  is set for the parent file system, and is automatically inherited by the child
3161 3169  file system.
3162 3170  .Bd -literal
3163 3171  # zfs create pool/home
3164 3172  # zfs set mountpoint=/export/home pool/home
3165 3173  # zfs create pool/home/bob
3166 3174  .Ed
3167 3175  .It Sy Example 2 No Creating a ZFS Snapshot
3168 3176  The following command creates a snapshot named
3169 3177  .Sy yesterday .
3170 3178  This snapshot is mounted on demand in the
3171 3179  .Pa .zfs/snapshot
3172 3180  directory at the root of the
3173 3181  .Em pool/home/bob
3174 3182  file system.
3175 3183  .Bd -literal
3176 3184  # zfs snapshot pool/home/bob@yesterday
3177 3185  .Ed
3178 3186  .It Sy Example 3 No Creating and Destroying Multiple Snapshots
3179 3187  The following command creates snapshots named
3180 3188  .Sy yesterday
3181 3189  of
3182 3190  .Em pool/home
3183 3191  and all of its descendent file systems. Each snapshot is mounted on demand in
3184 3192  the
3185 3193  .Pa .zfs/snapshot
3186 3194  directory at the root of its file system. The second command destroys the newly
3187 3195  created snapshots.
3188 3196  .Bd -literal
3189 3197  # zfs snapshot -r pool/home@yesterday
3190 3198  # zfs destroy -r pool/home@yesterday
3191 3199  .Ed
3192 3200  .It Sy Example 4 No Disabling and Enabling File System Compression
3193 3201  The following command disables the
3194 3202  .Sy compression
3195 3203  property for all file systems under
3196 3204  .Em pool/home .
3197 3205  The next command explicitly enables
3198 3206  .Sy compression
3199 3207  for
3200 3208  .Em pool/home/anne .
3201 3209  .Bd -literal
3202 3210  # zfs set compression=off pool/home
3203 3211  # zfs set compression=on pool/home/anne
3204 3212  .Ed
3205 3213  .It Sy Example 5 No Listing ZFS Datasets
3206 3214  The following command lists all active file systems and volumes in the system.
3207 3215  Snapshots are displayed if the
3208 3216  .Sy listsnaps
3209 3217  property is
3210 3218  .Sy on .
3211 3219  The default is
3212 3220  .Sy off .
3213 3221  See
3214 3222  .Xr zpool 1M
3215 3223  for more information on pool properties.
3216 3224  .Bd -literal
3217 3225  # zfs list
3218 3226  NAME                      USED  AVAIL  REFER  MOUNTPOINT
3219 3227  pool                      450K   457G    18K  /pool
3220 3228  pool/home                 315K   457G    21K  /export/home
3221 3229  pool/home/anne             18K   457G    18K  /export/home/anne
3222 3230  pool/home/bob             276K   457G   276K  /export/home/bob
3223 3231  .Ed
3224 3232  .It Sy Example 6 No Setting a Quota on a ZFS File System
3225 3233  The following command sets a quota of 50 Gbytes for
3226 3234  .Em pool/home/bob .
3227 3235  .Bd -literal
3228 3236  # zfs set quota=50G pool/home/bob
3229 3237  .Ed
3230 3238  .It Sy Example 7 No Listing ZFS Properties
3231 3239  The following command lists all properties for
3232 3240  .Em pool/home/bob .
3233 3241  .Bd -literal
3234 3242  # zfs get all pool/home/bob
3235 3243  NAME           PROPERTY              VALUE                  SOURCE
3236 3244  pool/home/bob  type                  filesystem             -
3237 3245  pool/home/bob  creation              Tue Jul 21 15:53 2009  -
3238 3246  pool/home/bob  used                  21K                    -
3239 3247  pool/home/bob  available             20.0G                  -
3240 3248  pool/home/bob  referenced            21K                    -
3241 3249  pool/home/bob  compressratio         1.00x                  -
3242 3250  pool/home/bob  mounted               yes                    -
3243 3251  pool/home/bob  quota                 20G                    local
3244 3252  pool/home/bob  reservation           none                   default
3245 3253  pool/home/bob  recordsize            128K                   default
3246 3254  pool/home/bob  mountpoint            /pool/home/bob         default
3247 3255  pool/home/bob  sharenfs              off                    default
3248 3256  pool/home/bob  checksum              on                     default
3249 3257  pool/home/bob  compression           on                     local
3250 3258  pool/home/bob  atime                 on                     default
3251 3259  pool/home/bob  devices               on                     default
3252 3260  pool/home/bob  exec                  on                     default
3253 3261  pool/home/bob  setuid                on                     default
3254 3262  pool/home/bob  readonly              off                    default
3255 3263  pool/home/bob  zoned                 off                    default
3256 3264  pool/home/bob  snapdir               hidden                 default
3257 3265  pool/home/bob  aclmode               discard                default
3258 3266  pool/home/bob  aclinherit            restricted             default
3259 3267  pool/home/bob  canmount              on                     default
3260 3268  pool/home/bob  xattr                 on                     default
3261 3269  pool/home/bob  copies                1                      default
3262 3270  pool/home/bob  version               4                      -
3263 3271  pool/home/bob  utf8only              off                    -
3264 3272  pool/home/bob  normalization         none                   -
3265 3273  pool/home/bob  casesensitivity       sensitive              -
3266 3274  pool/home/bob  vscan                 off                    default
3267 3275  pool/home/bob  nbmand                off                    default
3268 3276  pool/home/bob  sharesmb              off                    default
3269 3277  pool/home/bob  refquota              none                   default
3270 3278  pool/home/bob  refreservation        none                   default
3271 3279  pool/home/bob  primarycache          all                    default
3272 3280  pool/home/bob  secondarycache        all                    default
3273 3281  pool/home/bob  usedbysnapshots       0                      -
3274 3282  pool/home/bob  usedbydataset         21K                    -
3275 3283  pool/home/bob  usedbychildren        0                      -
3276 3284  pool/home/bob  usedbyrefreservation  0                      -
3277 3285  .Ed
3278 3286  .Pp
3279 3287  The following command gets a single property value.
3280 3288  .Bd -literal
3281 3289  # zfs get -H -o value compression pool/home/bob
3282 3290  on
3283 3291  .Ed
3284 3292  The following command lists all properties with local settings for
3285 3293  .Em pool/home/bob .
3286 3294  .Bd -literal
3287 3295  # zfs get -r -s local -o name,property,value all pool/home/bob
3288 3296  NAME           PROPERTY              VALUE
3289 3297  pool/home/bob  quota                 20G
3290 3298  pool/home/bob  compression           on
3291 3299  .Ed
3292 3300  .It Sy Example 8 No Rolling Back a ZFS File System
3293 3301  The following command reverts the contents of
3294 3302  .Em pool/home/anne
3295 3303  to the snapshot named
3296 3304  .Sy yesterday ,
3297 3305  deleting all intermediate snapshots.
3298 3306  .Bd -literal
3299 3307  # zfs rollback -r pool/home/anne@yesterday
3300 3308  .Ed
3301 3309  .It Sy Example 9 No Creating a ZFS Clone
3302 3310  The following command creates a writable file system whose initial contents are
3303 3311  the same as
3304 3312  .Em pool/home/bob@yesterday .
3305 3313  .Bd -literal
3306 3314  # zfs clone pool/home/bob@yesterday pool/clone
3307 3315  .Ed
3308 3316  .It Sy Example 10 No Promoting a ZFS Clone
3309 3317  The following commands illustrate how to test out changes to a file system, and
3310 3318  then replace the original file system with the changed one, using clones, clone
3311 3319  promotion, and renaming:
3312 3320  .Bd -literal
3313 3321  # zfs create pool/project/production
3314 3322    populate /pool/project/production with data
3315 3323  # zfs snapshot pool/project/production@today
3316 3324  # zfs clone pool/project/production@today pool/project/beta
3317 3325    make changes to /pool/project/beta and test them
3318 3326  # zfs promote pool/project/beta
3319 3327  # zfs rename pool/project/production pool/project/legacy
3320 3328  # zfs rename pool/project/beta pool/project/production
3321 3329    once the legacy version is no longer needed, it can be destroyed
3322 3330  # zfs destroy pool/project/legacy
3323 3331  .Ed
3324 3332  .It Sy Example 11 No Inheriting ZFS Properties
3325 3333  The following command causes
3326 3334  .Em pool/home/bob
3327 3335  and
3328 3336  .Em pool/home/anne
3329 3337  to inherit the
3330 3338  .Sy checksum
3331 3339  property from their parent.
3332 3340  .Bd -literal
3333 3341  # zfs inherit checksum pool/home/bob pool/home/anne
3334 3342  .Ed
3335 3343  .It Sy Example 12 No Remotely Replicating ZFS Data
3336 3344  The following commands send a full stream and then an incremental stream to a
3337 3345  remote machine, restoring them into
3338 3346  .Em poolB/received/fs@a
3339 3347  and
3340 3348  .Em poolB/received/fs@b ,
3341 3349  respectively.
3342 3350  .Em poolB
3343 3351  must contain the file system
3344 3352  .Em poolB/received ,
3345 3353  and must not initially contain
3346 3354  .Em poolB/received/fs .
3347 3355  .Bd -literal
3348 3356  # zfs send pool/fs@a | \e
3349 3357    ssh host zfs receive poolB/received/fs@a
3350 3358  # zfs send -i a pool/fs@b | \e
3351 3359    ssh host zfs receive poolB/received/fs
3352 3360  .Ed
3353 3361  .It Sy Example 13 No Using the zfs receive -d Option
3354 3362  The following command sends a full stream of
3355 3363  .Em poolA/fsA/fsB@snap
3356 3364  to a remote machine, receiving it into
3357 3365  .Em poolB/received/fsA/fsB@snap .
3358 3366  The
3359 3367  .Em fsA/fsB@snap
3360 3368  portion of the received snapshot's name is determined from the name of the sent
3361 3369  snapshot.
3362 3370  .Em poolB
3363 3371  must contain the file system
3364 3372  .Em poolB/received .
3365 3373  If
3366 3374  .Em poolB/received/fsA
3367 3375  does not exist, it is created as an empty file system.
3368 3376  .Bd -literal
3369 3377  # zfs send poolA/fsA/fsB@snap | \e
3370 3378    ssh host zfs receive -d poolB/received
3371 3379  .Ed
3372 3380  .It Sy Example 14 No Setting User Properties
3373 3381  The following example sets the user-defined
3374 3382  .Sy com.example:department
3375 3383  property for a dataset.
3376 3384  .Bd -literal
3377 3385  # zfs set com.example:department=12345 tank/accounting
3378 3386  .Ed
3379 3387  .It Sy Example 15 No Performing a Rolling Snapshot
3380 3388  The following example shows how to maintain a history of snapshots with a
3381 3389  consistent naming scheme. To keep a week's worth of snapshots, the user
3382 3390  destroys the oldest snapshot, renames the remaining snapshots, and then creates
3383 3391  a new snapshot, as follows:
3384 3392  .Bd -literal
3385 3393  # zfs destroy -r pool/users@7daysago
3386 3394  # zfs rename -r pool/users@6daysago @7daysago
3387 3395  # zfs rename -r pool/users@5daysago @6daysago
3388 3396  # zfs rename -r pool/users@yesterday @5daysago
3389 3397  # zfs rename -r pool/users@yesterday @4daysago
3390 3398  # zfs rename -r pool/users@yesterday @3daysago
3391 3399  # zfs rename -r pool/users@yesterday @2daysago
3392 3400  # zfs rename -r pool/users@today @yesterday
3393 3401  # zfs snapshot -r pool/users@today
3394 3402  .Ed
3395 3403  .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
3396 3404  The following commands show how to set
3397 3405  .Sy sharenfs
3398 3406  property options to enable
3399 3407  .Sy rw
3400 3408  access for a set of
3401 3409  .Sy IP
3402 3410  addresses and to enable root access for system
3403 3411  .Sy neo
3404 3412  on the
3405 3413  .Em tank/home
3406 3414  file system.
3407 3415  .Bd -literal
3408 3416  # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
3409 3417  .Ed
3410 3418  .Pp
3411 3419  If you are using
3412 3420  .Sy DNS
3413 3421  for host name resolution, specify the fully qualified hostname.
3414 3422  .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
3415 3423  The following example shows how to set permissions so that user
3416 3424  .Sy cindys
3417 3425  can create, destroy, mount, and take snapshots on
3418 3426  .Em tank/cindys .
3419 3427  The permissions on
3420 3428  .Em tank/cindys
3421 3429  are also displayed.
3422 3430  .Bd -literal
3423 3431  # zfs allow cindys create,destroy,mount,snapshot tank/cindys
3424 3432  # zfs allow tank/cindys
3425 3433  ---- Permissions on tank/cindys --------------------------------------
3426 3434  Local+Descendent permissions:
3427 3435          user cindys create,destroy,mount,snapshot
3428 3436  .Ed
3429 3437  .Pp
3430 3438  Because the
3431 3439  .Em tank/cindys
3432 3440  mount point permission is set to 755 by default, user
3433 3441  .Sy cindys
3434 3442  will be unable to mount file systems under
3435 3443  .Em tank/cindys .
3436 3444  Add an
3437 3445  .Sy ACE
3438 3446  similar to the following syntax to provide mount point access:
3439 3447  .Bd -literal
3440 3448  # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
3441 3449  .Ed
3442 3450  .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
3443 3451  The following example shows how to grant anyone in the group
3444 3452  .Sy staff
3445 3453  to create file systems in
3446 3454  .Em tank/users .
3447 3455  This syntax also allows staff members to destroy their own file systems, but not
3448 3456  destroy anyone else's file system. The permissions on
3449 3457  .Em tank/users
3450 3458  are also displayed.
3451 3459  .Bd -literal
3452 3460  # zfs allow staff create,mount tank/users
3453 3461  # zfs allow -c destroy tank/users
3454 3462  # zfs allow tank/users
3455 3463  ---- Permissions on tank/users ---------------------------------------
3456 3464  Permission sets:
3457 3465          destroy
3458 3466  Local+Descendent permissions:
3459 3467          group staff create,mount
3460 3468  .Ed
3461 3469  .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
3462 3470  The following example shows how to define and grant a permission set on the
3463 3471  .Em tank/users
3464 3472  file system. The permissions on
3465 3473  .Em tank/users
3466 3474  are also displayed.
3467 3475  .Bd -literal
3468 3476  # zfs allow -s @pset create,destroy,snapshot,mount tank/users
3469 3477  # zfs allow staff @pset tank/users
3470 3478  # zfs allow tank/users
3471 3479  ---- Permissions on tank/users ---------------------------------------
3472 3480  Permission sets:
3473 3481          @pset create,destroy,mount,snapshot
3474 3482  Local+Descendent permissions:
3475 3483          group staff @pset
3476 3484  .Ed
3477 3485  .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
3478 3486  The following example shows to grant the ability to set quotas and reservations
3479 3487  on the
3480 3488  .Em users/home
3481 3489  file system. The permissions on
3482 3490  .Em users/home
3483 3491  are also displayed.
3484 3492  .Bd -literal
3485 3493  # zfs allow cindys quota,reservation users/home
3486 3494  # zfs allow users/home
3487 3495  ---- Permissions on users/home ---------------------------------------
3488 3496  Local+Descendent permissions:
3489 3497          user cindys quota,reservation
3490 3498  cindys% zfs set quota=10G users/home/marks
3491 3499  cindys% zfs get quota users/home/marks
3492 3500  NAME              PROPERTY  VALUE  SOURCE
3493 3501  users/home/marks  quota     10G    local
3494 3502  .Ed
3495 3503  .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
3496 3504  The following example shows how to remove the snapshot permission from the
3497 3505  .Sy staff
3498 3506  group on the
3499 3507  .Em tank/users
3500 3508  file system. The permissions on
3501 3509  .Em tank/users
3502 3510  are also displayed.
3503 3511  .Bd -literal
3504 3512  # zfs unallow staff snapshot tank/users
3505 3513  # zfs allow tank/users
3506 3514  ---- Permissions on tank/users ---------------------------------------
3507 3515  Permission sets:
3508 3516          @pset create,destroy,mount,snapshot
3509 3517  Local+Descendent permissions:
3510 3518          group staff @pset
3511 3519  .Ed
3512 3520  .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
3513 3521  The following example shows how to see what has changed between a prior
3514 3522  snapshot of a ZFS dataset and its current state. The
3515 3523  .Fl F
3516 3524  option is used to indicate type information for the files affected.
3517 3525  .Bd -literal
3518 3526  # zfs diff -F tank/test@before tank/test
3519 3527  M       /       /tank/test/
3520 3528  M       F       /tank/test/linked      (+1)
3521 3529  R       F       /tank/test/oldname -> /tank/test/newname
3522 3530  -       F       /tank/test/deleted
3523 3531  +       F       /tank/test/created
3524 3532  M       F       /tank/test/modified
3525 3533  .Ed
3526 3534  .El
3527 3535  .Sh INTERFACE STABILITY
3528 3536  .Sy Commited .
3529 3537  .Sh SEE ALSO
3530 3538  .Xr gzip 1,
3531 3539  .Xr ssh 1 ,
3532 3540  .Xr mount 1M ,
3533 3541  .Xr share 1M ,
3534 3542  .Xr sharemgr 1M ,
3535 3543  .Xr unshare 1M ,
3536 3544  .Xr zonecfg 1M ,
3537 3545  .Xr zpool 1M ,
3538 3546  .Xr chmod 2 ,
3539 3547  .Xr stat 2 ,
3540 3548  .Xr write 2 ,
3541 3549  .Xr fsync 3C ,
3542 3550  .Xr dfstab 4 ,
3543 3551  .Xr acl 5 ,
3544 3552  .Xr attributes 5

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX