10473 zfs(1M) missing cross-reference to zfs-program(1M)

          --- 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, 2016 by Delphix. All rights reserved.
  25   25  .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
  26      -.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
  27   26  .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
  28   27  .\" Copyright (c) 2014 Integros [integros.com]
  29   28  .\" Copyright 2018 Nexenta Systems, Inc.
  30      -.\" Copyright 2018 Joyent, Inc.
       29 +.\" Copyright 2019 Joyent, Inc.
  31   30  .\" Copyright (c) 2018 Datto Inc.
  32   31  .\"
  33      -.Dd Jan 05, 2019
       32 +.Dd February 26, 2019
  34   33  .Dt ZFS 1M
  35   34  .Os
  36   35  .Sh NAME
  37   36  .Nm zfs
  38   37  .Nd configures ZFS file systems
  39   38  .Sh SYNOPSIS
  40   39  .Nm
  41   40  .Op Fl \?
  42   41  .Nm
  43   42  .Cm create

  44   43  .Op Fl p
  45   44  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  46   45  .Ar filesystem
  47   46  .Nm
  48   47  .Cm create
  49   48  .Op Fl ps
  50   49  .Op Fl b Ar blocksize
  51   50  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  52   51  .Fl V Ar size Ar volume
  53   52  .Nm
  54   53  .Cm destroy
  55   54  .Op Fl Rfnprv
  56   55  .Ar filesystem Ns | Ns Ar volume
  57   56  .Nm
  58   57  .Cm destroy
  59   58  .Op Fl Rdnprv
  60   59  .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
  61   60  .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
  62   61  .Nm
  63   62  .Cm destroy
  64   63  .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
  65   64  .Nm
  66   65  .Cm snapshot
  67   66  .Op Fl r
  68   67  .Oo Fl o Ar property Ns = Ns value Oc Ns ...
  69   68  .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
  70   69  .Nm
  71   70  .Cm rollback
  72   71  .Op Fl Rfr
  73   72  .Ar snapshot
  74   73  .Nm
  75   74  .Cm clone
  76   75  .Op Fl p
  77   76  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
  78   77  .Ar snapshot Ar filesystem Ns | Ns Ar volume
  79   78  .Nm
  80   79  .Cm promote
  81   80  .Ar clone-filesystem
  82   81  .Nm
  83   82  .Cm rename
  84   83  .Op Fl f
  85   84  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  86   85  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
  87   86  .Nm
  88   87  .Cm rename
  89   88  .Op Fl fp
  90   89  .Ar filesystem Ns | Ns Ar volume
  91   90  .Ar filesystem Ns | Ns Ar volume
  92   91  .Nm
  93   92  .Cm rename
  94   93  .Fl r
  95   94  .Ar snapshot Ar snapshot
  96   95  .Nm
  97   96  .Cm list
  98   97  .Op Fl r Ns | Ns Fl d Ar depth
  99   98  .Op Fl Hp
 100   99  .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
 101  100  .Oo Fl s Ar property Oc Ns ...
 102  101  .Oo Fl S Ar property Oc Ns ...
 103  102  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 104  103  .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
 105  104  .Nm
 106  105  .Cm remap
 107  106  .Ar filesystem Ns | Ns Ar volume
 108  107  .Nm
 109  108  .Cm set
 110  109  .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
 111  110  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 112  111  .Nm
 113  112  .Cm get
 114  113  .Op Fl r Ns | Ns Fl d Ar depth
 115  114  .Op Fl Hp
 116  115  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 117  116  .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
 118  117  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 119  118  .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
 120  119  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
 121  120  .Nm
 122  121  .Cm inherit
 123  122  .Op Fl rS
 124  123  .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
 125  124  .Nm
 126  125  .Cm upgrade
 127  126  .Nm
 128  127  .Cm upgrade
 129  128  .Fl v
 130  129  .Nm
 131  130  .Cm upgrade
 132  131  .Op Fl r
 133  132  .Op Fl V Ar version
 134  133  .Fl a | Ar filesystem
 135  134  .Nm
 136  135  .Cm userspace
 137  136  .Op Fl Hinp
 138  137  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 139  138  .Oo Fl s Ar field Oc Ns ...
 140  139  .Oo Fl S Ar field Oc Ns ...
 141  140  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 142  141  .Ar filesystem Ns | Ns Ar snapshot
 143  142  .Nm
 144  143  .Cm groupspace
 145  144  .Op Fl Hinp
 146  145  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
 147  146  .Oo Fl s Ar field Oc Ns ...
 148  147  .Oo Fl S Ar field Oc Ns ...
 149  148  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
 150  149  .Ar filesystem Ns | Ns Ar snapshot
 151  150  .Nm
 152  151  .Cm mount
 153  152  .Nm
 154  153  .Cm mount
 155  154  .Op Fl Ov
 156  155  .Op Fl o Ar options
 157  156  .Fl a | Ar filesystem
 158  157  .Nm
 159  158  .Cm unmount
 160  159  .Op Fl f
 161  160  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
 162  161  .Nm
 163  162  .Cm share
 164  163  .Fl a | Ar filesystem
 165  164  .Nm
 166  165  .Cm unshare
 167  166  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
 168  167  .Nm
 169  168  .Cm bookmark
 170  169  .Ar snapshot bookmark
 171  170  .Nm
 172  171  .Cm send
 173  172  .Op Fl DLPRcenpv
 174  173  .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
 175  174  .Ar snapshot
 176  175  .Nm
 177  176  .Cm send
 178  177  .Op Fl Lce
 179  178  .Op Fl i Ar snapshot Ns | Ns Ar bookmark
 180  179  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
 181  180  .Nm
 182  181  .Cm send
 183  182  .Op Fl Penv
 184  183  .Fl t Ar receive_resume_token
 185  184  .Nm
 186  185  .Cm receive
 187  186  .Op Fl Fnsuv
 188  187  .Op Fl o Sy origin Ns = Ns Ar snapshot
 189  188  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
 190  189  .Nm
 191  190  .Cm receive
 192  191  .Op Fl Fnsuv
 193  192  .Op Fl d Ns | Ns Fl e
 194  193  .Op Fl o Sy origin Ns = Ns Ar snapshot
 195  194  .Ar filesystem
 196  195  .Nm
 197  196  .Cm receive
 198  197  .Fl A
 199  198  .Ar filesystem Ns | Ns Ar volume
 200  199  .Nm
 201  200  .Cm allow
 202  201  .Ar filesystem Ns | Ns Ar volume
 203  202  .Nm
 204  203  .Cm allow
 205  204  .Op Fl dglu
 206  205  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
 207  206  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 208  207  .Ar setname Oc Ns ...
 209  208  .Ar filesystem Ns | Ns Ar volume
 210  209  .Nm
 211  210  .Cm allow
 212  211  .Op Fl dl
 213  212  .Fl e Ns | Ns Sy everyone
 214  213  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 215  214  .Ar setname Oc Ns ...
 216  215  .Ar filesystem Ns | Ns Ar volume
 217  216  .Nm
 218  217  .Cm allow
 219  218  .Fl c
 220  219  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 221  220  .Ar setname Oc Ns ...
 222  221  .Ar filesystem Ns | Ns Ar volume
 223  222  .Nm
 224  223  .Cm allow
 225  224  .Fl s No @ Ns Ar setname
 226  225  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 227  226  .Ar setname Oc Ns ...
 228  227  .Ar filesystem Ns | Ns Ar volume
 229  228  .Nm
 230  229  .Cm unallow
 231  230  .Op Fl dglru
 232  231  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
 233  232  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 234  233  .Ar setname Oc Ns ... Oc
 235  234  .Ar filesystem Ns | Ns Ar volume
 236  235  .Nm
 237  236  .Cm unallow
 238  237  .Op Fl dlr
 239  238  .Fl e Ns | Ns Sy everyone
 240  239  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 241  240  .Ar setname Oc Ns ... Oc
 242  241  .Ar filesystem Ns | Ns Ar volume
 243  242  .Nm
 244  243  .Cm unallow
 245  244  .Op Fl r
 246  245  .Fl c
 247  246  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 248  247  .Ar setname Oc Ns ... Oc
 249  248  .Ar filesystem Ns | Ns Ar volume
 250  249  .Nm
 251  250  .Cm unallow
 252  251  .Op Fl r
 253  252  .Fl s @ Ns Ar setname
 254  253  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 255  254  .Ar setname Oc Ns ... Oc
 256  255  .Ar filesystem Ns | Ns Ar volume
 257  256  .Nm
 258  257  .Cm hold
 259  258  .Op Fl r
 260  259  .Ar tag Ar snapshot Ns ...
 261  260  .Nm
 262  261  .Cm holds
 263  262  .Op Fl r
 264  263  .Ar snapshot Ns ...
 265  264  .Nm
 266  265  .Cm release
 267  266  .Op Fl r
 268  267  .Ar tag Ar snapshot Ns ...
 269  268  .Nm
 270  269  .Cm diff
 271  270  .Op Fl FHt
 272  271  .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
 273  272  .Nm
 274  273  .Cm program
 275  274  .Op Fl jn
 276  275  .Op Fl t Ar timeout
 277  276  .Op Fl m Ar memory_limit
 278  277  .Ar pool script
 279  278  .Op Ar arg1 No ...
 280  279  .Sh DESCRIPTION
 281  280  The
 282  281  .Nm
 283  282  command configures ZFS datasets within a ZFS storage pool, as described in
 284  283  .Xr zpool 1M .
 285  284  A dataset is identified by a unique path within the ZFS namespace.
 286  285  For example:
 287  286  .Bd -literal
 288  287  pool/{filesystem,volume,snapshot}
 289  288  .Ed
 290  289  .Pp
 291  290  where the maximum length of a dataset name is
 292  291  .Dv MAXNAMELEN
 293  292  .Pq 256 bytes
 294  293  and the maximum amount of nesting allowed in a path is 50 levels deep.
 295  294  .Pp
 296  295  A dataset can be one of the following:
 297  296  .Bl -tag -width "file system"
 298  297  .It Sy file system
 299  298  A ZFS dataset of type
 300  299  .Sy filesystem
 301  300  can be mounted within the standard system namespace and behaves like other file
 302  301  systems.
 303  302  While ZFS file systems are designed to be POSIX compliant, known issues exist
 304  303  that prevent compliance in some cases.
 305  304  Applications that depend on standards conformance might fail due to non-standard
 306  305  behavior when checking file system free space.
 307  306  .It Sy volume
 308  307  A logical volume exported as a raw or block device.
 309  308  This type of dataset should only be used under special circumstances.
 310  309  File systems are typically used in most environments.
 311  310  .It Sy snapshot
 312  311  A read-only version of a file system or volume at a given point in time.
 313  312  It is specified as
 314  313  .Ar filesystem Ns @ Ns Ar name
 315  314  or
 316  315  .Ar volume Ns @ Ns Ar name .
 317  316  .El
 318  317  .Ss ZFS File System Hierarchy
 319  318  A ZFS storage pool is a logical collection of devices that provide space for
 320  319  datasets.
 321  320  A storage pool is also the root of the ZFS file system hierarchy.
 322  321  .Pp
 323  322  The root of the pool can be accessed as a file system, such as mounting and
 324  323  unmounting, taking snapshots, and setting properties.
 325  324  The physical storage characteristics, however, are managed by the
 326  325  .Xr zpool 1M
 327  326  command.
 328  327  .Pp
 329  328  See
 330  329  .Xr zpool 1M
 331  330  for more information on creating and administering pools.
 332  331  .Ss Snapshots
 333  332  A snapshot is a read-only copy of a file system or volume.
 334  333  Snapshots can be created extremely quickly, and initially consume no additional
 335  334  space within the pool.
 336  335  As data within the active dataset changes, the snapshot consumes more data than
 337  336  would otherwise be shared with the active dataset.
 338  337  .Pp
 339  338  Snapshots can have arbitrary names.
 340  339  Snapshots of volumes can be cloned or rolled back, but cannot be accessed
 341  340  independently.
 342  341  .Pp
 343  342  File system snapshots can be accessed under the
 344  343  .Pa .zfs/snapshot
 345  344  directory in the root of the file system.
 346  345  Snapshots are automatically mounted on demand and may be unmounted at regular
 347  346  intervals.
 348  347  The visibility of the
 349  348  .Pa .zfs
 350  349  directory can be controlled by the
 351  350  .Sy snapdir
 352  351  property.
 353  352  .Ss Clones
 354  353  A clone is a writable volume or file system whose initial contents are the same
 355  354  as another dataset.
 356  355  As with snapshots, creating a clone is nearly instantaneous, and initially
 357  356  consumes no additional space.
 358  357  .Pp
 359  358  Clones can only be created from a snapshot.
 360  359  When a snapshot is cloned, it creates an implicit dependency between the parent
 361  360  and child.
 362  361  Even though the clone is created somewhere else in the dataset hierarchy, the
 363  362  original snapshot cannot be destroyed as long as a clone exists.
 364  363  The
 365  364  .Sy origin
 366  365  property exposes this dependency, and the
 367  366  .Cm destroy
 368  367  command lists any such dependencies, if they exist.
 369  368  .Pp
 370  369  The clone parent-child dependency relationship can be reversed by using the
 371  370  .Cm promote
 372  371  subcommand.
 373  372  This causes the
 374  373  .Qq origin
 375  374  file system to become a clone of the specified file system, which makes it
 376  375  possible to destroy the file system that the clone was created from.
 377  376  .Ss "Mount Points"
 378  377  Creating a ZFS file system is a simple operation, so the number of file systems
 379  378  per system is likely to be numerous.
 380  379  To cope with this, ZFS automatically manages mounting and unmounting file
 381  380  systems without the need to edit the
 382  381  .Pa /etc/vfstab
 383  382  file.
 384  383  All automatically managed file systems are mounted by ZFS at boot time.
 385  384  .Pp
 386  385  By default, file systems are mounted under
 387  386  .Pa /path ,
 388  387  where
 389  388  .Ar path
 390  389  is the name of the file system in the ZFS namespace.
 391  390  Directories are created and destroyed as needed.
 392  391  .Pp
 393  392  A file system can also have a mount point set in the
 394  393  .Sy mountpoint
 395  394  property.
 396  395  This directory is created as needed, and ZFS automatically mounts the file
 397  396  system when the
 398  397  .Nm zfs Cm mount Fl a
 399  398  command is invoked
 400  399  .Po without editing
 401  400  .Pa /etc/vfstab
 402  401  .Pc .
 403  402  The
 404  403  .Sy mountpoint
 405  404  property can be inherited, so if
 406  405  .Em pool/home
 407  406  has a mount point of
 408  407  .Pa /export/stuff ,
 409  408  then
 410  409  .Em pool/home/user
 411  410  automatically inherits a mount point of
 412  411  .Pa /export/stuff/user .
 413  412  .Pp
 414  413  A file system
 415  414  .Sy mountpoint
 416  415  property of
 417  416  .Sy none
 418  417  prevents the file system from being mounted.
 419  418  .Pp
 420  419  If needed, ZFS file systems can also be managed with traditional tools
 421  420  .Po
 422  421  .Nm mount ,
 423  422  .Nm umount ,
 424  423  .Pa /etc/vfstab
 425  424  .Pc .
 426  425  If a file system's mount point is set to
 427  426  .Sy legacy ,
 428  427  ZFS makes no attempt to manage the file system, and the administrator is
 429  428  responsible for mounting and unmounting the file system.
 430  429  .Ss "Zones"
 431  430  A ZFS file system can be added to a non-global zone by using the
 432  431  .Nm zonecfg Cm add Sy fs
 433  432  subcommand.
 434  433  A ZFS file system that is added to a non-global zone must have its
 435  434  .Sy mountpoint
 436  435  property set to
 437  436  .Sy legacy .
 438  437  .Pp
 439  438  The physical properties of an added file system are controlled by the global
 440  439  administrator.
 441  440  However, the zone administrator can create, modify, or destroy files within the
 442  441  added file system, depending on how the file system is mounted.
 443  442  .Pp
 444  443  A dataset can also be delegated to a non-global zone by using the
 445  444  .Nm zonecfg Cm add Sy dataset
 446  445  subcommand.
 447  446  You cannot delegate a dataset to one zone and the children of the same dataset
 448  447  to another zone.
 449  448  The zone administrator can change properties of the dataset or any of its
 450  449  children.
 451  450  However, the
 452  451  .Sy quota ,
 453  452  .Sy filesystem_limit
 454  453  and
 455  454  .Sy snapshot_limit
 456  455  properties of the delegated dataset can be modified only by the global
 457  456  administrator.
 458  457  .Pp
 459  458  A ZFS volume can be added as a device to a non-global zone by using the
 460  459  .Nm zonecfg Cm add Sy device
 461  460  subcommand.
 462  461  However, its physical properties can be modified only by the global
 463  462  administrator.
 464  463  .Pp
 465  464  For more information about
 466  465  .Nm zonecfg
 467  466  syntax, see
 468  467  .Xr zonecfg 1M .
 469  468  .Pp
 470  469  After a dataset is delegated to a non-global zone, the
 471  470  .Sy zoned
 472  471  property is automatically set.
 473  472  A zoned file system cannot be mounted in the global zone, since the zone
 474  473  administrator might have to set the mount point to an unacceptable value.
 475  474  .Pp
 476  475  The global administrator can forcibly clear the
 477  476  .Sy zoned
 478  477  property, though this should be done with extreme care.
 479  478  The global administrator should verify that all the mount points are acceptable
 480  479  before clearing the property.
 481  480  .Ss Native Properties
 482  481  Properties are divided into two types, native properties and user-defined
 483  482  .Po or
 484  483  .Qq user
 485  484  .Pc
 486  485  properties.
 487  486  Native properties either export internal statistics or control ZFS behavior.
 488  487  In addition, native properties are either editable or read-only.
 489  488  User properties have no effect on ZFS behavior, but you can use them to annotate
 490  489  datasets in a way that is meaningful in your environment.
 491  490  For more information about user properties, see the
 492  491  .Sx User Properties
 493  492  section, below.
 494  493  .Pp
 495  494  Every dataset has a set of properties that export statistics about the dataset
 496  495  as well as control various behaviors.
 497  496  Properties are inherited from the parent unless overridden by the child.
 498  497  Some properties apply only to certain types of datasets
 499  498  .Pq file systems, volumes, or snapshots .
 500  499  .Pp
 501  500  The values of numeric properties can be specified using human-readable suffixes
 502  501  .Po for example,
 503  502  .Sy k ,
 504  503  .Sy KB ,
 505  504  .Sy M ,
 506  505  .Sy Gb ,
 507  506  and so forth, up to
 508  507  .Sy Z
 509  508  for zettabyte
 510  509  .Pc .
 511  510  The following are all valid
 512  511  .Pq and equal
 513  512  specifications:
 514  513  .Li 1536M, 1.5g, 1.50GB .
 515  514  .Pp
 516  515  The values of non-numeric properties are case sensitive and must be lowercase,
 517  516  except for
 518  517  .Sy mountpoint ,
 519  518  .Sy sharenfs ,
 520  519  and
 521  520  .Sy sharesmb .
 522  521  .Pp
 523  522  The following native properties consist of read-only statistics about the
 524  523  dataset.
 525  524  These properties can be neither set, nor inherited.
 526  525  Native properties apply to all dataset types unless otherwise noted.
 527  526  .Bl -tag -width "usedbyrefreservation"
 528  527  .It Sy available
 529  528  The amount of space available to the dataset and all its children, assuming that
 530  529  there is no other activity in the pool.
 531  530  Because space is shared within a pool, availability can be limited by any number
 532  531  of factors, including physical pool size, quotas, reservations, or other
 533  532  datasets within the pool.
 534  533  .Pp
 535  534  This property can also be referred to by its shortened column name,
 536  535  .Sy avail .
 537  536  .It Sy compressratio
 538  537  For non-snapshots, the compression ratio achieved for the
 539  538  .Sy used
 540  539  space of this dataset, expressed as a multiplier.
 541  540  The
 542  541  .Sy used
 543  542  property includes descendant datasets, and, for clones, does not include the
 544  543  space shared with the origin snapshot.
 545  544  For snapshots, the
 546  545  .Sy compressratio
 547  546  is the same as the
 548  547  .Sy refcompressratio
 549  548  property.
 550  549  Compression can be turned on by running:
 551  550  .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset .
 552  551  The default value is
 553  552  .Sy off .
 554  553  .It Sy createtxg
 555  554  The transaction group (txg) in which the dataset was created.
 556  555  Bookmarks have the same
 557  556  .Sy createtxg
 558  557  as the snapshot they are initially tied to.
 559  558  This property is suitable for ordering a list of snapshots,
 560  559  e.g. for incremental send and receive.
 561  560  .It Sy creation
 562  561  The time this dataset was created.
 563  562  .It Sy clones
 564  563  For snapshots, this property is a comma-separated list of filesystems or volumes
 565  564  which are clones of this snapshot.
 566  565  The clones'
 567  566  .Sy origin
 568  567  property is this snapshot.
 569  568  If the
 570  569  .Sy clones
 571  570  property is not empty, then this snapshot can not be destroyed
 572  571  .Po even with the
 573  572  .Fl r
 574  573  or
 575  574  .Fl f
 576  575  options
 577  576  .Pc .
 578  577  .It Sy defer_destroy
 579  578  This property is
 580  579  .Sy on
 581  580  if the snapshot has been marked for deferred destroy by using the
 582  581  .Nm zfs Cm destroy Fl d
 583  582  command.
 584  583  Otherwise, the property is
 585  584  .Sy off .
 586  585  .It Sy filesystem_count
 587  586  The total number of filesystems and volumes that exist under this location in
 588  587  the dataset tree.
 589  588  This value is only available when a
 590  589  .Sy filesystem_limit
 591  590  has been set somewhere in the tree under which the dataset resides.
 592  591  .It Sy guid
 593  592  The 64 bit GUID of this dataset or bookmark which does not change over its
 594  593  entire lifetime.
 595  594  When a snapshot is sent to another pool, the received snapshot has the same
 596  595  GUID.
 597  596  Thus, the
 598  597  .Sy guid
 599  598  is suitable to identify a snapshot across pools.
 600  599  .It Sy logicalreferenced
 601  600  The amount of space that is
 602  601  .Qq logically
 603  602  accessible by this dataset.
 604  603  See the
 605  604  .Sy referenced
 606  605  property.
 607  606  The logical space ignores the effect of the
 608  607  .Sy compression
 609  608  and
 610  609  .Sy copies
 611  610  properties, giving a quantity closer to the amount of data that applications
 612  611  see.
 613  612  However, it does include space consumed by metadata.
 614  613  .Pp
 615  614  This property can also be referred to by its shortened column name,
 616  615  .Sy lrefer .
 617  616  .It Sy logicalused
 618  617  The amount of space that is
 619  618  .Qq logically
 620  619  consumed by this dataset and all its descendents.
 621  620  See the
 622  621  .Sy used
 623  622  property.
 624  623  The logical space ignores the effect of the
 625  624  .Sy compression
 626  625  and
 627  626  .Sy copies
 628  627  properties, giving a quantity closer to the amount of data that applications
 629  628  see.
 630  629  However, it does include space consumed by metadata.
 631  630  .Pp
 632  631  This property can also be referred to by its shortened column name,
 633  632  .Sy lused .
 634  633  .It Sy mounted
 635  634  For file systems, indicates whether the file system is currently mounted.
 636  635  This property can be either
 637  636  .Sy yes
 638  637  or
 639  638  .Sy no .
 640  639  .It Sy origin
 641  640  For cloned file systems or volumes, the snapshot from which the clone was
 642  641  created.
 643  642  See also the
 644  643  .Sy clones
 645  644  property.
 646  645  .It Sy receive_resume_token
 647  646  For filesystems or volumes which have saved partially-completed state from
 648  647  .Sy zfs receive -s ,
 649  648  this opaque token can be provided to
 650  649  .Sy zfs send -t
 651  650  to resume and complete the
 652  651  .Sy zfs receive .
 653  652  .It Sy referenced
 654  653  The amount of data that is accessible by this dataset, which may or may not be
 655  654  shared with other datasets in the pool.
 656  655  When a snapshot or clone is created, it initially references the same amount of
 657  656  space as the file system or snapshot it was created from, since its contents are
 658  657  identical.
 659  658  .Pp
 660  659  This property can also be referred to by its shortened column name,
 661  660  .Sy refer .
 662  661  .It Sy refcompressratio
 663  662  The compression ratio achieved for the
 664  663  .Sy referenced
 665  664  space of this dataset, expressed as a multiplier.
 666  665  See also the
 667  666  .Sy compressratio
 668  667  property.
 669  668  .It Sy snapshot_count
 670  669  The total number of snapshots that exist under this location in the dataset
 671  670  tree.
 672  671  This value is only available when a
 673  672  .Sy snapshot_limit
 674  673  has been set somewhere in the tree under which the dataset resides.
 675  674  .It Sy type
 676  675  The type of dataset:
 677  676  .Sy filesystem ,
 678  677  .Sy volume ,
 679  678  or
 680  679  .Sy snapshot .
 681  680  .It Sy used
 682  681  The amount of space consumed by this dataset and all its descendents.
 683  682  This is the value that is checked against this dataset's quota and reservation.
 684  683  The space used does not include this dataset's reservation, but does take into
 685  684  account the reservations of any descendent datasets.
 686  685  The amount of space that a dataset consumes from its parent, as well as the
 687  686  amount of space that is freed if this dataset is recursively destroyed, is the
 688  687  greater of its space used and its reservation.
 689  688  .Pp
 690  689  The used space of a snapshot
 691  690  .Po see the
 692  691  .Sx Snapshots
 693  692  section
 694  693  .Pc
 695  694  is space that is referenced exclusively by this snapshot.
 696  695  If this snapshot is destroyed, the amount of
 697  696  .Sy used
 698  697  space will be freed.
 699  698  Space that is shared by multiple snapshots isn't accounted for in this metric.
 700  699  When a snapshot is destroyed, space that was previously shared with this
 701  700  snapshot can become unique to snapshots adjacent to it, thus changing the used
 702  701  space of those snapshots.
 703  702  The used space of the latest snapshot can also be affected by changes in the
 704  703  file system.
 705  704  Note that the
 706  705  .Sy used
 707  706  space of a snapshot is a subset of the
 708  707  .Sy written
 709  708  space of the snapshot.
 710  709  .Pp
 711  710  The amount of space used, available, or referenced does not take into account
 712  711  pending changes.
 713  712  Pending changes are generally accounted for within a few seconds.
 714  713  Committing a change to a disk using
 715  714  .Xr fsync 3C
 716  715  or
 717  716  .Dv O_SYNC
 718  717  does not necessarily guarantee that the space usage information is updated
 719  718  immediately.
 720  719  .It Sy usedby*
 721  720  The
 722  721  .Sy usedby*
 723  722  properties decompose the
 724  723  .Sy used
 725  724  properties into the various reasons that space is used.
 726  725  Specifically,
 727  726  .Sy used No =
 728  727  .Sy usedbychildren No +
 729  728  .Sy usedbydataset No +
 730  729  .Sy usedbyrefreservation No +
 731  730  .Sy usedbysnapshots .
 732  731  These properties are only available for datasets created on
 733  732  .Nm zpool
 734  733  .Qo version 13 Qc
 735  734  pools.
 736  735  .It Sy usedbychildren
 737  736  The amount of space used by children of this dataset, which would be freed if
 738  737  all the dataset's children were destroyed.
 739  738  .It Sy usedbydataset
 740  739  The amount of space used by this dataset itself, which would be freed if the
 741  740  dataset were destroyed
 742  741  .Po after first removing any
 743  742  .Sy refreservation
 744  743  and destroying any necessary snapshots or descendents
 745  744  .Pc .
 746  745  .It Sy usedbyrefreservation
 747  746  The amount of space used by a
 748  747  .Sy refreservation
 749  748  set on this dataset, which would be freed if the
 750  749  .Sy refreservation
 751  750  was removed.
 752  751  .It Sy usedbysnapshots
 753  752  The amount of space consumed by snapshots of this dataset.
 754  753  In particular, it is the amount of space that would be freed if all of this
 755  754  dataset's snapshots were destroyed.
 756  755  Note that this is not simply the sum of the snapshots'
 757  756  .Sy used
 758  757  properties because space can be shared by multiple snapshots.
 759  758  .It Sy userused Ns @ Ns Em user
 760  759  The amount of space consumed by the specified user in this dataset.
 761  760  Space is charged to the owner of each file, as displayed by
 762  761  .Nm ls Fl l .
 763  762  The amount of space charged is displayed by
 764  763  .Nm du
 765  764  and
 766  765  .Nm ls Fl s .
 767  766  See the
 768  767  .Nm zfs Cm userspace
 769  768  subcommand for more information.
 770  769  .Pp
 771  770  Unprivileged users can access only their own space usage.
 772  771  The root user, or a user who has been granted the
 773  772  .Sy userused
 774  773  privilege with
 775  774  .Nm zfs Cm allow ,
 776  775  can access everyone's usage.
 777  776  .Pp
 778  777  The
 779  778  .Sy userused Ns @ Ns Em ...
 780  779  properties are not displayed by
 781  780  .Nm zfs Cm get Sy all .
 782  781  The user's name must be appended after the @ symbol, using one of the following
 783  782  forms:
 784  783  .Bl -bullet -width ""
 785  784  .It
 786  785  .Em POSIX name
 787  786  .Po for example,
 788  787  .Sy joe
 789  788  .Pc
 790  789  .It
 791  790  .Em POSIX numeric ID
 792  791  .Po for example,
 793  792  .Sy 789
 794  793  .Pc
 795  794  .It
 796  795  .Em SID name
 797  796  .Po for example,
 798  797  .Sy joe.smith@mydomain
 799  798  .Pc
 800  799  .It
 801  800  .Em SID numeric ID
 802  801  .Po for example,
 803  802  .Sy S-1-123-456-789
 804  803  .Pc
 805  804  .El
 806  805  .It Sy userrefs
 807  806  This property is set to the number of user holds on this snapshot.
 808  807  User holds are set by using the
 809  808  .Nm zfs Cm hold
 810  809  command.
 811  810  .It Sy groupused Ns @ Ns Em group
 812  811  The amount of space consumed by the specified group in this dataset.
 813  812  Space is charged to the group of each file, as displayed by
 814  813  .Nm ls Fl l .
 815  814  See the
 816  815  .Sy userused Ns @ Ns Em user
 817  816  property for more information.
 818  817  .Pp
 819  818  Unprivileged users can only access their own groups' space usage.
 820  819  The root user, or a user who has been granted the
 821  820  .Sy groupused
 822  821  privilege with
 823  822  .Nm zfs Cm allow ,
 824  823  can access all groups' usage.
 825  824  .It Sy volblocksize
 826  825  For volumes, specifies the block size of the volume.
 827  826  The
 828  827  .Sy blocksize
 829  828  cannot be changed once the volume has been written, so it should be set at
 830  829  volume creation time.
 831  830  The default
 832  831  .Sy blocksize
 833  832  for volumes is 8 Kbytes.
 834  833  Any power of 2 from 512 bytes to 128 Kbytes is valid.
 835  834  .Pp
 836  835  This property can also be referred to by its shortened column name,
 837  836  .Sy volblock .
 838  837  .It Sy written
 839  838  The amount of space
 840  839  .Sy referenced
 841  840  by this dataset, that was written since the previous snapshot
 842  841  .Pq i.e. that is not referenced by the previous snapshot .
 843  842  .It Sy written Ns @ Ns Em snapshot
 844  843  The amount of
 845  844  .Sy referenced
 846  845  space written to this dataset since the specified snapshot.
 847  846  This is the space that is referenced by this dataset but was not referenced by
 848  847  the specified snapshot.
 849  848  .Pp
 850  849  The
 851  850  .Em snapshot
 852  851  may be specified as a short snapshot name
 853  852  .Po just the part after the
 854  853  .Sy @
 855  854  .Pc ,
 856  855  in which case it will be interpreted as a snapshot in the same filesystem as
 857  856  this dataset.
 858  857  The
 859  858  .Em snapshot
 860  859  may be a full snapshot name
 861  860  .Po Em filesystem Ns @ Ns Em snapshot Pc ,
 862  861  which for clones may be a snapshot in the origin's filesystem
 863  862  .Pq or the origin of the origin's filesystem, etc.
 864  863  .El
 865  864  .Pp
 866  865  The following native properties can be used to change the behavior of a ZFS
 867  866  dataset.
 868  867  .Bl -tag -width ""
 869  868  .It Xo
 870  869  .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns
 871  870  .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x
 872  871  .Xc
 873  872  Controls how ACEs are inherited when files and directories are created.
 874  873  .Bl -tag -width "passthrough-x"
 875  874  .It Sy discard
 876  875  does not inherit any ACEs.
 877  876  .It Sy noallow
 878  877  only inherits inheritable ACEs that specify
 879  878  .Qq deny
 880  879  permissions.
 881  880  .It Sy restricted
 882  881  default, removes the
 883  882  .Sy write_acl
 884  883  and
 885  884  .Sy write_owner
 886  885  permissions when the ACE is inherited.
 887  886  .It Sy passthrough
 888  887  inherits all inheritable ACEs without any modifications.
 889  888  .It Sy passthrough-x
 890  889  same meaning as
 891  890  .Sy passthrough ,
 892  891  except that the
 893  892  .Sy owner@ ,
 894  893  .Sy group@ ,
 895  894  and
 896  895  .Sy everyone@
 897  896  ACEs inherit the execute permission only if the file creation mode also requests
 898  897  the execute bit.
 899  898  .El
 900  899  .Pp
 901  900  When the property value is set to
 902  901  .Sy passthrough ,
 903  902  files are created with a mode determined by the inheritable ACEs.
 904  903  If no inheritable ACEs exist that affect the mode, then the mode is set in
 905  904  accordance to the requested mode from the application.
 906  905  .It Xo
 907  906  .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns
 908  907  .Sy passthrough Ns | Ns Sy restricted
 909  908  .Xc
 910  909  Controls how an ACL is modified during
 911  910  .Xr chmod 2
 912  911  and how inherited ACEs are modified by the file creation mode.
 913  912  .Bl -tag -width "passthrough"
 914  913  .It Sy discard
 915  914  default, deletes all ACEs except for those representing the mode of the file or
 916  915  directory requested by
 917  916  .Xr chmod 2 .
 918  917  .It Sy groupmask
 919  918  reduces permissions granted by all
 920  919  .Sy ALLOW
 921  920  entries found in the ACL such that they are no greater than the group
 922  921  permissions specified by the mode.
 923  922  .It Sy passthrough
 924  923  indicates that no changes are made to the ACL other than creating or updating
 925  924  the necessary ACEs to represent the new mode of the file or directory.
 926  925  .It Sy restricted
 927  926  causes the
 928  927  .Xr chmod 2
 929  928  operation to return an error when used on any file or directory which has a
 930  929  non-trivial ACL, with entries in addition to those that represent the mode.
 931  930  .El
 932  931  .Pp
 933  932  .Xr chmod 2
 934  933  is required to change the set user ID, set group ID, or sticky bit on a file or
 935  934  directory, as they do not have equivalent ACEs.
 936  935  In order to use
 937  936  .Xr chmod 2
 938  937  on a file or directory with a non-trivial ACL when
 939  938  .Sy aclmode
 940  939  is set to
 941  940  .Sy restricted ,
 942  941  you must first remove all ACEs except for those that represent the current mode.
 943  942  .It Sy atime Ns = Ns Sy on Ns | Ns Sy off
 944  943  Controls whether the access time for files is updated when they are read.
 945  944  Turning this property off avoids producing write traffic when reading files and
 946  945  can result in significant performance gains, though it might confuse mailers
 947  946  and other similar utilities.
 948  947  The default value is
 949  948  .Sy on .
 950  949  .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto
 951  950  If this property is set to
 952  951  .Sy off ,
 953  952  the file system cannot be mounted, and is ignored by
 954  953  .Nm zfs Cm mount Fl a .
 955  954  Setting this property to
 956  955  .Sy off
 957  956  is similar to setting the
 958  957  .Sy mountpoint
 959  958  property to
 960  959  .Sy none ,
 961  960  except that the dataset still has a normal
 962  961  .Sy mountpoint
 963  962  property, which can be inherited.
 964  963  Setting this property to
 965  964  .Sy off
 966  965  allows datasets to be used solely as a mechanism to inherit properties.
 967  966  One example of setting
 968  967  .Sy canmount Ns = Ns Sy off
 969  968  is to have two datasets with the same
 970  969  .Sy mountpoint ,
 971  970  so that the children of both datasets appear in the same directory, but might
 972  971  have different inherited characteristics.
 973  972  .Pp
 974  973  When set to
 975  974  .Sy noauto ,
 976  975  a dataset can only be mounted and unmounted explicitly.
 977  976  The dataset is not mounted automatically when the dataset is created or
 978  977  imported, nor is it mounted by the
 979  978  .Nm zfs Cm mount Fl a
 980  979  command or unmounted by the
 981  980  .Nm zfs Cm unmount Fl a
 982  981  command.
 983  982  .Pp
 984  983  This property is not inherited.
 985  984  .It Xo
 986  985  .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns
 987  986  .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns
 988  987  .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr
 989  988  .Xc
 990  989  Controls the checksum used to verify data integrity.
 991  990  The default value is
 992  991  .Sy on ,
 993  992  which automatically selects an appropriate algorithm
 994  993  .Po currently,
 995  994  .Sy fletcher4 ,
 996  995  but this may change in future releases
 997  996  .Pc .
 998  997  The value
 999  998  .Sy off
1000  999  disables integrity checking on user data.
1001 1000  The value
1002 1001  .Sy noparity
1003 1002  not only disables integrity but also disables maintaining parity for user data.
1004 1003  This setting is used internally by a dump device residing on a RAID-Z pool and
1005 1004  should not be used by any other dataset.
1006 1005  Disabling checksums is
1007 1006  .Sy NOT
1008 1007  a recommended practice.
1009 1008  .Pp
1010 1009  The
1011 1010  .Sy sha512 ,
1012 1011  .Sy skein ,
1013 1012  and
1014 1013  .Sy edonr
1015 1014  checksum algorithms require enabling the appropriate features on the pool.
1016 1015  Please see
1017 1016  .Xr zpool-features 5
1018 1017  for more information on these algorithms.
1019 1018  .Pp
1020 1019  Changing this property affects only newly-written data.
1021 1020  .It Xo
1022 1021  .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns
1023 1022  .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle
1024 1023  .Xc
1025 1024  Controls the compression algorithm used for this dataset.
1026 1025  .Pp
1027 1026  Setting compression to
1028 1027  .Sy on
1029 1028  indicates that the current default compression algorithm should be used.
1030 1029  The default balances compression and decompression speed, with compression ratio
1031 1030  and is expected to work well on a wide variety of workloads.
1032 1031  Unlike all other settings for this property,
1033 1032  .Sy on
1034 1033  does not select a fixed compression type.
1035 1034  As new compression algorithms are added to ZFS and enabled on a pool, the
1036 1035  default compression algorithm may change.
1037 1036  The current default compression algorithm is either
1038 1037  .Sy lzjb
1039 1038  or, if the
1040 1039  .Sy lz4_compress
1041 1040  feature is enabled,
1042 1041  .Sy lz4 .
1043 1042  .Pp
1044 1043  The
1045 1044  .Sy lz4
1046 1045  compression algorithm is a high-performance replacement for the
1047 1046  .Sy lzjb
1048 1047  algorithm.
1049 1048  It features significantly faster compression and decompression, as well as a
1050 1049  moderately higher compression ratio than
1051 1050  .Sy lzjb ,
1052 1051  but can only be used on pools with the
1053 1052  .Sy lz4_compress
1054 1053  feature set to
1055 1054  .Sy enabled .
1056 1055  See
1057 1056  .Xr zpool-features 5
1058 1057  for details on ZFS feature flags and the
1059 1058  .Sy lz4_compress
1060 1059  feature.
1061 1060  .Pp
1062 1061  The
1063 1062  .Sy lzjb
1064 1063  compression algorithm is optimized for performance while providing decent data
1065 1064  compression.
1066 1065  .Pp
1067 1066  The
1068 1067  .Sy gzip
1069 1068  compression algorithm uses the same compression as the
1070 1069  .Xr gzip 1
1071 1070  command.
1072 1071  You can specify the
1073 1072  .Sy gzip
1074 1073  level by using the value
1075 1074  .Sy gzip- Ns Em N ,
1076 1075  where
1077 1076  .Em N
1078 1077  is an integer from 1
1079 1078  .Pq fastest
1080 1079  to 9
1081 1080  .Pq best compression ratio .
1082 1081  Currently,
1083 1082  .Sy gzip
1084 1083  is equivalent to
1085 1084  .Sy gzip-6
1086 1085  .Po which is also the default for
1087 1086  .Xr gzip 1
1088 1087  .Pc .
1089 1088  .Pp
1090 1089  The
1091 1090  .Sy zle
1092 1091  compression algorithm compresses runs of zeros.
1093 1092  .Pp
1094 1093  This property can also be referred to by its shortened column name
1095 1094  .Sy compress .
1096 1095  Changing this property affects only newly-written data.
1097 1096  .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3
1098 1097  Controls the number of copies of data stored for this dataset.
1099 1098  These copies are in addition to any redundancy provided by the pool, for
1100 1099  example, mirroring or RAID-Z.
1101 1100  The copies are stored on different disks, if possible.
1102 1101  The space used by multiple copies is charged to the associated file and dataset,
1103 1102  changing the
1104 1103  .Sy used
1105 1104  property and counting against quotas and reservations.
1106 1105  .Pp
1107 1106  Changing this property only affects newly-written data.
1108 1107  Therefore, set this property at file system creation time by using the
1109 1108  .Fl o Sy copies Ns = Ns Ar N
1110 1109  option.
1111 1110  .It Sy devices Ns = Ns Sy on Ns | Ns Sy off
1112 1111  Controls whether device nodes can be opened on this file system.
1113 1112  The default value is
1114 1113  .Sy on .
1115 1114  .It Sy exec Ns = Ns Sy on Ns | Ns Sy off
1116 1115  Controls whether processes can be executed from within this file system.
1117 1116  The default value is
1118 1117  .Sy on .
1119 1118  .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none
1120 1119  Limits the number of filesystems and volumes that can exist under this point in
1121 1120  the dataset tree.
1122 1121  The limit is not enforced if the user is allowed to change the limit.
1123 1122  Setting a
1124 1123  .Sy filesystem_limit
1125 1124  to
1126 1125  .Sy on
1127 1126  a descendent of a filesystem that already has a
1128 1127  .Sy filesystem_limit
1129 1128  does not override the ancestor's
1130 1129  .Sy filesystem_limit ,
1131 1130  but rather imposes an additional limit.
1132 1131  This feature must be enabled to be used
1133 1132  .Po see
1134 1133  .Xr zpool-features 5
1135 1134  .Pc .
1136 1135  .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy
1137 1136  Controls the mount point used for this file system.
1138 1137  See the
1139 1138  .Sx Mount Points
1140 1139  section for more information on how this property is used.
1141 1140  .Pp
1142 1141  When the
1143 1142  .Sy mountpoint
1144 1143  property is changed for a file system, the file system and any children that
1145 1144  inherit the mount point are unmounted.
1146 1145  If the new value is
1147 1146  .Sy legacy ,
1148 1147  then they remain unmounted.
1149 1148  Otherwise, they are automatically remounted in the new location if the property
1150 1149  was previously
1151 1150  .Sy legacy
1152 1151  or
1153 1152  .Sy none ,
1154 1153  or if they were mounted before the property was changed.
1155 1154  In addition, any shared file systems are unshared and shared in the new
1156 1155  location.
1157 1156  .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off
1158 1157  Controls whether the file system should be mounted with
1159 1158  .Sy nbmand
1160 1159  .Pq Non Blocking mandatory locks .
1161 1160  This is used for SMB clients.
1162 1161  Changes to this property only take effect when the file system is umounted and
1163 1162  remounted.
1164 1163  See
1165 1164  .Xr mount 1M
1166 1165  for more information on
1167 1166  .Sy nbmand
1168 1167  mounts.
1169 1168  .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1170 1169  Controls what is cached in the primary cache
1171 1170  .Pq ARC .
1172 1171  If this property is set to
1173 1172  .Sy all ,
1174 1173  then both user data and metadata is cached.
1175 1174  If this property is set to
1176 1175  .Sy none ,
1177 1176  then neither user data nor metadata is cached.
1178 1177  If this property is set to
1179 1178  .Sy metadata ,
1180 1179  then only metadata is cached.
1181 1180  The default value is
1182 1181  .Sy all .
1183 1182  .It Sy quota Ns = Ns Em size Ns | Ns Sy none
1184 1183  Limits the amount of space a dataset and its descendents can consume.
1185 1184  This property enforces a hard limit on the amount of space used.
1186 1185  This includes all space consumed by descendents, including file systems and
1187 1186  snapshots.
1188 1187  Setting a quota on a descendent of a dataset that already has a quota does not
1189 1188  override the ancestor's quota, but rather imposes an additional limit.
1190 1189  .Pp
1191 1190  Quotas cannot be set on volumes, as the
1192 1191  .Sy volsize
1193 1192  property acts as an implicit quota.
1194 1193  .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none
1195 1194  Limits the number of snapshots that can be created on a dataset and its
1196 1195  descendents.
1197 1196  Setting a
1198 1197  .Sy snapshot_limit
1199 1198  on a descendent of a dataset that already has a
1200 1199  .Sy snapshot_limit
1201 1200  does not override the ancestor's
1202 1201  .Sy snapshot_limit ,
1203 1202  but rather imposes an additional limit.
1204 1203  The limit is not enforced if the user is allowed to change the limit.
1205 1204  For example, this means that recursive snapshots taken from the global zone are
1206 1205  counted against each delegated dataset within a zone.
1207 1206  This feature must be enabled to be used
1208 1207  .Po see
1209 1208  .Xr zpool-features 5
1210 1209  .Pc .
1211 1210  .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none
1212 1211  Limits the amount of space consumed by the specified user.
1213 1212  User space consumption is identified by the
1214 1213  .Sy userspace@ Ns Em user
1215 1214  property.
1216 1215  .Pp
1217 1216  Enforcement of user quotas may be delayed by several seconds.
1218 1217  This delay means that a user might exceed their quota before the system notices
1219 1218  that they are over quota and begins to refuse additional writes with the
1220 1219  .Er EDQUOT
1221 1220  error message.
1222 1221  See the
1223 1222  .Nm zfs Cm userspace
1224 1223  subcommand for more information.
1225 1224  .Pp
1226 1225  Unprivileged users can only access their own groups' space usage.
1227 1226  The root user, or a user who has been granted the
1228 1227  .Sy userquota
1229 1228  privilege with
1230 1229  .Nm zfs Cm allow ,
1231 1230  can get and set everyone's quota.
1232 1231  .Pp
1233 1232  This property is not available on volumes, on file systems before version 4, or
1234 1233  on pools before version 15.
1235 1234  The
1236 1235  .Sy userquota@ Ns Em ...
1237 1236  properties are not displayed by
1238 1237  .Nm zfs Cm get Sy all .
1239 1238  The user's name must be appended after the
1240 1239  .Sy @
1241 1240  symbol, using one of the following forms:
1242 1241  .Bl -bullet
1243 1242  .It
1244 1243  .Em POSIX name
1245 1244  .Po for example,
1246 1245  .Sy joe
1247 1246  .Pc
1248 1247  .It
1249 1248  .Em POSIX numeric ID
1250 1249  .Po for example,
1251 1250  .Sy 789
1252 1251  .Pc
1253 1252  .It
1254 1253  .Em SID name
1255 1254  .Po for example,
1256 1255  .Sy joe.smith@mydomain
1257 1256  .Pc
1258 1257  .It
1259 1258  .Em SID numeric ID
1260 1259  .Po for example,
1261 1260  .Sy S-1-123-456-789
1262 1261  .Pc
1263 1262  .El
1264 1263  .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none
1265 1264  Limits the amount of space consumed by the specified group.
1266 1265  Group space consumption is identified by the
1267 1266  .Sy groupused@ Ns Em group
1268 1267  property.
1269 1268  .Pp
1270 1269  Unprivileged users can access only their own groups' space usage.
1271 1270  The root user, or a user who has been granted the
1272 1271  .Sy groupquota
1273 1272  privilege with
1274 1273  .Nm zfs Cm allow ,
1275 1274  can get and set all groups' quotas.
1276 1275  .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
1277 1276  Controls whether this dataset can be modified.
1278 1277  The default value is
1279 1278  .Sy off .
1280 1279  .Pp
1281 1280  This property can also be referred to by its shortened column name,
1282 1281  .Sy rdonly .
1283 1282  .It Sy recordsize Ns = Ns Em size
1284 1283  Specifies a suggested block size for files in the file system.
1285 1284  This property is designed solely for use with database workloads that access
1286 1285  files in fixed-size records.
1287 1286  ZFS automatically tunes block sizes according to internal algorithms optimized
1288 1287  for typical access patterns.
1289 1288  .Pp
1290 1289  For databases that create very large files but access them in small random
1291 1290  chunks, these algorithms may be suboptimal.
1292 1291  Specifying a
1293 1292  .Sy recordsize
1294 1293  greater than or equal to the record size of the database can result in
1295 1294  significant performance gains.
1296 1295  Use of this property for general purpose file systems is strongly discouraged,
1297 1296  and may adversely affect performance.
1298 1297  .Pp
1299 1298  The size specified must be a power of two greater than or equal to 512 and less
1300 1299  than or equal to 128 Kbytes.
1301 1300  If the
1302 1301  .Sy large_blocks
1303 1302  feature is enabled on the pool, the size may be up to 1 Mbyte.
1304 1303  See
1305 1304  .Xr zpool-features 5
1306 1305  for details on ZFS feature flags.
1307 1306  .Pp
1308 1307  Changing the file system's
1309 1308  .Sy recordsize
1310 1309  affects only files created afterward; existing files are unaffected.
1311 1310  .Pp
1312 1311  This property can also be referred to by its shortened column name,
1313 1312  .Sy recsize .
1314 1313  .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most
1315 1314  Controls what types of metadata are stored redundantly.
1316 1315  ZFS stores an extra copy of metadata, so that if a single block is corrupted,
1317 1316  the amount of user data lost is limited.
1318 1317  This extra copy is in addition to any redundancy provided at the pool level
1319 1318  .Pq e.g. by mirroring or RAID-Z ,
1320 1319  and is in addition to an extra copy specified by the
1321 1320  .Sy copies
1322 1321  property
1323 1322  .Pq up to a total of 3 copies .
1324 1323  For example if the pool is mirrored,
1325 1324  .Sy copies Ns = Ns 2 ,
1326 1325  and
1327 1326  .Sy redundant_metadata Ns = Ns Sy most ,
1328 1327  then ZFS stores 6 copies of most metadata, and 4 copies of data and some
1329 1328  metadata.
1330 1329  .Pp
1331 1330  When set to
1332 1331  .Sy all ,
1333 1332  ZFS stores an extra copy of all metadata.
1334 1333  If a single on-disk block is corrupt, at worst a single block of user data
1335 1334  .Po which is
1336 1335  .Sy recordsize
1337 1336  bytes long
1338 1337  .Pc
1339 1338  can be lost.
1340 1339  .Pp
1341 1340  When set to
1342 1341  .Sy most ,
1343 1342  ZFS stores an extra copy of most types of metadata.
1344 1343  This can improve performance of random writes, because less metadata must be
1345 1344  written.
1346 1345  In practice, at worst about 100 blocks
1347 1346  .Po of
1348 1347  .Sy recordsize
1349 1348  bytes each
1350 1349  .Pc
1351 1350  of user data can be lost if a single on-disk block is corrupt.
1352 1351  The exact behavior of which metadata blocks are stored redundantly may change in
1353 1352  future releases.
1354 1353  .Pp
1355 1354  The default value is
1356 1355  .Sy all .
1357 1356  .It Sy refquota Ns = Ns Em size Ns | Ns Sy none
1358 1357  Limits the amount of space a dataset can consume.
1359 1358  This property enforces a hard limit on the amount of space used.
1360 1359  This hard limit does not include space used by descendents, including file
1361 1360  systems and snapshots.
1362 1361  .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto
1363 1362  The minimum amount of space guaranteed to a dataset, not including its
1364 1363  descendents.
1365 1364  When the amount of space used is below this value, the dataset is treated as if
1366 1365  it were taking up the amount of space specified by
1367 1366  .Sy refreservation .
1368 1367  The
1369 1368  .Sy refreservation
1370 1369  reservation is accounted for in the parent datasets' space used, and counts
1371 1370  against the parent datasets' quotas and reservations.
1372 1371  .Pp
1373 1372  If
1374 1373  .Sy refreservation
1375 1374  is set, a snapshot is only allowed if there is enough free pool space outside of
1376 1375  this reservation to accommodate the current number of
1377 1376  .Qq referenced
1378 1377  bytes in the dataset.
1379 1378  .Pp
1380 1379  If
1381 1380  .Sy refreservation
1382 1381  is set to
1383 1382  .Sy auto ,
1384 1383  a volume is thick provisioned
1385 1384  .Po or
1386 1385  .Qq not sparse
1387 1386  .Pc .
1388 1387  .Sy refreservation Ns = Ns Sy auto
1389 1388  is only supported on volumes.
1390 1389  See
1391 1390  .Sy volsize
1392 1391  in the
1393 1392  .Sx Native Properties
1394 1393  section for more information about sparse volumes.
1395 1394  .Pp
1396 1395  This property can also be referred to by its shortened column name,
1397 1396  .Sy refreserv .
1398 1397  .It Sy reservation Ns = Ns Em size Ns | Ns Sy none
1399 1398  The minimum amount of space guaranteed to a dataset and its descendants.
1400 1399  When the amount of space used is below this value, the dataset is treated as if
1401 1400  it were taking up the amount of space specified by its reservation.
1402 1401  Reservations are accounted for in the parent datasets' space used, and count
1403 1402  against the parent datasets' quotas and reservations.
1404 1403  .Pp
1405 1404  This property can also be referred to by its shortened column name,
1406 1405  .Sy reserv .
1407 1406  .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata
1408 1407  Controls what is cached in the secondary cache
1409 1408  .Pq L2ARC .
1410 1409  If this property is set to
1411 1410  .Sy all ,
1412 1411  then both user data and metadata is cached.
1413 1412  If this property is set to
1414 1413  .Sy none ,
1415 1414  then neither user data nor metadata is cached.
1416 1415  If this property is set to
1417 1416  .Sy metadata ,
1418 1417  then only metadata is cached.
1419 1418  The default value is
1420 1419  .Sy all .
1421 1420  .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off
1422 1421  Controls whether the setuid bit is respected for the file system.
1423 1422  The default value is
1424 1423  .Sy on .
1425 1424  .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1426 1425  Controls whether the file system is shared via SMB, and what options are to be
1427 1426  used.
1428 1427  A file system with the
1429 1428  .Sy sharesmb
1430 1429  property set to
1431 1430  .Sy off
1432 1431  is managed through traditional tools such as
1433 1432  .Xr sharemgr 1M .
1434 1433  Otherwise, the file system is automatically shared and unshared with the
1435 1434  .Nm zfs Cm share
1436 1435  and
1437 1436  .Nm zfs Cm unshare
1438 1437  commands.
1439 1438  If the property is set to
1440 1439  .Sy on ,
1441 1440  the
1442 1441  .Xr sharemgr 1M
1443 1442  command is invoked with no options.
1444 1443  Otherwise, the
1445 1444  .Xr sharemgr 1M
1446 1445  command is invoked with options equivalent to the contents of this property.
1447 1446  .Pp
1448 1447  Because SMB shares requires a resource name, a unique resource name is
1449 1448  constructed from the dataset name.
1450 1449  The constructed name is a copy of the dataset name except that the characters in
1451 1450  the dataset name, which would be invalid in the resource name, are replaced with
1452 1451  underscore
1453 1452  .Pq Sy _
1454 1453  characters.
1455 1454  A pseudo property
1456 1455  .Qq name
1457 1456  is also supported that allows you to replace the data set name with a specified
1458 1457  name.
1459 1458  The specified name is then used to replace the prefix dataset in the case of
1460 1459  inheritance.
1461 1460  For example, if the dataset
1462 1461  .Em data/home/john
1463 1462  is set to
1464 1463  .Sy name Ns = Ns Sy john ,
1465 1464  then
1466 1465  .Em data/home/john
1467 1466  has a resource name of
1468 1467  .Sy john .
1469 1468  If a child dataset
1470 1469  .Em data/home/john/backups
1471 1470  is shared, it has a resource name of
1472 1471  .Sy john_backups .
1473 1472  .Pp
1474 1473  When SMB shares are created, the SMB share name appears as an entry in the
1475 1474  .Pa .zfs/shares
1476 1475  directory.
1477 1476  You can use the
1478 1477  .Nm ls
1479 1478  or
1480 1479  .Nm chmod
1481 1480  command to display the share-level ACLs on the entries in this directory.
1482 1481  .Pp
1483 1482  When the
1484 1483  .Sy sharesmb
1485 1484  property is changed for a dataset, the dataset and any children inheriting the
1486 1485  property are re-shared with the new options, only if the property was previously
1487 1486  set to
1488 1487  .Sy off ,
1489 1488  or if they were shared before the property was changed.
1490 1489  If the new property is set to
1491 1490  .Sy off ,
1492 1491  the file systems are unshared.
1493 1492  .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts
1494 1493  Controls whether the file system is shared via NFS, and what options are to be
1495 1494  used.
1496 1495  A file system with a
1497 1496  .Sy sharenfs
1498 1497  property of
1499 1498  .Sy off
1500 1499  is managed through traditional tools such as
1501 1500  .Xr share 1M ,
1502 1501  .Xr unshare 1M ,
1503 1502  and
1504 1503  .Xr dfstab 4 .
1505 1504  Otherwise, the file system is automatically shared and unshared with the
1506 1505  .Nm zfs Cm share
1507 1506  and
1508 1507  .Nm zfs Cm unshare
1509 1508  commands.
1510 1509  If the property is set to
1511 1510  .Sy on ,
1512 1511  .Xr share 1M
1513 1512  command is invoked with no options.
1514 1513  Otherwise, the
1515 1514  .Xr share 1M
1516 1515  command is invoked with options equivalent to the contents of this property.
1517 1516  .Pp
1518 1517  When the
1519 1518  .Sy sharenfs
1520 1519  property is changed for a dataset, the dataset and any children inheriting the
1521 1520  property are re-shared with the new options, only if the property was previously
1522 1521  .Sy off ,
1523 1522  or if they were shared before the property was changed.
1524 1523  If the new property is
1525 1524  .Sy off ,
1526 1525  the file systems are unshared.
1527 1526  .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput
1528 1527  Provide a hint to ZFS about handling of synchronous requests in this dataset.
1529 1528  If
1530 1529  .Sy logbias
1531 1530  is set to
1532 1531  .Sy latency
1533 1532  .Pq the default ,
1534 1533  ZFS will use pool log devices
1535 1534  .Pq if configured
1536 1535  to handle the requests at low latency.
1537 1536  If
1538 1537  .Sy logbias
1539 1538  is set to
1540 1539  .Sy throughput ,
1541 1540  ZFS will not use configured pool log devices.
1542 1541  ZFS will instead optimize synchronous operations for global pool throughput and
1543 1542  efficient use of resources.
1544 1543  .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible
1545 1544  Controls whether the
1546 1545  .Pa .zfs
1547 1546  directory is hidden or visible in the root of the file system as discussed in
1548 1547  the
1549 1548  .Sx Snapshots
1550 1549  section.
1551 1550  The default value is
1552 1551  .Sy hidden .
1553 1552  .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled
1554 1553  Controls the behavior of synchronous requests
1555 1554  .Pq e.g. fsync, O_DSYNC .
1556 1555  .Sy standard
1557 1556  is the
1558 1557  .Tn POSIX
1559 1558  specified behavior of ensuring all synchronous requests are written to stable
1560 1559  storage and all devices are flushed to ensure data is not cached by device
1561 1560  controllers
1562 1561  .Pq this is the default .
1563 1562  .Sy always
1564 1563  causes every file system transaction to be written and flushed before its
1565 1564  system call returns.
1566 1565  This has a large performance penalty.
1567 1566  .Sy disabled
1568 1567  disables synchronous requests.
1569 1568  File system transactions are only committed to stable storage periodically.
1570 1569  This option will give the highest performance.
1571 1570  However, it is very dangerous as ZFS would be ignoring the synchronous
1572 1571  transaction demands of applications such as databases or NFS.
1573 1572  Administrators should only use this option when the risks are understood.
1574 1573  .It Sy version Ns = Ns Em N Ns | Ns Sy current
1575 1574  The on-disk version of this file system, which is independent of the pool
1576 1575  version.
1577 1576  This property can only be set to later supported versions.
1578 1577  See the
1579 1578  .Nm zfs Cm upgrade
1580 1579  command.
1581 1580  .It Sy volsize Ns = Ns Em size
1582 1581  For volumes, specifies the logical size of the volume.
1583 1582  By default, creating a volume establishes a reservation of equal size.
1584 1583  For storage pools with a version number of 9 or higher, a
1585 1584  .Sy refreservation
1586 1585  is set instead.
1587 1586  Any changes to
1588 1587  .Sy volsize
1589 1588  are reflected in an equivalent change to the reservation
1590 1589  .Po or
1591 1590  .Sy refreservation
1592 1591  .Pc .
1593 1592  The
1594 1593  .Sy volsize
1595 1594  can only be set to a multiple of
1596 1595  .Sy volblocksize ,
1597 1596  and cannot be zero.
1598 1597  .Pp
1599 1598  The reservation is kept equal to the volume's logical size to prevent unexpected
1600 1599  behavior for consumers.
1601 1600  Without the reservation, the volume could run out of space, resulting in
1602 1601  undefined behavior or data corruption, depending on how the volume is used.
1603 1602  These effects can also occur when the volume size is changed while it is in use
1604 1603  .Pq particularly when shrinking the size .
1605 1604  Extreme care should be used when adjusting the volume size.
1606 1605  .Pp
1607 1606  Though not recommended, a
1608 1607  .Qq sparse volume
1609 1608  .Po also known as
1610 1609  .Qq thin provisioned
1611 1610  .Pc
1612 1611  can be created by specifying the
1613 1612  .Fl s
1614 1613  option to the
1615 1614  .Nm zfs Cm create Fl V
1616 1615  command, or by changing the value of the
1617 1616  .Sy refreservation
1618 1617  property
1619 1618  .Po or
1620 1619  .Sy reservation
1621 1620  property on pool version 8 or earlier
1622 1621  .Pc
1623 1622  after the volume has been created.
1624 1623  A
1625 1624  .Qq sparse volume
1626 1625  is a volume where the value of
1627 1626  .Sy refreservation
1628 1627  is less than the size of the volume plus the space required to store its
1629 1628  metadata.
1630 1629  Consequently, writes to a sparse volume can fail with
1631 1630  .Er ENOSPC
1632 1631  when the pool is low on space.
1633 1632  For a sparse volume, changes to
1634 1633  .Sy volsize
1635 1634  are not reflected in the
1636 1635  .Sy refreservation.
1637 1636  A volume that is not sparse is said to be
1638 1637  .Qq thick provisioned .
1639 1638  A sparse volume can become thick provisioned by setting
1640 1639  .Sy refreservation
1641 1640  to
1642 1641  .Sy auto .
1643 1642  .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off
1644 1643  Controls whether regular files should be scanned for viruses when a file is
1645 1644  opened and closed.
1646 1645  In addition to enabling this property, the virus scan service must also be
1647 1646  enabled for virus scanning to occur.
1648 1647  The default value is
1649 1648  .Sy off .
1650 1649  .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off
1651 1650  Controls whether extended attributes are enabled for this file system.
1652 1651  The default value is
1653 1652  .Sy on .
1654 1653  .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off
1655 1654  Controls whether the dataset is managed from a non-global zone.
1656 1655  See the
1657 1656  .Sx Zones
1658 1657  section for more information.
1659 1658  The default value is
1660 1659  .Sy off .
1661 1660  .El
1662 1661  .Pp
1663 1662  The following three properties cannot be changed after the file system is
1664 1663  created, and therefore, should be set when the file system is created.
1665 1664  If the properties are not set with the
1666 1665  .Nm zfs Cm create
1667 1666  or
1668 1667  .Nm zpool Cm create
1669 1668  commands, these properties are inherited from the parent dataset.
1670 1669  If the parent dataset lacks these properties due to having been created prior to
1671 1670  these features being supported, the new file system will have the default values
1672 1671  for these properties.
1673 1672  .Bl -tag -width ""
1674 1673  .It Xo
1675 1674  .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns
1676 1675  .Sy insensitive Ns | Ns Sy mixed
1677 1676  .Xc
1678 1677  Indicates whether the file name matching algorithm used by the file system
1679 1678  should be case-sensitive, case-insensitive, or allow a combination of both
1680 1679  styles of matching.
1681 1680  The default value for the
1682 1681  .Sy casesensitivity
1683 1682  property is
1684 1683  .Sy sensitive .
1685 1684  Traditionally,
1686 1685  .Ux
1687 1686  and
1688 1687  .Tn POSIX
1689 1688  file systems have case-sensitive file names.
1690 1689  .Pp
1691 1690  The
1692 1691  .Sy mixed
1693 1692  value for the
1694 1693  .Sy casesensitivity
1695 1694  property indicates that the file system can support requests for both
1696 1695  case-sensitive and case-insensitive matching behavior.
1697 1696  Currently, case-insensitive matching behavior on a file system that supports
1698 1697  mixed behavior is limited to the SMB server product.
1699 1698  For more information about the
1700 1699  .Sy mixed
1701 1700  value behavior, see the "ZFS Administration Guide".
1702 1701  .It Xo
1703 1702  .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns
1704 1703  .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD
1705 1704  .Xc
1706 1705  Indicates whether the file system should perform a
1707 1706  .Sy unicode
1708 1707  normalization of file names whenever two file names are compared, and which
1709 1708  normalization algorithm should be used.
1710 1709  File names are always stored unmodified, names are normalized as part of any
1711 1710  comparison process.
1712 1711  If this property is set to a legal value other than
1713 1712  .Sy none ,
1714 1713  and the
1715 1714  .Sy utf8only
1716 1715  property was left unspecified, the
1717 1716  .Sy utf8only
1718 1717  property is automatically set to
1719 1718  .Sy on .
1720 1719  The default value of the
1721 1720  .Sy normalization
1722 1721  property is
1723 1722  .Sy none .
1724 1723  This property cannot be changed after the file system is created.
1725 1724  .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off
1726 1725  Indicates whether the file system should reject file names that include
1727 1726  characters that are not present in the
1728 1727  .Sy UTF-8
1729 1728  character code set.
1730 1729  If this property is explicitly set to
1731 1730  .Sy off ,
1732 1731  the normalization property must either not be explicitly set or be set to
1733 1732  .Sy none .
1734 1733  The default value for the
1735 1734  .Sy utf8only
1736 1735  property is
1737 1736  .Sy off .
1738 1737  This property cannot be changed after the file system is created.
1739 1738  .El
1740 1739  .Pp
1741 1740  The
1742 1741  .Sy casesensitivity ,
1743 1742  .Sy normalization ,
1744 1743  and
1745 1744  .Sy utf8only
1746 1745  properties are also new permissions that can be assigned to non-privileged users
1747 1746  by using the ZFS delegated administration feature.
1748 1747  .Ss "Temporary Mount Point Properties"
1749 1748  When a file system is mounted, either through
1750 1749  .Xr mount 1M
1751 1750  for legacy mounts or the
1752 1751  .Nm zfs Cm mount
1753 1752  command for normal file systems, its mount options are set according to its
1754 1753  properties.
1755 1754  The correlation between properties and mount options is as follows:
1756 1755  .Bd -literal
1757 1756      PROPERTY                MOUNT OPTION
1758 1757      devices                 devices/nodevices
1759 1758      exec                    exec/noexec
1760 1759      readonly                ro/rw
1761 1760      setuid                  setuid/nosetuid
1762 1761      xattr                   xattr/noxattr
1763 1762  .Ed
1764 1763  .Pp
1765 1764  In addition, these options can be set on a per-mount basis using the
1766 1765  .Fl o
1767 1766  option, without affecting the property that is stored on disk.
1768 1767  The values specified on the command line override the values stored in the
1769 1768  dataset.
1770 1769  The
1771 1770  .Sy nosuid
1772 1771  option is an alias for
1773 1772  .Sy nodevices Ns \&, Ns Sy nosetuid .
1774 1773  These properties are reported as
1775 1774  .Qq temporary
1776 1775  by the
1777 1776  .Nm zfs Cm get
1778 1777  command.
1779 1778  If the properties are changed while the dataset is mounted, the new setting
1780 1779  overrides any temporary settings.
1781 1780  .Ss "User Properties"
1782 1781  In addition to the standard native properties, ZFS supports arbitrary user
1783 1782  properties.
1784 1783  User properties have no effect on ZFS behavior, but applications or
1785 1784  administrators can use them to annotate datasets
1786 1785  .Pq file systems, volumes, and snapshots .
1787 1786  .Pp
1788 1787  User property names must contain a colon
1789 1788  .Pq Qq Sy \&:
1790 1789  character to distinguish them from native properties.
1791 1790  They may contain lowercase letters, numbers, and the following punctuation
1792 1791  characters: colon
1793 1792  .Pq Qq Sy \&: ,
1794 1793  dash
1795 1794  .Pq Qq Sy - ,
1796 1795  period
1797 1796  .Pq Qq Sy \&. ,
1798 1797  and underscore
1799 1798  .Pq Qq Sy _ .
1800 1799  The expected convention is that the property name is divided into two portions
1801 1800  such as
1802 1801  .Em module Ns \&: Ns Em property ,
1803 1802  but this namespace is not enforced by ZFS.
1804 1803  User property names can be at most 256 characters, and cannot begin with a dash
1805 1804  .Pq Qq Sy - .
1806 1805  .Pp
1807 1806  When making programmatic use of user properties, it is strongly suggested to use
1808 1807  a reversed
1809 1808  .Sy DNS
1810 1809  domain name for the
1811 1810  .Em module
1812 1811  component of property names to reduce the chance that two
1813 1812  independently-developed packages use the same property name for different
1814 1813  purposes.
1815 1814  .Pp
1816 1815  The values of user properties are arbitrary strings, are always inherited, and
1817 1816  are never validated.
1818 1817  All of the commands that operate on properties
1819 1818  .Po Nm zfs Cm list ,
1820 1819  .Nm zfs Cm get ,
1821 1820  .Nm zfs Cm set ,
1822 1821  and so forth
1823 1822  .Pc
1824 1823  can be used to manipulate both native properties and user properties.
1825 1824  Use the
1826 1825  .Nm zfs Cm inherit
1827 1826  command to clear a user property.
1828 1827  If the property is not defined in any parent dataset, it is removed entirely.
1829 1828  Property values are limited to 8192 bytes.
1830 1829  .Ss ZFS Volumes as Swap or Dump Devices
1831 1830  During an initial installation a swap device and dump device are created on ZFS
1832 1831  volumes in the ZFS root pool.
1833 1832  By default, the swap area size is based on 1/2 the size of physical memory up to
1834 1833  2 Gbytes.
1835 1834  The size of the dump device depends on the kernel's requirements at installation
1836 1835  time.
1837 1836  Separate ZFS volumes must be used for the swap area and dump devices.
1838 1837  Do not swap to a file on a ZFS file system.
1839 1838  A ZFS swap file configuration is not supported.
1840 1839  .Pp
1841 1840  If you need to change your swap area or dump device after the system is
1842 1841  installed or upgraded, use the
1843 1842  .Xr swap 1M
1844 1843  and
1845 1844  .Xr dumpadm 1M
1846 1845  commands.
1847 1846  .Sh SUBCOMMANDS
1848 1847  All subcommands that modify state are logged persistently to the pool in their
1849 1848  original form.
1850 1849  .Bl -tag -width ""
1851 1850  .It Nm Fl \?
1852 1851  Displays a help message.
1853 1852  .It Xo
1854 1853  .Nm
1855 1854  .Cm create
1856 1855  .Op Fl p
1857 1856  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1858 1857  .Ar filesystem
1859 1858  .Xc
1860 1859  Creates a new ZFS file system.
1861 1860  The file system is automatically mounted according to the
1862 1861  .Sy mountpoint
1863 1862  property inherited from the parent.
1864 1863  .Bl -tag -width "-o"
1865 1864  .It Fl o Ar property Ns = Ns Ar value
1866 1865  Sets the specified property as if the command
1867 1866  .Nm zfs Cm set Ar property Ns = Ns Ar value
1868 1867  was invoked at the same time the dataset was created.
1869 1868  Any editable ZFS property can also be set at creation time.
1870 1869  Multiple
1871 1870  .Fl o
1872 1871  options can be specified.
1873 1872  An error results if the same property is specified in multiple
1874 1873  .Fl o
1875 1874  options.
1876 1875  .It Fl p
1877 1876  Creates all the non-existing parent datasets.
1878 1877  Datasets created in this manner are automatically mounted according to the
1879 1878  .Sy mountpoint
1880 1879  property inherited from their parent.
1881 1880  Any property specified on the command line using the
1882 1881  .Fl o
1883 1882  option is ignored.
1884 1883  If the target filesystem already exists, the operation completes successfully.
1885 1884  .El
1886 1885  .It Xo
1887 1886  .Nm
1888 1887  .Cm create
1889 1888  .Op Fl ps
1890 1889  .Op Fl b Ar blocksize
1891 1890  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
1892 1891  .Fl V Ar size Ar volume
1893 1892  .Xc
1894 1893  Creates a volume of the given size.
1895 1894  The volume is exported as a block device in
1896 1895  .Pa /dev/zvol/{dsk,rdsk}/path ,
1897 1896  where
1898 1897  .Em path
1899 1898  is the name of the volume in the ZFS namespace.
1900 1899  The size represents the logical size as exported by the device.
1901 1900  By default, a reservation of equal size is created.
1902 1901  .Pp
1903 1902  .Ar size
1904 1903  is automatically rounded up to the nearest 128 Kbytes to ensure that the volume
1905 1904  has an integral number of blocks regardless of
1906 1905  .Sy blocksize .
1907 1906  .Bl -tag -width "-b"
1908 1907  .It Fl b Ar blocksize
1909 1908  Equivalent to
1910 1909  .Fl o Sy volblocksize Ns = Ns Ar blocksize .
1911 1910  If this option is specified in conjunction with
1912 1911  .Fl o Sy volblocksize ,
1913 1912  the resulting behavior is undefined.
1914 1913  .It Fl o Ar property Ns = Ns Ar value
1915 1914  Sets the specified property as if the
1916 1915  .Nm zfs Cm set Ar property Ns = Ns Ar value
1917 1916  command was invoked at the same time the dataset was created.
1918 1917  Any editable ZFS property can also be set at creation time.
1919 1918  Multiple
1920 1919  .Fl o
1921 1920  options can be specified.
1922 1921  An error results if the same property is specified in multiple
1923 1922  .Fl o
1924 1923  options.
1925 1924  .It Fl p
1926 1925  Creates all the non-existing parent datasets.
1927 1926  Datasets created in this manner are automatically mounted according to the
1928 1927  .Sy mountpoint
1929 1928  property inherited from their parent.
1930 1929  Any property specified on the command line using the
1931 1930  .Fl o
1932 1931  option is ignored.
1933 1932  If the target filesystem already exists, the operation completes successfully.
1934 1933  .It Fl s
1935 1934  Creates a sparse volume with no reservation.
1936 1935  See
1937 1936  .Sy volsize
1938 1937  in the
1939 1938  .Sx Native Properties
1940 1939  section for more information about sparse volumes.
1941 1940  .El
1942 1941  .It Xo
1943 1942  .Nm
1944 1943  .Cm destroy
1945 1944  .Op Fl Rfnprv
1946 1945  .Ar filesystem Ns | Ns Ar volume
1947 1946  .Xc
1948 1947  Destroys the given dataset.
1949 1948  By default, the command unshares any file systems that are currently shared,
1950 1949  unmounts any file systems that are currently mounted, and refuses to destroy a
1951 1950  dataset that has active dependents
1952 1951  .Pq children or clones .
1953 1952  .Bl -tag -width "-R"
1954 1953  .It Fl R
1955 1954  Recursively destroy all dependents, including cloned file systems outside the
1956 1955  target hierarchy.
1957 1956  .It Fl f
1958 1957  Force an unmount of any file systems using the
1959 1958  .Nm unmount Fl f
1960 1959  command.
1961 1960  This option has no effect on non-file systems or unmounted file systems.
1962 1961  .It Fl n
1963 1962  Do a dry-run
1964 1963  .Pq Qq No-op
1965 1964  deletion.
1966 1965  No data will be deleted.
1967 1966  This is useful in conjunction with the
1968 1967  .Fl v
1969 1968  or
1970 1969  .Fl p
1971 1970  flags to determine what data would be deleted.
1972 1971  .It Fl p
1973 1972  Print machine-parsable verbose information about the deleted data.
1974 1973  .It Fl r
1975 1974  Recursively destroy all children.
1976 1975  .It Fl v
1977 1976  Print verbose information about the deleted data.
1978 1977  .El
1979 1978  .Pp
1980 1979  Extreme care should be taken when applying either the
1981 1980  .Fl r
1982 1981  or the
1983 1982  .Fl R
1984 1983  options, as they can destroy large portions of a pool and cause unexpected
1985 1984  behavior for mounted file systems in use.
1986 1985  .It Xo
1987 1986  .Nm
1988 1987  .Cm destroy
1989 1988  .Op Fl Rdnprv
1990 1989  .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns
1991 1990  .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ...
1992 1991  .Xc
1993 1992  The given snapshots are destroyed immediately if and only if the
1994 1993  .Nm zfs Cm destroy
1995 1994  command without the
1996 1995  .Fl d
1997 1996  option would have destroyed it.
1998 1997  Such immediate destruction would occur, for example, if the snapshot had no
1999 1998  clones and the user-initiated reference count were zero.
2000 1999  .Pp
2001 2000  If a snapshot does not qualify for immediate destruction, it is marked for
2002 2001  deferred deletion.
2003 2002  In this state, it exists as a usable, visible snapshot until both of the
2004 2003  preconditions listed above are met, at which point it is destroyed.
2005 2004  .Pp
2006 2005  An inclusive range of snapshots may be specified by separating the first and
2007 2006  last snapshots with a percent sign.
2008 2007  The first and/or last snapshots may be left blank, in which case the
2009 2008  filesystem's oldest or newest snapshot will be implied.
2010 2009  .Pp
2011 2010  Multiple snapshots
2012 2011  .Pq or ranges of snapshots
2013 2012  of the same filesystem or volume may be specified in a comma-separated list of
2014 2013  snapshots.
2015 2014  Only the snapshot's short name
2016 2015  .Po the part after the
2017 2016  .Sy @
2018 2017  .Pc
2019 2018  should be specified when using a range or comma-separated list to identify
2020 2019  multiple snapshots.
2021 2020  .Bl -tag -width "-R"
2022 2021  .It Fl R
2023 2022  Recursively destroy all clones of these snapshots, including the clones,
2024 2023  snapshots, and children.
2025 2024  If this flag is specified, the
2026 2025  .Fl d
2027 2026  flag will have no effect.
2028 2027  .It Fl d
2029 2028  Defer snapshot deletion.
2030 2029  .It Fl n
2031 2030  Do a dry-run
2032 2031  .Pq Qq No-op
2033 2032  deletion.
2034 2033  No data will be deleted.
2035 2034  This is useful in conjunction with the
2036 2035  .Fl p
2037 2036  or
2038 2037  .Fl v
2039 2038  flags to determine what data would be deleted.
2040 2039  .It Fl p
2041 2040  Print machine-parsable verbose information about the deleted data.
2042 2041  .It Fl r
2043 2042  Destroy
2044 2043  .Pq or mark for deferred deletion
2045 2044  all snapshots with this name in descendent file systems.
2046 2045  .It Fl v
2047 2046  Print verbose information about the deleted data.
2048 2047  .Pp
2049 2048  Extreme care should be taken when applying either the
2050 2049  .Fl r
2051 2050  or the
2052 2051  .Fl R
2053 2052  options, as they can destroy large portions of a pool and cause unexpected
2054 2053  behavior for mounted file systems in use.
2055 2054  .El
2056 2055  .It Xo
2057 2056  .Nm
2058 2057  .Cm destroy
2059 2058  .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark
2060 2059  .Xc
2061 2060  The given bookmark is destroyed.
2062 2061  .It Xo
2063 2062  .Nm
2064 2063  .Cm snapshot
2065 2064  .Op Fl r
2066 2065  .Oo Fl o Ar property Ns = Ns value Oc Ns ...
2067 2066  .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ...
2068 2067  .Xc
2069 2068  Creates snapshots with the given names.
2070 2069  All previous modifications by successful system calls to the file system are
2071 2070  part of the snapshots.
2072 2071  Snapshots are taken atomically, so that all snapshots correspond to the same
2073 2072  moment in time.
2074 2073  See the
2075 2074  .Sx Snapshots
2076 2075  section for details.
2077 2076  .Bl -tag -width "-o"
2078 2077  .It Fl o Ar property Ns = Ns Ar value
2079 2078  Sets the specified property; see
2080 2079  .Nm zfs Cm create
2081 2080  for details.
2082 2081  .It Fl r
2083 2082  Recursively create snapshots of all descendent datasets
2084 2083  .El
2085 2084  .It Xo
2086 2085  .Nm
2087 2086  .Cm rollback
2088 2087  .Op Fl Rfr
2089 2088  .Ar snapshot
2090 2089  .Xc
2091 2090  Roll back the given dataset to a previous snapshot.
2092 2091  When a dataset is rolled back, all data that has changed since the snapshot is
2093 2092  discarded, and the dataset reverts to the state at the time of the snapshot.
2094 2093  By default, the command refuses to roll back to a snapshot other than the most
2095 2094  recent one.
2096 2095  In order to do so, all intermediate snapshots and bookmarks must be destroyed by
2097 2096  specifying the
2098 2097  .Fl r
2099 2098  option.
2100 2099  .Pp
2101 2100  The
2102 2101  .Fl rR
2103 2102  options do not recursively destroy the child snapshots of a recursive snapshot.
2104 2103  Only direct snapshots of the specified filesystem are destroyed by either of
2105 2104  these options.
2106 2105  To completely roll back a recursive snapshot, you must rollback the individual
2107 2106  child snapshots.
2108 2107  .Bl -tag -width "-R"
2109 2108  .It Fl R
2110 2109  Destroy any more recent snapshots and bookmarks, as well as any clones of those
2111 2110  snapshots.
2112 2111  .It Fl f
2113 2112  Used with the
2114 2113  .Fl R
2115 2114  option to force an unmount of any clone file systems that are to be destroyed.
2116 2115  .It Fl r
2117 2116  Destroy any snapshots and bookmarks more recent than the one specified.
2118 2117  .El
2119 2118  .It Xo
2120 2119  .Nm
2121 2120  .Cm clone
2122 2121  .Op Fl p
2123 2122  .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
2124 2123  .Ar snapshot Ar filesystem Ns | Ns Ar volume
2125 2124  .Xc
2126 2125  Creates a clone of the given snapshot.
2127 2126  See the
2128 2127  .Sx Clones
2129 2128  section for details.
2130 2129  The target dataset can be located anywhere in the ZFS hierarchy, and is created
2131 2130  as the same type as the original.
2132 2131  .Bl -tag -width "-o"
2133 2132  .It Fl o Ar property Ns = Ns Ar value
2134 2133  Sets the specified property; see
2135 2134  .Nm zfs Cm create
2136 2135  for details.
2137 2136  .It Fl p
2138 2137  Creates all the non-existing parent datasets.
2139 2138  Datasets created in this manner are automatically mounted according to the
2140 2139  .Sy mountpoint
2141 2140  property inherited from their parent.
2142 2141  If the target filesystem or volume already exists, the operation completes
2143 2142  successfully.
2144 2143  .El
2145 2144  .It Xo
2146 2145  .Nm
2147 2146  .Cm promote
2148 2147  .Ar clone-filesystem
2149 2148  .Xc
2150 2149  Promotes a clone file system to no longer be dependent on its
2151 2150  .Qq origin
2152 2151  snapshot.
2153 2152  This makes it possible to destroy the file system that the clone was created
2154 2153  from.
2155 2154  The clone parent-child dependency relationship is reversed, so that the origin
2156 2155  file system becomes a clone of the specified file system.
2157 2156  .Pp
2158 2157  The snapshot that was cloned, and any snapshots previous to this snapshot, are
2159 2158  now owned by the promoted clone.
2160 2159  The space they use moves from the origin file system to the promoted clone, so
2161 2160  enough space must be available to accommodate these snapshots.
2162 2161  No new space is consumed by this operation, but the space accounting is
2163 2162  adjusted.
2164 2163  The promoted clone must not have any conflicting snapshot names of its own.
2165 2164  The
2166 2165  .Cm rename
2167 2166  subcommand can be used to rename any conflicting snapshots.
2168 2167  .It Xo
2169 2168  .Nm
2170 2169  .Cm rename
2171 2170  .Op Fl f
2172 2171  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2173 2172  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2174 2173  .Xc
2175 2174  .It Xo
2176 2175  .Nm
2177 2176  .Cm rename
2178 2177  .Op Fl fp
2179 2178  .Ar filesystem Ns | Ns Ar volume
2180 2179  .Ar filesystem Ns | Ns Ar volume
2181 2180  .Xc
2182 2181  Renames the given dataset.
2183 2182  The new target can be located anywhere in the ZFS hierarchy, with the exception
2184 2183  of snapshots.
2185 2184  Snapshots can only be renamed within the parent file system or volume.
2186 2185  When renaming a snapshot, the parent file system of the snapshot does not need
2187 2186  to be specified as part of the second argument.
2188 2187  Renamed file systems can inherit new mount points, in which case they are
2189 2188  unmounted and remounted at the new mount point.
2190 2189  .Bl -tag -width "-a"
2191 2190  .It Fl f
2192 2191  Force unmount any filesystems that need to be unmounted in the process.
2193 2192  .It Fl p
2194 2193  Creates all the nonexistent parent datasets.
2195 2194  Datasets created in this manner are automatically mounted according to the
2196 2195  .Sy mountpoint
2197 2196  property inherited from their parent.
2198 2197  .El
2199 2198  .It Xo
2200 2199  .Nm
2201 2200  .Cm rename
2202 2201  .Fl r
2203 2202  .Ar snapshot Ar snapshot
2204 2203  .Xc
2205 2204  Recursively rename the snapshots of all descendent datasets.
2206 2205  Snapshots are the only dataset that can be renamed recursively.
2207 2206  .It Xo
2208 2207  .Nm
2209 2208  .Cm list
2210 2209  .Op Fl r Ns | Ns Fl d Ar depth
2211 2210  .Op Fl Hp
2212 2211  .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc
2213 2212  .Oo Fl s Ar property Oc Ns ...
2214 2213  .Oo Fl S Ar property Oc Ns ...
2215 2214  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2216 2215  .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ...
2217 2216  .Xc
2218 2217  Lists the property information for the given datasets in tabular form.
2219 2218  If specified, you can list property information by the absolute pathname or the
2220 2219  relative pathname.
2221 2220  By default, all file systems and volumes are displayed.
2222 2221  Snapshots are displayed if the
2223 2222  .Sy listsnaps
2224 2223  property is
2225 2224  .Sy on
2226 2225  .Po the default is
2227 2226  .Sy off
2228 2227  .Pc .
2229 2228  The following fields are displayed,
2230 2229  .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns
2231 2230  .Sy mountpoint .
2232 2231  .Bl -tag -width "-H"
2233 2232  .It Fl H
2234 2233  Used for scripting mode.
2235 2234  Do not print headers and separate fields by a single tab instead of arbitrary
2236 2235  white space.
2237 2236  .It Fl S Ar property
2238 2237  Same as the
2239 2238  .Fl s
2240 2239  option, but sorts by property in descending order.
2241 2240  .It Fl d Ar depth
2242 2241  Recursively display any children of the dataset, limiting the recursion to
2243 2242  .Ar depth .
2244 2243  A
2245 2244  .Ar depth
2246 2245  of
2247 2246  .Sy 1
2248 2247  will display only the dataset and its direct children.
2249 2248  .It Fl o Ar property
2250 2249  A comma-separated list of properties to display.
2251 2250  The property must be:
2252 2251  .Bl -bullet
2253 2252  .It
2254 2253  One of the properties described in the
2255 2254  .Sx Native Properties
2256 2255  section
2257 2256  .It
2258 2257  A user property
2259 2258  .It
2260 2259  The value
2261 2260  .Sy name
2262 2261  to display the dataset name
2263 2262  .It
2264 2263  The value
2265 2264  .Sy space
2266 2265  to display space usage properties on file systems and volumes.
2267 2266  This is a shortcut for specifying
2268 2267  .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns
2269 2268  .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t
2270 2269  .Sy filesystem Ns \&, Ns Sy volume
2271 2270  syntax.
2272 2271  .El
2273 2272  .It Fl p
2274 2273  Display numbers in parsable
2275 2274  .Pq exact
2276 2275  values.
2277 2276  .It Fl r
2278 2277  Recursively display any children of the dataset on the command line.
2279 2278  .It Fl s Ar property
2280 2279  A property for sorting the output by column in ascending order based on the
2281 2280  value of the property.
2282 2281  The property must be one of the properties described in the
2283 2282  .Sx Properties
2284 2283  section, or the special value
2285 2284  .Sy name
2286 2285  to sort by the dataset name.
2287 2286  Multiple properties can be specified at one time using multiple
2288 2287  .Fl s
2289 2288  property options.
2290 2289  Multiple
2291 2290  .Fl s
2292 2291  options are evaluated from left to right in decreasing order of importance.
2293 2292  The following is a list of sorting criteria:
2294 2293  .Bl -bullet
2295 2294  .It
2296 2295  Numeric types sort in numeric order.
2297 2296  .It
2298 2297  String types sort in alphabetical order.
2299 2298  .It
2300 2299  Types inappropriate for a row sort that row to the literal bottom, regardless of
2301 2300  the specified ordering.
2302 2301  .El
2303 2302  .Pp
2304 2303  If no sorting options are specified the existing behavior of
2305 2304  .Nm zfs Cm list
2306 2305  is preserved.
2307 2306  .It Fl t Ar type
2308 2307  A comma-separated list of types to display, where
2309 2308  .Ar type
2310 2309  is one of
2311 2310  .Sy filesystem ,
2312 2311  .Sy snapshot ,
2313 2312  .Sy volume ,
2314 2313  .Sy bookmark ,
2315 2314  or
2316 2315  .Sy all .
2317 2316  For example, specifying
2318 2317  .Fl t Sy snapshot
2319 2318  displays only snapshots.
2320 2319  .El
2321 2320  .It Xo
2322 2321  .Nm
2323 2322  .Cm set
2324 2323  .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ...
2325 2324  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2326 2325  .Xc
2327 2326  Sets the property or list of properties to the given value(s) for each dataset.
2328 2327  Only some properties can be edited.
2329 2328  See the
2330 2329  .Sx Properties
2331 2330  section for more information on what properties can be set and acceptable
2332 2331  values.
2333 2332  Numeric values can be specified as exact values, or in a human-readable form
2334 2333  with a suffix of
2335 2334  .Sy B , K , M , G , T , P , E , Z
2336 2335  .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes,
2337 2336  or zettabytes, respectively
2338 2337  .Pc .
2339 2338  User properties can be set on snapshots.
2340 2339  For more information, see the
2341 2340  .Sx User Properties
2342 2341  section.
2343 2342  .It Xo
2344 2343  .Nm
2345 2344  .Cm get
2346 2345  .Op Fl r Ns | Ns Fl d Ar depth
2347 2346  .Op Fl Hp
2348 2347  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2349 2348  .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc
2350 2349  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2351 2350  .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ...
2352 2351  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ...
2353 2352  .Xc
2354 2353  Displays properties for the given datasets.
2355 2354  If no datasets are specified, then the command displays properties for all
2356 2355  datasets on the system.
2357 2356  For each property, the following columns are displayed:
2358 2357  .Bd -literal
2359 2358      name      Dataset name
2360 2359      property  Property name
2361 2360      value     Property value
2362 2361      source    Property source.  Can either be local, default,
2363 2362                temporary, inherited, or none (-).
2364 2363  .Ed
2365 2364  .Pp
2366 2365  All columns are displayed by default, though this can be controlled by using the
2367 2366  .Fl o
2368 2367  option.
2369 2368  This command takes a comma-separated list of properties as described in the
2370 2369  .Sx Native Properties
2371 2370  and
2372 2371  .Sx User Properties
2373 2372  sections.
2374 2373  .Pp
2375 2374  The special value
2376 2375  .Sy all
2377 2376  can be used to display all properties that apply to the given dataset's type
2378 2377  .Pq filesystem, volume, snapshot, or bookmark .
2379 2378  .Bl -tag -width "-H"
2380 2379  .It Fl H
2381 2380  Display output in a form more easily parsed by scripts.
2382 2381  Any headers are omitted, and fields are explicitly separated by a single tab
2383 2382  instead of an arbitrary amount of space.
2384 2383  .It Fl d Ar depth
2385 2384  Recursively display any children of the dataset, limiting the recursion to
2386 2385  .Ar depth .
2387 2386  A depth of
2388 2387  .Sy 1
2389 2388  will display only the dataset and its direct children.
2390 2389  .It Fl o Ar field
2391 2390  A comma-separated list of columns to display.
2392 2391  .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source
2393 2392  is the default value.
2394 2393  .It Fl p
2395 2394  Display numbers in parsable
2396 2395  .Pq exact
2397 2396  values.
2398 2397  .It Fl r
2399 2398  Recursively display properties for any children.
2400 2399  .It Fl s Ar source
2401 2400  A comma-separated list of sources to display.
2402 2401  Those properties coming from a source other than those in this list are ignored.
2403 2402  Each source must be one of the following:
2404 2403  .Sy local ,
2405 2404  .Sy default ,
2406 2405  .Sy inherited ,
2407 2406  .Sy temporary ,
2408 2407  and
2409 2408  .Sy none .
2410 2409  The default value is all sources.
2411 2410  .It Fl t Ar type
2412 2411  A comma-separated list of types to display, where
2413 2412  .Ar type
2414 2413  is one of
2415 2414  .Sy filesystem ,
2416 2415  .Sy snapshot ,
2417 2416  .Sy volume ,
2418 2417  .Sy bookmark ,
2419 2418  or
2420 2419  .Sy all .
2421 2420  .El
2422 2421  .It Xo
2423 2422  .Nm
2424 2423  .Cm inherit
2425 2424  .Op Fl rS
2426 2425  .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ...
2427 2426  .Xc
2428 2427  Clears the specified property, causing it to be inherited from an ancestor,
2429 2428  restored to default if no ancestor has the property set, or with the
2430 2429  .Fl S
2431 2430  option reverted to the received value if one exists.
2432 2431  See the
2433 2432  .Sx Properties
2434 2433  section for a listing of default values, and details on which properties can be
2435 2434  inherited.
2436 2435  .Bl -tag -width "-r"
2437 2436  .It Fl r
2438 2437  Recursively inherit the given property for all children.
2439 2438  .It Fl S
2440 2439  Revert the property to the received value if one exists; otherwise operate as
2441 2440  if the
2442 2441  .Fl S
2443 2442  option was not specified.
2444 2443  .El
2445 2444  .It Xo
2446 2445  .Nm
2447 2446  .Cm remap
2448 2447  .Ar filesystem Ns | Ns Ar volume
2449 2448  .Xc
2450 2449  Remap the indirect blocks in the given filesystem or volume so that they no
2451 2450  longer reference blocks on previously removed vdevs and we can eventually
2452 2451  shrink the size of the indirect mapping objects for the previously removed
2453 2452  vdevs. Note that remapping all blocks might not be possible and that
2454 2453  references from snapshots will still exist and cannot be remapped.
2455 2454  .It Xo
2456 2455  .Nm
2457 2456  .Cm upgrade
2458 2457  .Xc
2459 2458  Displays a list of file systems that are not the most recent version.
2460 2459  .It Xo
2461 2460  .Nm
2462 2461  .Cm upgrade
2463 2462  .Fl v
2464 2463  .Xc
2465 2464  Displays a list of currently supported file system versions.
2466 2465  .It Xo
2467 2466  .Nm
2468 2467  .Cm upgrade
2469 2468  .Op Fl r
2470 2469  .Op Fl V Ar version
2471 2470  .Fl a | Ar filesystem
2472 2471  .Xc
2473 2472  Upgrades file systems to a new on-disk version.
2474 2473  Once this is done, the file systems will no longer be accessible on systems
2475 2474  running older versions of the software.
2476 2475  .Nm zfs Cm send
2477 2476  streams generated from new snapshots of these file systems cannot be accessed on
2478 2477  systems running older versions of the software.
2479 2478  .Pp
2480 2479  In general, the file system version is independent of the pool version.
2481 2480  See
2482 2481  .Xr zpool 1M
2483 2482  for information on the
2484 2483  .Nm zpool Cm upgrade
2485 2484  command.
2486 2485  .Pp
2487 2486  In some cases, the file system version and the pool version are interrelated and
2488 2487  the pool version must be upgraded before the file system version can be
2489 2488  upgraded.
2490 2489  .Bl -tag -width "-V"
2491 2490  .It Fl V Ar version
2492 2491  Upgrade to the specified
2493 2492  .Ar version .
2494 2493  If the
2495 2494  .Fl V
2496 2495  flag is not specified, this command upgrades to the most recent version.
2497 2496  This
2498 2497  option can only be used to increase the version number, and only up to the most
2499 2498  recent version supported by this software.
2500 2499  .It Fl a
2501 2500  Upgrade all file systems on all imported pools.
2502 2501  .It Ar filesystem
2503 2502  Upgrade the specified file system.
2504 2503  .It Fl r
2505 2504  Upgrade the specified file system and all descendent file systems.
2506 2505  .El
2507 2506  .It Xo
2508 2507  .Nm
2509 2508  .Cm userspace
2510 2509  .Op Fl Hinp
2511 2510  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2512 2511  .Oo Fl s Ar field Oc Ns ...
2513 2512  .Oo Fl S Ar field Oc Ns ...
2514 2513  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2515 2514  .Ar filesystem Ns | Ns Ar snapshot
2516 2515  .Xc
2517 2516  Displays space consumed by, and quotas on, each user in the specified filesystem
2518 2517  or snapshot.
2519 2518  This corresponds to the
2520 2519  .Sy userused@ Ns Em user
2521 2520  and
2522 2521  .Sy userquota@ Ns Em user
2523 2522  properties.
2524 2523  .Bl -tag -width "-H"
2525 2524  .It Fl H
2526 2525  Do not print headers, use tab-delimited output.
2527 2526  .It Fl S Ar field
2528 2527  Sort by this field in reverse order.
2529 2528  See
2530 2529  .Fl s .
2531 2530  .It Fl i
2532 2531  Translate SID to POSIX ID.
2533 2532  The POSIX ID may be ephemeral if no mapping exists.
2534 2533  Normal POSIX interfaces
2535 2534  .Po for example,
2536 2535  .Xr stat 2 ,
2537 2536  .Nm ls Fl l
2538 2537  .Pc
2539 2538  perform this translation, so the
2540 2539  .Fl i
2541 2540  option allows the output from
2542 2541  .Nm zfs Cm userspace
2543 2542  to be compared directly with those utilities.
2544 2543  However,
2545 2544  .Fl i
2546 2545  may lead to confusion if some files were created by an SMB user before a
2547 2546  SMB-to-POSIX name mapping was established.
2548 2547  In such a case, some files will be owned by the SMB entity and some by the POSIX
2549 2548  entity.
2550 2549  However, the
2551 2550  .Fl i
2552 2551  option will report that the POSIX entity has the total usage and quota for both.
2553 2552  .It Fl n
2554 2553  Print numeric ID instead of user/group name.
2555 2554  .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ...
2556 2555  Display only the specified fields from the following set:
2557 2556  .Sy type ,
2558 2557  .Sy name ,
2559 2558  .Sy used ,
2560 2559  .Sy quota .
2561 2560  The default is to display all fields.
2562 2561  .It Fl p
2563 2562  Use exact
2564 2563  .Pq parsable
2565 2564  numeric output.
2566 2565  .It Fl s Ar field
2567 2566  Sort output by this field.
2568 2567  The
2569 2568  .Fl s
2570 2569  and
2571 2570  .Fl S
2572 2571  flags may be specified multiple times to sort first by one field, then by
2573 2572  another.
2574 2573  The default is
2575 2574  .Fl s Sy type Fl s Sy name .
2576 2575  .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ...
2577 2576  Print only the specified types from the following set:
2578 2577  .Sy all ,
2579 2578  .Sy posixuser ,
2580 2579  .Sy smbuser ,
2581 2580  .Sy posixgroup ,
2582 2581  .Sy smbgroup .
2583 2582  The default is
2584 2583  .Fl t Sy posixuser Ns \&, Ns Sy smbuser .
2585 2584  The default can be changed to include group types.
2586 2585  .El
2587 2586  .It Xo
2588 2587  .Nm
2589 2588  .Cm groupspace
2590 2589  .Op Fl Hinp
2591 2590  .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc
2592 2591  .Oo Fl s Ar field Oc Ns ...
2593 2592  .Oo Fl S Ar field Oc Ns ...
2594 2593  .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc
2595 2594  .Ar filesystem Ns | Ns Ar snapshot
2596 2595  .Xc
2597 2596  Displays space consumed by, and quotas on, each group in the specified
2598 2597  filesystem or snapshot.
2599 2598  This subcommand is identical to
2600 2599  .Nm zfs Cm userspace ,
2601 2600  except that the default types to display are
2602 2601  .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup .
2603 2602  .It Xo
2604 2603  .Nm
2605 2604  .Cm mount
2606 2605  .Xc
2607 2606  Displays all ZFS file systems currently mounted.
2608 2607  .It Xo
2609 2608  .Nm
2610 2609  .Cm mount
2611 2610  .Op Fl Ov
2612 2611  .Op Fl o Ar options
2613 2612  .Fl a | Ar filesystem
2614 2613  .Xc
2615 2614  Mounts ZFS file systems.
2616 2615  .Bl -tag -width "-O"
2617 2616  .It Fl O
2618 2617  Perform an overlay mount.
2619 2618  See
2620 2619  .Xr mount 1M
2621 2620  for more information.
2622 2621  .It Fl a
2623 2622  Mount all available ZFS file systems.
2624 2623  Invoked automatically as part of the boot process.
2625 2624  .It Ar filesystem
2626 2625  Mount the specified filesystem.
2627 2626  .It Fl o Ar options
2628 2627  An optional, comma-separated list of mount options to use temporarily for the
2629 2628  duration of the mount.
2630 2629  See the
2631 2630  .Sx Temporary Mount Point Properties
2632 2631  section for details.
2633 2632  .It Fl v
2634 2633  Report mount progress.
2635 2634  .El
2636 2635  .It Xo
2637 2636  .Nm
2638 2637  .Cm unmount
2639 2638  .Op Fl f
2640 2639  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2641 2640  .Xc
2642 2641  Unmounts currently mounted ZFS file systems.
2643 2642  .Bl -tag -width "-a"
2644 2643  .It Fl a
2645 2644  Unmount all available ZFS file systems.
2646 2645  Invoked automatically as part of the shutdown process.
2647 2646  .It Ar filesystem Ns | Ns Ar mountpoint
2648 2647  Unmount the specified filesystem.
2649 2648  The command can also be given a path to a ZFS file system mount point on the
2650 2649  system.
2651 2650  .It Fl f
2652 2651  Forcefully unmount the file system, even if it is currently in use.
2653 2652  .El
2654 2653  .It Xo
2655 2654  .Nm
2656 2655  .Cm share
2657 2656  .Fl a | Ar filesystem
2658 2657  .Xc
2659 2658  Shares available ZFS file systems.
2660 2659  .Bl -tag -width "-a"
2661 2660  .It Fl a
2662 2661  Share all available ZFS file systems.
2663 2662  Invoked automatically as part of the boot process.
2664 2663  .It Ar filesystem
2665 2664  Share the specified filesystem according to the
2666 2665  .Sy sharenfs
2667 2666  and
2668 2667  .Sy sharesmb
2669 2668  properties.
2670 2669  File systems are shared when the
2671 2670  .Sy sharenfs
2672 2671  or
2673 2672  .Sy sharesmb
2674 2673  property is set.
2675 2674  .El
2676 2675  .It Xo
2677 2676  .Nm
2678 2677  .Cm unshare
2679 2678  .Fl a | Ar filesystem Ns | Ns Ar mountpoint
2680 2679  .Xc
2681 2680  Unshares currently shared ZFS file systems.
2682 2681  .Bl -tag -width "-a"
2683 2682  .It Fl a
2684 2683  Unshare all available ZFS file systems.
2685 2684  Invoked automatically as part of the shutdown process.
2686 2685  .It Ar filesystem Ns | Ns Ar mountpoint
2687 2686  Unshare the specified filesystem.
2688 2687  The command can also be given a path to a ZFS file system shared on the system.
2689 2688  .El
2690 2689  .It Xo
2691 2690  .Nm
2692 2691  .Cm bookmark
2693 2692  .Ar snapshot bookmark
2694 2693  .Xc
2695 2694  Creates a bookmark of the given snapshot.
2696 2695  Bookmarks mark the point in time when the snapshot was created, and can be used
2697 2696  as the incremental source for a
2698 2697  .Nm zfs Cm send
2699 2698  command.
2700 2699  .Pp
2701 2700  This feature must be enabled to be used.
2702 2701  See
2703 2702  .Xr zpool-features 5
2704 2703  for details on ZFS feature flags and the
2705 2704  .Sy bookmarks
2706 2705  feature.
2707 2706  .It Xo
2708 2707  .Nm
2709 2708  .Cm send
2710 2709  .Op Fl DLPRcenpv
2711 2710  .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot
2712 2711  .Ar snapshot
2713 2712  .Xc
2714 2713  Creates a stream representation of the second
2715 2714  .Ar snapshot ,
2716 2715  which is written to standard output.
2717 2716  The output can be redirected to a file or to a different system
2718 2717  .Po for example, using
2719 2718  .Xr ssh 1
2720 2719  .Pc .
2721 2720  By default, a full stream is generated.
2722 2721  .Bl -tag -width "-D"
2723 2722  .It Fl D, -dedup
2724 2723  Generate a deduplicated stream.
2725 2724  Blocks which would have been sent multiple times in the send stream will only be
2726 2725  sent once.
2727 2726  The receiving system must also support this feature to receive a deduplicated
2728 2727  stream.
2729 2728  This flag can be used regardless of the dataset's
2730 2729  .Sy dedup
2731 2730  property, but performance will be much better if the filesystem uses a
2732 2731  dedup-capable checksum
2733 2732  .Po for example,
2734 2733  .Sy sha256
2735 2734  .Pc .
2736 2735  .It Fl I Ar snapshot
2737 2736  Generate a stream package that sends all intermediary snapshots from the first
2738 2737  snapshot to the second snapshot.
2739 2738  For example,
2740 2739  .Fl I Em @a Em fs@d
2741 2740  is similar to
2742 2741  .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d .
2743 2742  The incremental source may be specified as with the
2744 2743  .Fl i
2745 2744  option.
2746 2745  .It Fl L, -large-block
2747 2746  Generate a stream which may contain blocks larger than 128KB.
2748 2747  This flag has no effect if the
2749 2748  .Sy large_blocks
2750 2749  pool feature is disabled, or if the
2751 2750  .Sy recordsize
2752 2751  property of this filesystem has never been set above 128KB.
2753 2752  The receiving system must have the
2754 2753  .Sy large_blocks
2755 2754  pool feature enabled as well.
2756 2755  See
2757 2756  .Xr zpool-features 5
2758 2757  for details on ZFS feature flags and the
2759 2758  .Sy large_blocks
2760 2759  feature.
2761 2760  .It Fl P, -parsable
2762 2761  Print machine-parsable verbose information about the stream package generated.
2763 2762  .It Fl R, -replicate
2764 2763  Generate a replication stream package, which will replicate the specified
2765 2764  file system, and all descendent file systems, up to the named snapshot.
2766 2765  When received, all properties, snapshots, descendent file systems, and clones
2767 2766  are preserved.
2768 2767  .Pp
2769 2768  If the
2770 2769  .Fl i
2771 2770  or
2772 2771  .Fl I
2773 2772  flags are used in conjunction with the
2774 2773  .Fl R
2775 2774  flag, an incremental replication stream is generated.
2776 2775  The current values of properties, and current snapshot and file system names are
2777 2776  set when the stream is received.
2778 2777  If the
2779 2778  .Fl F
2780 2779  flag is specified when this stream is received, snapshots and file systems that
2781 2780  do not exist on the sending side are destroyed.
2782 2781  .It Fl e, -embed
2783 2782  Generate a more compact stream by using
2784 2783  .Sy WRITE_EMBEDDED
2785 2784  records for blocks which are stored more compactly on disk by the
2786 2785  .Sy embedded_data
2787 2786  pool feature.
2788 2787  This flag has no effect if the
2789 2788  .Sy embedded_data
2790 2789  feature is disabled.
2791 2790  The receiving system must have the
2792 2791  .Sy embedded_data
2793 2792  feature enabled.
2794 2793  If the
2795 2794  .Sy lz4_compress
2796 2795  feature is active on the sending system, then the receiving system must have
2797 2796  that feature enabled as well.
2798 2797  See
2799 2798  .Xr zpool-features 5
2800 2799  for details on ZFS feature flags and the
2801 2800  .Sy embedded_data
2802 2801  feature.
2803 2802  .It Fl c, -compressed
2804 2803  Generate a more compact stream by using compressed WRITE records for blocks
2805 2804  which are compressed on disk and in memory
2806 2805  .Po see the
2807 2806  .Sy compression
2808 2807  property for details
2809 2808  .Pc .
2810 2809  If the
2811 2810  .Sy lz4_compress
2812 2811  feature is active on the sending system, then the receiving system must have
2813 2812  that feature enabled as well.
2814 2813  If the
2815 2814  .Sy large_blocks
2816 2815  feature is enabled on the sending system but the
2817 2816  .Fl L
2818 2817  option is not supplied in conjunction with
2819 2818  .Fl c ,
2820 2819  then the data will be decompressed before sending so it can be split into
2821 2820  smaller block sizes.
2822 2821  .It Fl i Ar snapshot
2823 2822  Generate an incremental stream from the first
2824 2823  .Ar snapshot
2825 2824  .Pq the incremental source
2826 2825  to the second
2827 2826  .Ar snapshot
2828 2827  .Pq the incremental target .
2829 2828  The incremental source can be specified as the last component of the snapshot
2830 2829  name
2831 2830  .Po the
2832 2831  .Sy @
2833 2832  character and following
2834 2833  .Pc
2835 2834  and it is assumed to be from the same file system as the incremental target.
2836 2835  .Pp
2837 2836  If the destination is a clone, the source may be the origin snapshot, which must
2838 2837  be fully specified
2839 2838  .Po for example,
2840 2839  .Em pool/fs@origin ,
2841 2840  not just
2842 2841  .Em @origin
2843 2842  .Pc .
2844 2843  .It Fl n, -dryrun
2845 2844  Do a dry-run
2846 2845  .Pq Qq No-op
2847 2846  send.
2848 2847  Do not generate any actual send data.
2849 2848  This is useful in conjunction with the
2850 2849  .Fl v
2851 2850  or
2852 2851  .Fl P
2853 2852  flags to determine what data will be sent.
2854 2853  In this case, the verbose output will be written to standard output
2855 2854  .Po contrast with a non-dry-run, where the stream is written to standard output
2856 2855  and the verbose output goes to standard error
2857 2856  .Pc .
2858 2857  .It Fl p, -props
2859 2858  Include the dataset's properties in the stream.
2860 2859  This flag is implicit when
2861 2860  .Fl R
2862 2861  is specified.
2863 2862  The receiving system must also support this feature.
2864 2863  .It Fl v, -verbose
2865 2864  Print verbose information about the stream package generated.
2866 2865  This information includes a per-second report of how much data has been sent.
2867 2866  .Pp
2868 2867  The format of the stream is committed.
2869 2868  You will be able to receive your streams on future versions of ZFS .
2870 2869  .El
2871 2870  .It Xo
2872 2871  .Nm
2873 2872  .Cm send
2874 2873  .Op Fl Lce
2875 2874  .Op Fl i Ar snapshot Ns | Ns Ar bookmark
2876 2875  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2877 2876  .Xc
2878 2877  Generate a send stream, which may be of a filesystem, and may be incremental
2879 2878  from a bookmark.
2880 2879  If the destination is a filesystem or volume, the pool must be read-only, or the
2881 2880  filesystem must not be mounted.
2882 2881  When the stream generated from a filesystem or volume is received, the default
2883 2882  snapshot name will be
2884 2883  .Qq --head-- .
2885 2884  .Bl -tag -width "-L"
2886 2885  .It Fl L, -large-block
2887 2886  Generate a stream which may contain blocks larger than 128KB.
2888 2887  This flag has no effect if the
2889 2888  .Sy large_blocks
2890 2889  pool feature is disabled, or if the
2891 2890  .Sy recordsize
2892 2891  property of this filesystem has never been set above 128KB.
2893 2892  The receiving system must have the
2894 2893  .Sy large_blocks
2895 2894  pool feature enabled as well.
2896 2895  See
2897 2896  .Xr zpool-features 5
2898 2897  for details on ZFS feature flags and the
2899 2898  .Sy large_blocks
2900 2899  feature.
2901 2900  .It Fl c, -compressed
2902 2901  Generate a more compact stream by using compressed WRITE records for blocks
2903 2902  which are compressed on disk and in memory
2904 2903  .Po see the
2905 2904  .Sy compression
2906 2905  property for details
2907 2906  .Pc .
2908 2907  If the
2909 2908  .Sy lz4_compress
2910 2909  feature is active on the sending system, then the receiving system must have
2911 2910  that feature enabled as well.
2912 2911  If the
2913 2912  .Sy large_blocks
2914 2913  feature is enabled on the sending system but the
2915 2914  .Fl L
2916 2915  option is not supplied in conjunction with
2917 2916  .Fl c ,
2918 2917  then the data will be decompressed before sending so it can be split into
2919 2918  smaller block sizes.
2920 2919  .It Fl e, -embed
2921 2920  Generate a more compact stream by using
2922 2921  .Sy WRITE_EMBEDDED
2923 2922  records for blocks which are stored more compactly on disk by the
2924 2923  .Sy embedded_data
2925 2924  pool feature.
2926 2925  This flag has no effect if the
2927 2926  .Sy embedded_data
2928 2927  feature is disabled.
2929 2928  The receiving system must have the
2930 2929  .Sy embedded_data
2931 2930  feature enabled.
2932 2931  If the
2933 2932  .Sy lz4_compress
2934 2933  feature is active on the sending system, then the receiving system must have
2935 2934  that feature enabled as well.
2936 2935  See
2937 2936  .Xr zpool-features 5
2938 2937  for details on ZFS feature flags and the
2939 2938  .Sy embedded_data
2940 2939  feature.
2941 2940  .It Fl i Ar snapshot Ns | Ns Ar bookmark
2942 2941  Generate an incremental send stream.
2943 2942  The incremental source must be an earlier snapshot in the destination's history.
2944 2943  It will commonly be an earlier snapshot in the destination's file system, in
2945 2944  which case it can be specified as the last component of the name
2946 2945  .Po the
2947 2946  .Sy #
2948 2947  or
2949 2948  .Sy @
2950 2949  character and following
2951 2950  .Pc .
2952 2951  .Pp
2953 2952  If the incremental target is a clone, the incremental source can be the origin
2954 2953  snapshot, or an earlier snapshot in the origin's filesystem, or the origin's
2955 2954  origin, etc.
2956 2955  .El
2957 2956  .It Xo
2958 2957  .Nm
2959 2958  .Cm send
2960 2959  .Op Fl Penv
2961 2960  .Fl t
2962 2961  .Ar receive_resume_token
2963 2962  .Xc
2964 2963  Creates a send stream which resumes an interrupted receive.
2965 2964  The
2966 2965  .Ar receive_resume_token
2967 2966  is the value of this property on the filesystem or volume that was being
2968 2967  received into.
2969 2968  See the documentation for
2970 2969  .Sy zfs receive -s
2971 2970  for more details.
2972 2971  .It Xo
2973 2972  .Nm
2974 2973  .Cm receive
2975 2974  .Op Fl Fnsuv
2976 2975  .Op Fl o Sy origin Ns = Ns Ar snapshot
2977 2976  .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot
2978 2977  .Xc
2979 2978  .It Xo
2980 2979  .Nm
2981 2980  .Cm receive
2982 2981  .Op Fl Fnsuv
2983 2982  .Op Fl d Ns | Ns Fl e
2984 2983  .Op Fl o Sy origin Ns = Ns Ar snapshot
2985 2984  .Ar filesystem
2986 2985  .Xc
2987 2986  Creates a snapshot whose contents are as specified in the stream provided on
2988 2987  standard input.
2989 2988  If a full stream is received, then a new file system is created as well.
2990 2989  Streams are created using the
2991 2990  .Nm zfs Cm send
2992 2991  subcommand, which by default creates a full stream.
2993 2992  .Nm zfs Cm recv
2994 2993  can be used as an alias for
2995 2994  .Nm zfs Cm receive.
2996 2995  .Pp
2997 2996  If an incremental stream is received, then the destination file system must
2998 2997  already exist, and its most recent snapshot must match the incremental stream's
2999 2998  source.
3000 2999  For
3001 3000  .Sy zvols ,
3002 3001  the destination device link is destroyed and recreated, which means the
3003 3002  .Sy zvol
3004 3003  cannot be accessed during the
3005 3004  .Cm receive
3006 3005  operation.
3007 3006  .Pp
3008 3007  When a snapshot replication package stream that is generated by using the
3009 3008  .Nm zfs Cm send Fl R
3010 3009  command is received, any snapshots that do not exist on the sending location are
3011 3010  destroyed by using the
3012 3011  .Nm zfs Cm destroy Fl d
3013 3012  command.
3014 3013  .Pp
3015 3014  The name of the snapshot
3016 3015  .Pq and file system, if a full stream is received
3017 3016  that this subcommand creates depends on the argument type and the use of the
3018 3017  .Fl d
3019 3018  or
3020 3019  .Fl e
3021 3020  options.
3022 3021  .Pp
3023 3022  If the argument is a snapshot name, the specified
3024 3023  .Ar snapshot
3025 3024  is created.
3026 3025  If the argument is a file system or volume name, a snapshot with the same name
3027 3026  as the sent snapshot is created within the specified
3028 3027  .Ar filesystem
3029 3028  or
3030 3029  .Ar volume .
3031 3030  If neither of the
3032 3031  .Fl d
3033 3032  or
3034 3033  .Fl e
3035 3034  options are specified, the provided target snapshot name is used exactly as
3036 3035  provided.
3037 3036  .Pp
3038 3037  The
3039 3038  .Fl d
3040 3039  and
3041 3040  .Fl e
3042 3041  options cause the file system name of the target snapshot to be determined by
3043 3042  appending a portion of the sent snapshot's name to the specified target
3044 3043  .Ar filesystem .
3045 3044  If the
3046 3045  .Fl d
3047 3046  option is specified, all but the first element of the sent snapshot's file
3048 3047  system path
3049 3048  .Pq usually the pool name
3050 3049  is used and any required intermediate file systems within the specified one are
3051 3050  created.
3052 3051  If the
3053 3052  .Fl e
3054 3053  option is specified, then only the last element of the sent snapshot's file
3055 3054  system name
3056 3055  .Pq i.e. the name of the source file system itself
3057 3056  is used as the target file system name.
3058 3057  .Bl -tag -width "-F"
3059 3058  .It Fl F
3060 3059  Force a rollback of the file system to the most recent snapshot before
3061 3060  performing the receive operation.
3062 3061  If receiving an incremental replication stream
3063 3062  .Po for example, one generated by
3064 3063  .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I
3065 3064  .Pc ,
3066 3065  destroy snapshots and file systems that do not exist on the sending side.
3067 3066  .It Fl d
3068 3067  Discard the first element of the sent snapshot's file system name, using the
3069 3068  remaining elements to determine the name of the target file system for the new
3070 3069  snapshot as described in the paragraph above.
3071 3070  .It Fl e
3072 3071  Discard all but the last element of the sent snapshot's file system name, using
3073 3072  that element to determine the name of the target file system for the new
3074 3073  snapshot as described in the paragraph above.
3075 3074  .It Fl n
3076 3075  Do not actually receive the stream.
3077 3076  This can be useful in conjunction with the
3078 3077  .Fl v
3079 3078  option to verify the name the receive operation would use.
3080 3079  .It Fl o Sy origin Ns = Ns Ar snapshot
3081 3080  Forces the stream to be received as a clone of the given snapshot.
3082 3081  If the stream is a full send stream, this will create the filesystem
3083 3082  described by the stream as a clone of the specified snapshot.
3084 3083  Which snapshot was specified will not affect the success or failure of the
3085 3084  receive, as long as the snapshot does exist.
3086 3085  If the stream is an incremental send stream, all the normal verification will be
3087 3086  performed.
3088 3087  .It Fl u
3089 3088  File system that is associated with the received stream is not mounted.
3090 3089  .It Fl v
3091 3090  Print verbose information about the stream and the time required to perform the
3092 3091  receive operation.
3093 3092  .It Fl s
3094 3093  If the receive is interrupted, save the partially received state, rather
3095 3094  than deleting it.
3096 3095  Interruption may be due to premature termination of the stream
3097 3096  .Po e.g. due to network failure or failure of the remote system
3098 3097  if the stream is being read over a network connection
3099 3098  .Pc ,
3100 3099  a checksum error in the stream, termination of the
3101 3100  .Nm zfs Cm receive
3102 3101  process, or unclean shutdown of the system.
3103 3102  .Pp
3104 3103  The receive can be resumed with a stream generated by
3105 3104  .Nm zfs Cm send Fl t Ar token ,
3106 3105  where the
3107 3106  .Ar token
3108 3107  is the value of the
3109 3108  .Sy receive_resume_token
3110 3109  property of the filesystem or volume which is received into.
3111 3110  .Pp
3112 3111  To use this flag, the storage pool must have the
3113 3112  .Sy extensible_dataset
3114 3113  feature enabled.
3115 3114  See
3116 3115  .Xr zpool-features 5
3117 3116  for details on ZFS feature flags.
3118 3117  .El
3119 3118  .It Xo
3120 3119  .Nm
3121 3120  .Cm receive
3122 3121  .Fl A
3123 3122  .Ar filesystem Ns | Ns Ar volume
3124 3123  .Xc
3125 3124  Abort an interrupted
3126 3125  .Nm zfs Cm receive Fl s ,
3127 3126  deleting its saved partially received state.
3128 3127  .It Xo
3129 3128  .Nm
3130 3129  .Cm allow
3131 3130  .Ar filesystem Ns | Ns Ar volume
3132 3131  .Xc
3133 3132  Displays permissions that have been delegated on the specified filesystem or
3134 3133  volume.
3135 3134  See the other forms of
3136 3135  .Nm zfs Cm allow
3137 3136  for more information.
3138 3137  .It Xo
3139 3138  .Nm
3140 3139  .Cm allow
3141 3140  .Op Fl dglu
3142 3141  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3143 3142  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3144 3143  .Ar setname Oc Ns ...
3145 3144  .Ar filesystem Ns | Ns Ar volume
3146 3145  .Xc
3147 3146  .It Xo
3148 3147  .Nm
3149 3148  .Cm allow
3150 3149  .Op Fl dl
3151 3150  .Fl e Ns | Ns Sy everyone
3152 3151  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3153 3152  .Ar setname Oc Ns ...
3154 3153  .Ar filesystem Ns | Ns Ar volume
3155 3154  .Xc
3156 3155  Delegates ZFS administration permission for the file systems to non-privileged
3157 3156  users.
3158 3157  .Bl -tag -width "-d"
3159 3158  .It Fl d
3160 3159  Allow only for the descendent file systems.
3161 3160  .It Fl e Ns | Ns Sy everyone
3162 3161  Specifies that the permissions be delegated to everyone.
3163 3162  .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ...
3164 3163  Explicitly specify that permissions are delegated to the group.
3165 3164  .It Fl l
3166 3165  Allow
3167 3166  .Qq locally
3168 3167  only for the specified file system.
3169 3168  .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ...
3170 3169  Explicitly specify that permissions are delegated to the user.
3171 3170  .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3172 3171  Specifies to whom the permissions are delegated.
3173 3172  Multiple entities can be specified as a comma-separated list.
3174 3173  If neither of the
3175 3174  .Fl gu
3176 3175  options are specified, then the argument is interpreted preferentially as the
3177 3176  keyword
3178 3177  .Sy everyone ,
3179 3178  then as a user name, and lastly as a group name.
3180 3179  To specify a user or group named
3181 3180  .Qq everyone ,
3182 3181  use the
3183 3182  .Fl g
3184 3183  or
3185 3184  .Fl u
3186 3185  options.
3187 3186  To specify a group with the same name as a user, use the
3188 3187  .Fl g
3189 3188  options.
3190 3189  .It Xo
3191 3190  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3192 3191  .Ar setname Oc Ns ...
3193 3192  .Xc
3194 3193  The permissions to delegate.
3195 3194  Multiple permissions may be specified as a comma-separated list.
3196 3195  Permission names are the same as ZFS subcommand and property names.
3197 3196  See the property list below.
3198 3197  Property set names, which begin with
3199 3198  .Sy @ ,
3200 3199  may be specified.
3201 3200  See the
3202 3201  .Fl s
3203 3202  form below for details.
3204 3203  .El
3205 3204  .Pp
3206 3205  If neither of the
3207 3206  .Fl dl
3208 3207  options are specified, or both are, then the permissions are allowed for the
3209 3208  file system or volume, and all of its descendents.
3210 3209  .Pp
3211 3210  Permissions are generally the ability to use a ZFS subcommand or change a ZFS
3212 3211  property.
3213 3212  The following permissions are available:
3214 3213  .Bd -literal
3215 3214  NAME             TYPE           NOTES
3216 3215  allow            subcommand     Must also have the permission that is
3217 3216                                  being allowed
3218 3217  clone            subcommand     Must also have the 'create' ability and
3219 3218                                  'mount' ability in the origin file system
3220 3219  create           subcommand     Must also have the 'mount' ability
3221 3220  destroy          subcommand     Must also have the 'mount' ability
3222 3221  diff             subcommand     Allows lookup of paths within a dataset
3223 3222                                  given an object number, and the ability
3224 3223                                  to create snapshots necessary to
3225 3224                                  'zfs diff'.
3226 3225  mount            subcommand     Allows mount/umount of ZFS datasets
3227 3226  promote          subcommand     Must also have the 'mount' and 'promote'
3228 3227                                  ability in the origin file system
3229 3228  receive          subcommand     Must also have the 'mount' and 'create'
3230 3229                                  ability
3231 3230  rename           subcommand     Must also have the 'mount' and 'create'
3232 3231                                  ability in the new parent
3233 3232  rollback         subcommand     Must also have the 'mount' ability
3234 3233  send             subcommand
3235 3234  share            subcommand     Allows sharing file systems over NFS
3236 3235                                  or SMB protocols
3237 3236  snapshot         subcommand     Must also have the 'mount' ability
3238 3237  
3239 3238  groupquota       other          Allows accessing any groupquota@...
3240 3239                                  property
3241 3240  groupused        other          Allows reading any groupused@... property
3242 3241  userprop         other          Allows changing any user property
3243 3242  userquota        other          Allows accessing any userquota@...
3244 3243                                  property
3245 3244  userused         other          Allows reading any userused@... property
3246 3245  
3247 3246  aclinherit       property
3248 3247  aclmode          property
3249 3248  atime            property
3250 3249  canmount         property
3251 3250  casesensitivity  property
3252 3251  checksum         property
3253 3252  compression      property
3254 3253  copies           property
3255 3254  devices          property
3256 3255  exec             property
3257 3256  filesystem_limit property
3258 3257  mountpoint       property
3259 3258  nbmand           property
3260 3259  normalization    property
3261 3260  primarycache     property
3262 3261  quota            property
3263 3262  readonly         property
3264 3263  recordsize       property
3265 3264  refquota         property
3266 3265  refreservation   property
3267 3266  reservation      property
3268 3267  secondarycache   property
3269 3268  setuid           property
3270 3269  sharenfs         property
3271 3270  sharesmb         property
3272 3271  snapdir          property
3273 3272  snapshot_limit   property
3274 3273  utf8only         property
3275 3274  version          property
3276 3275  volblocksize     property
3277 3276  volsize          property
3278 3277  vscan            property
3279 3278  xattr            property
3280 3279  zoned            property
3281 3280  .Ed
3282 3281  .It Xo
3283 3282  .Nm
3284 3283  .Cm allow
3285 3284  .Fl c
3286 3285  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3287 3286  .Ar setname Oc Ns ...
3288 3287  .Ar filesystem Ns | Ns Ar volume
3289 3288  .Xc
3290 3289  Sets
3291 3290  .Qq create time
3292 3291  permissions.
3293 3292  These permissions are granted
3294 3293  .Pq locally
3295 3294  to the creator of any newly-created descendent file system.
3296 3295  .It Xo
3297 3296  .Nm
3298 3297  .Cm allow
3299 3298  .Fl s No @ Ns Ar setname
3300 3299  .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3301 3300  .Ar setname Oc Ns ...
3302 3301  .Ar filesystem Ns | Ns Ar volume
3303 3302  .Xc
3304 3303  Defines or adds permissions to a permission set.
3305 3304  The set can be used by other
3306 3305  .Nm zfs Cm allow
3307 3306  commands for the specified file system and its descendents.
3308 3307  Sets are evaluated dynamically, so changes to a set are immediately reflected.
3309 3308  Permission sets follow the same naming restrictions as ZFS file systems, but the
3310 3309  name must begin with
3311 3310  .Sy @ ,
3312 3311  and can be no more than 64 characters long.
3313 3312  .It Xo
3314 3313  .Nm
3315 3314  .Cm unallow
3316 3315  .Op Fl dglru
3317 3316  .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ...
3318 3317  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3319 3318  .Ar setname Oc Ns ... Oc
3320 3319  .Ar filesystem Ns | Ns Ar volume
3321 3320  .Xc
3322 3321  .It Xo
3323 3322  .Nm
3324 3323  .Cm unallow
3325 3324  .Op Fl dlr
3326 3325  .Fl e Ns | Ns Sy everyone
3327 3326  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3328 3327  .Ar setname Oc Ns ... Oc
3329 3328  .Ar filesystem Ns | Ns Ar volume
3330 3329  .Xc
3331 3330  .It Xo
3332 3331  .Nm
3333 3332  .Cm unallow
3334 3333  .Op Fl r
3335 3334  .Fl c
3336 3335  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3337 3336  .Ar setname Oc Ns ... Oc
3338 3337  .Ar filesystem Ns | Ns Ar volume
3339 3338  .Xc
3340 3339  Removes permissions that were granted with the
3341 3340  .Nm zfs Cm allow
3342 3341  command.
3343 3342  No permissions are explicitly denied, so other permissions granted are still in
3344 3343  effect.
3345 3344  For example, if the permission is granted by an ancestor.
3346 3345  If no permissions are specified, then all permissions for the specified
3347 3346  .Ar user ,
3348 3347  .Ar group ,
3349 3348  or
3350 3349  .Sy everyone
3351 3350  are removed.
3352 3351  Specifying
3353 3352  .Sy everyone
3354 3353  .Po or using the
3355 3354  .Fl e
3356 3355  option
3357 3356  .Pc
3358 3357  only removes the permissions that were granted to everyone, not all permissions
3359 3358  for every user and group.
3360 3359  See the
3361 3360  .Nm zfs Cm allow
3362 3361  command for a description of the
3363 3362  .Fl ldugec
3364 3363  options.
3365 3364  .Bl -tag -width "-r"
3366 3365  .It Fl r
3367 3366  Recursively remove the permissions from this file system and all descendents.
3368 3367  .El
3369 3368  .It Xo
3370 3369  .Nm
3371 3370  .Cm unallow
3372 3371  .Op Fl r
3373 3372  .Fl s No @ Ns Ar setname
3374 3373  .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
3375 3374  .Ar setname Oc Ns ... Oc
3376 3375  .Ar filesystem Ns | Ns Ar volume
3377 3376  .Xc
3378 3377  Removes permissions from a permission set.
3379 3378  If no permissions are specified, then all permissions are removed, thus removing
3380 3379  the set entirely.
3381 3380  .It Xo
3382 3381  .Nm
3383 3382  .Cm hold
3384 3383  .Op Fl r
3385 3384  .Ar tag Ar snapshot Ns ...
3386 3385  .Xc
3387 3386  Adds a single reference, named with the
3388 3387  .Ar tag
3389 3388  argument, to the specified snapshot or snapshots.
3390 3389  Each snapshot has its own tag namespace, and tags must be unique within that
3391 3390  space.
3392 3391  .Pp
3393 3392  If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3394 3393  .Nm zfs Cm destroy
3395 3394  command return
3396 3395  .Er EBUSY .
3397 3396  .Bl -tag -width "-r"
3398 3397  .It Fl r
3399 3398  Specifies that a hold with the given tag is applied recursively to the snapshots
3400 3399  of all descendent file systems.
3401 3400  .El
3402 3401  .It Xo
3403 3402  .Nm
3404 3403  .Cm holds
3405 3404  .Op Fl r
3406 3405  .Ar snapshot Ns ...
3407 3406  .Xc
3408 3407  Lists all existing user references for the given snapshot or snapshots.
3409 3408  .Bl -tag -width "-r"
3410 3409  .It Fl r
3411 3410  Lists the holds that are set on the named descendent snapshots, in addition to
3412 3411  listing the holds on the named snapshot.
3413 3412  .El
3414 3413  .It Xo
3415 3414  .Nm
3416 3415  .Cm release
3417 3416  .Op Fl r
3418 3417  .Ar tag Ar snapshot Ns ...
3419 3418  .Xc
3420 3419  Removes a single reference, named with the
3421 3420  .Ar tag
3422 3421  argument, from the specified snapshot or snapshots.
3423 3422  The tag must already exist for each snapshot.
3424 3423  If a hold exists on a snapshot, attempts to destroy that snapshot by using the
3425 3424  .Nm zfs Cm destroy
3426 3425  command return
3427 3426  .Er EBUSY .
3428 3427  .Bl -tag -width "-r"
3429 3428  .It Fl r
3430 3429  Recursively releases a hold with the given tag on the snapshots of all
3431 3430  descendent file systems.
3432 3431  .El
3433 3432  .It Xo
3434 3433  .Nm
3435 3434  .Cm diff
3436 3435  .Op Fl FHt
3437 3436  .Ar snapshot Ar snapshot Ns | Ns Ar filesystem
3438 3437  .Xc
3439 3438  Display the difference between a snapshot of a given filesystem and another
3440 3439  snapshot of that filesystem from a later time or the current contents of the
3441 3440  filesystem.
3442 3441  The first column is a character indicating the type of change, the other columns
3443 3442  indicate pathname, new pathname
3444 3443  .Pq in case of rename ,
3445 3444  change in link count, and optionally file type and/or change time.
3446 3445  The types of change are:
3447 3446  .Bd -literal
3448 3447  -       The path has been removed
3449 3448  +       The path has been created
3450 3449  M       The path has been modified
3451 3450  R       The path has been renamed
3452 3451  .Ed
3453 3452  .Bl -tag -width "-F"
3454 3453  .It Fl F
3455 3454  Display an indication of the type of file, in a manner similar to the
3456 3455  .Fl
3457 3456  option of
3458 3457  .Xr ls 1 .
3459 3458  .Bd -literal
3460 3459  B       Block device
3461 3460  C       Character device
3462 3461  /       Directory
3463 3462  >       Door
3464 3463  |       Named pipe
3465 3464  @       Symbolic link
3466 3465  P       Event port
3467 3466  =       Socket
3468 3467  F       Regular file
3469 3468  .Ed
3470 3469  .It Fl H
3471 3470  Give more parsable tab-separated output, without header lines and without
3472 3471  arrows.
3473 3472  .It Fl t
3474 3473  Display the path's inode change time as the first column of output.
3475 3474  .El
3476 3475  .It Xo
3477 3476  .Nm
3478 3477  .Cm program
3479 3478  .Op Fl jn
3480 3479  .Op Fl t Ar timeout
3481 3480  .Op Fl m Ar memory_limit
3482 3481  .Ar pool script
3483 3482  .Op Ar arg1 No ...
3484 3483  .Xc
3485 3484  Executes
3486 3485  .Ar script
3487 3486  as a ZFS channel program on
3488 3487  .Ar pool .

3489 3488  The ZFS channel
3490 3489  program interface allows ZFS administrative operations to be run
3491 3490  programmatically via a Lua script.
3492 3491  The entire script is executed atomically, with no other administrative
3493 3492  operations taking effect concurrently.
3494 3493  A library of ZFS calls is made available to channel program scripts.
3495 3494  Channel programs may only be run with root privileges.
3496 3495  .sp
3497 3496  For full documentation of the ZFS channel program interface, see the manual
3498 3497  page for
     3498 +.Xr zfs-program 1M .
3499 3499  .Bl -tag -width ""
3500 3500  .It Fl j
3501 3501  Display channel program output in JSON format.
3502 3502  When this flag is specified and standard output is empty -
3503 3503  channel program encountered an error.
3504 3504  The details of such an error will be printed to standard error in plain text.
3505 3505  .It Fl n
3506 3506  Executes a read-only channel program, which runs faster.
3507 3507  The program cannot change on-disk state by calling functions from
3508 3508  the zfs.sync submodule.

3509 3509  The program can be used to gather information such as properties and
3510 3510  determining if changes would succeed (zfs.check.*).
3511 3511  Without this flag, all pending changes must be synced to disk before
3512 3512  a channel program can complete.
3513 3513  .It Fl t Ar timeout
3514 3514  Execution time limit, in milliseconds.
3515 3515  If a channel program executes for longer than the provided timeout, it will
3516 3516  be stopped and an error will be returned.
3517 3517  The default timeout is 1000 ms, and can be set to a maximum of 10000 ms.
3518 3518  .It Fl m Ar memory-limit
3519 3519  Memory limit, in bytes.
3520 3520  If a channel program attempts to allocate more memory than the given limit,
3521 3521  it will be stopped and an error returned.
3522 3522  The default memory limit is 10 MB, and can be set to a maximum of 100 MB.
3523 3523  .sp
3524 3524  All remaining argument strings are passed directly to the channel program as
3525 3525  arguments.
3526 3526  See
3527 3527  .Xr zfs-program 1M
3528 3528  for more information.
3529 3529  .El
3530 3530  .El
3531 3531  .Sh EXIT STATUS
3532 3532  The
3533 3533  .Nm
3534 3534  utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line
3535 3535  options were specified.
3536 3536  .Sh EXAMPLES
3537 3537  .Bl -tag -width ""
3538 3538  .It Sy Example 1 No Creating a ZFS File System Hierarchy
3539 3539  The following commands create a file system named
3540 3540  .Em pool/home
3541 3541  and a file system named
3542 3542  .Em pool/home/bob .
3543 3543  The mount point
3544 3544  .Pa /export/home
3545 3545  is set for the parent file system, and is automatically inherited by the child
3546 3546  file system.
3547 3547  .Bd -literal
3548 3548  # zfs create pool/home
3549 3549  # zfs set mountpoint=/export/home pool/home
3550 3550  # zfs create pool/home/bob
3551 3551  .Ed
3552 3552  .It Sy Example 2 No Creating a ZFS Snapshot
3553 3553  The following command creates a snapshot named
3554 3554  .Sy yesterday .
3555 3555  This snapshot is mounted on demand in the
3556 3556  .Pa .zfs/snapshot
3557 3557  directory at the root of the
3558 3558  .Em pool/home/bob
3559 3559  file system.
3560 3560  .Bd -literal
3561 3561  # zfs snapshot pool/home/bob@yesterday
3562 3562  .Ed
3563 3563  .It Sy Example 3 No Creating and Destroying Multiple Snapshots
3564 3564  The following command creates snapshots named
3565 3565  .Sy yesterday
3566 3566  of
3567 3567  .Em pool/home
3568 3568  and all of its descendent file systems.
3569 3569  Each snapshot is mounted on demand in the
3570 3570  .Pa .zfs/snapshot
3571 3571  directory at the root of its file system.
3572 3572  The second command destroys the newly created snapshots.
3573 3573  .Bd -literal
3574 3574  # zfs snapshot -r pool/home@yesterday
3575 3575  # zfs destroy -r pool/home@yesterday
3576 3576  .Ed
3577 3577  .It Sy Example 4 No Disabling and Enabling File System Compression
3578 3578  The following command disables the
3579 3579  .Sy compression
3580 3580  property for all file systems under
3581 3581  .Em pool/home .
3582 3582  The next command explicitly enables
3583 3583  .Sy compression
3584 3584  for
3585 3585  .Em pool/home/anne .
3586 3586  .Bd -literal
3587 3587  # zfs set compression=off pool/home
3588 3588  # zfs set compression=on pool/home/anne
3589 3589  .Ed
3590 3590  .It Sy Example 5 No Listing ZFS Datasets
3591 3591  The following command lists all active file systems and volumes in the system.
3592 3592  Snapshots are displayed if the
3593 3593  .Sy listsnaps
3594 3594  property is
3595 3595  .Sy on .
3596 3596  The default is
3597 3597  .Sy off .
3598 3598  See
3599 3599  .Xr zpool 1M
3600 3600  for more information on pool properties.
3601 3601  .Bd -literal
3602 3602  # zfs list
3603 3603  NAME                      USED  AVAIL  REFER  MOUNTPOINT
3604 3604  pool                      450K   457G    18K  /pool
3605 3605  pool/home                 315K   457G    21K  /export/home
3606 3606  pool/home/anne             18K   457G    18K  /export/home/anne
3607 3607  pool/home/bob             276K   457G   276K  /export/home/bob
3608 3608  .Ed
3609 3609  .It Sy Example 6 No Setting a Quota on a ZFS File System
3610 3610  The following command sets a quota of 50 Gbytes for
3611 3611  .Em pool/home/bob .
3612 3612  .Bd -literal
3613 3613  # zfs set quota=50G pool/home/bob
3614 3614  .Ed
3615 3615  .It Sy Example 7 No Listing ZFS Properties
3616 3616  The following command lists all properties for
3617 3617  .Em pool/home/bob .
3618 3618  .Bd -literal
3619 3619  # zfs get all pool/home/bob
3620 3620  NAME           PROPERTY              VALUE                  SOURCE
3621 3621  pool/home/bob  type                  filesystem             -
3622 3622  pool/home/bob  creation              Tue Jul 21 15:53 2009  -
3623 3623  pool/home/bob  used                  21K                    -
3624 3624  pool/home/bob  available             20.0G                  -
3625 3625  pool/home/bob  referenced            21K                    -
3626 3626  pool/home/bob  compressratio         1.00x                  -
3627 3627  pool/home/bob  mounted               yes                    -
3628 3628  pool/home/bob  quota                 20G                    local
3629 3629  pool/home/bob  reservation           none                   default
3630 3630  pool/home/bob  recordsize            128K                   default
3631 3631  pool/home/bob  mountpoint            /pool/home/bob         default
3632 3632  pool/home/bob  sharenfs              off                    default
3633 3633  pool/home/bob  checksum              on                     default
3634 3634  pool/home/bob  compression           on                     local
3635 3635  pool/home/bob  atime                 on                     default
3636 3636  pool/home/bob  devices               on                     default
3637 3637  pool/home/bob  exec                  on                     default
3638 3638  pool/home/bob  setuid                on                     default
3639 3639  pool/home/bob  readonly              off                    default
3640 3640  pool/home/bob  zoned                 off                    default
3641 3641  pool/home/bob  snapdir               hidden                 default
3642 3642  pool/home/bob  aclmode               discard                default
3643 3643  pool/home/bob  aclinherit            restricted             default
3644 3644  pool/home/bob  canmount              on                     default
3645 3645  pool/home/bob  xattr                 on                     default
3646 3646  pool/home/bob  copies                1                      default
3647 3647  pool/home/bob  version               4                      -
3648 3648  pool/home/bob  utf8only              off                    -
3649 3649  pool/home/bob  normalization         none                   -
3650 3650  pool/home/bob  casesensitivity       sensitive              -
3651 3651  pool/home/bob  vscan                 off                    default
3652 3652  pool/home/bob  nbmand                off                    default
3653 3653  pool/home/bob  sharesmb              off                    default
3654 3654  pool/home/bob  refquota              none                   default
3655 3655  pool/home/bob  refreservation        none                   default
3656 3656  pool/home/bob  primarycache          all                    default
3657 3657  pool/home/bob  secondarycache        all                    default
3658 3658  pool/home/bob  usedbysnapshots       0                      -
3659 3659  pool/home/bob  usedbydataset         21K                    -
3660 3660  pool/home/bob  usedbychildren        0                      -
3661 3661  pool/home/bob  usedbyrefreservation  0                      -
3662 3662  .Ed
3663 3663  .Pp
3664 3664  The following command gets a single property value.
3665 3665  .Bd -literal
3666 3666  # zfs get -H -o value compression pool/home/bob
3667 3667  on
3668 3668  .Ed
3669 3669  The following command lists all properties with local settings for
3670 3670  .Em pool/home/bob .
3671 3671  .Bd -literal
3672 3672  # zfs get -r -s local -o name,property,value all pool/home/bob
3673 3673  NAME           PROPERTY              VALUE
3674 3674  pool/home/bob  quota                 20G
3675 3675  pool/home/bob  compression           on
3676 3676  .Ed
3677 3677  .It Sy Example 8 No Rolling Back a ZFS File System
3678 3678  The following command reverts the contents of
3679 3679  .Em pool/home/anne
3680 3680  to the snapshot named
3681 3681  .Sy yesterday ,
3682 3682  deleting all intermediate snapshots.
3683 3683  .Bd -literal
3684 3684  # zfs rollback -r pool/home/anne@yesterday
3685 3685  .Ed
3686 3686  .It Sy Example 9 No Creating a ZFS Clone
3687 3687  The following command creates a writable file system whose initial contents are
3688 3688  the same as
3689 3689  .Em pool/home/bob@yesterday .
3690 3690  .Bd -literal
3691 3691  # zfs clone pool/home/bob@yesterday pool/clone
3692 3692  .Ed
3693 3693  .It Sy Example 10 No Promoting a ZFS Clone
3694 3694  The following commands illustrate how to test out changes to a file system, and
3695 3695  then replace the original file system with the changed one, using clones, clone
3696 3696  promotion, and renaming:
3697 3697  .Bd -literal
3698 3698  # zfs create pool/project/production
3699 3699    populate /pool/project/production with data
3700 3700  # zfs snapshot pool/project/production@today
3701 3701  # zfs clone pool/project/production@today pool/project/beta
3702 3702    make changes to /pool/project/beta and test them
3703 3703  # zfs promote pool/project/beta
3704 3704  # zfs rename pool/project/production pool/project/legacy
3705 3705  # zfs rename pool/project/beta pool/project/production
3706 3706    once the legacy version is no longer needed, it can be destroyed
3707 3707  # zfs destroy pool/project/legacy
3708 3708  .Ed
3709 3709  .It Sy Example 11 No Inheriting ZFS Properties
3710 3710  The following command causes
3711 3711  .Em pool/home/bob
3712 3712  and
3713 3713  .Em pool/home/anne
3714 3714  to inherit the
3715 3715  .Sy checksum
3716 3716  property from their parent.
3717 3717  .Bd -literal
3718 3718  # zfs inherit checksum pool/home/bob pool/home/anne
3719 3719  .Ed
3720 3720  .It Sy Example 12 No Remotely Replicating ZFS Data
3721 3721  The following commands send a full stream and then an incremental stream to a
3722 3722  remote machine, restoring them into
3723 3723  .Em poolB/received/fs@a
3724 3724  and
3725 3725  .Em poolB/received/fs@b ,
3726 3726  respectively.
3727 3727  .Em poolB
3728 3728  must contain the file system
3729 3729  .Em poolB/received ,
3730 3730  and must not initially contain
3731 3731  .Em poolB/received/fs .
3732 3732  .Bd -literal
3733 3733  # zfs send pool/fs@a | \e
3734 3734    ssh host zfs receive poolB/received/fs@a
3735 3735  # zfs send -i a pool/fs@b | \e
3736 3736    ssh host zfs receive poolB/received/fs
3737 3737  .Ed
3738 3738  .It Sy Example 13 No Using the zfs receive -d Option
3739 3739  The following command sends a full stream of
3740 3740  .Em poolA/fsA/fsB@snap
3741 3741  to a remote machine, receiving it into
3742 3742  .Em poolB/received/fsA/fsB@snap .
3743 3743  The
3744 3744  .Em fsA/fsB@snap
3745 3745  portion of the received snapshot's name is determined from the name of the sent
3746 3746  snapshot.
3747 3747  .Em poolB
3748 3748  must contain the file system
3749 3749  .Em poolB/received .
3750 3750  If
3751 3751  .Em poolB/received/fsA
3752 3752  does not exist, it is created as an empty file system.
3753 3753  .Bd -literal
3754 3754  # zfs send poolA/fsA/fsB@snap | \e
3755 3755    ssh host zfs receive -d poolB/received
3756 3756  .Ed
3757 3757  .It Sy Example 14 No Setting User Properties
3758 3758  The following example sets the user-defined
3759 3759  .Sy com.example:department
3760 3760  property for a dataset.
3761 3761  .Bd -literal
3762 3762  # zfs set com.example:department=12345 tank/accounting
3763 3763  .Ed
3764 3764  .It Sy Example 15 No Performing a Rolling Snapshot
3765 3765  The following example shows how to maintain a history of snapshots with a
3766 3766  consistent naming scheme.
3767 3767  To keep a week's worth of snapshots, the user destroys the oldest snapshot,
3768 3768  renames the remaining snapshots, and then creates a new snapshot, as follows:
3769 3769  .Bd -literal
3770 3770  # zfs destroy -r pool/users@7daysago
3771 3771  # zfs rename -r pool/users@6daysago @7daysago
3772 3772  # zfs rename -r pool/users@5daysago @6daysago
3773 3773  # zfs rename -r pool/users@4daysago @5daysago
3774 3774  # zfs rename -r pool/users@3daysago @4daysago
3775 3775  # zfs rename -r pool/users@2daysago @3daysago
3776 3776  # zfs rename -r pool/users@yesterday @2daysago
3777 3777  # zfs rename -r pool/users@today @yesterday
3778 3778  # zfs snapshot -r pool/users@today
3779 3779  .Ed
3780 3780  .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System
3781 3781  The following commands show how to set
3782 3782  .Sy sharenfs
3783 3783  property options to enable
3784 3784  .Sy rw
3785 3785  access for a set of
3786 3786  .Sy IP
3787 3787  addresses and to enable root access for system
3788 3788  .Sy neo
3789 3789  on the
3790 3790  .Em tank/home
3791 3791  file system.
3792 3792  .Bd -literal
3793 3793  # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home
3794 3794  .Ed
3795 3795  .Pp
3796 3796  If you are using
3797 3797  .Sy DNS
3798 3798  for host name resolution, specify the fully qualified hostname.
3799 3799  .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset
3800 3800  The following example shows how to set permissions so that user
3801 3801  .Sy cindys
3802 3802  can create, destroy, mount, and take snapshots on
3803 3803  .Em tank/cindys .
3804 3804  The permissions on
3805 3805  .Em tank/cindys
3806 3806  are also displayed.
3807 3807  .Bd -literal
3808 3808  # zfs allow cindys create,destroy,mount,snapshot tank/cindys
3809 3809  # zfs allow tank/cindys
3810 3810  ---- Permissions on tank/cindys --------------------------------------
3811 3811  Local+Descendent permissions:
3812 3812          user cindys create,destroy,mount,snapshot
3813 3813  .Ed
3814 3814  .Pp
3815 3815  Because the
3816 3816  .Em tank/cindys
3817 3817  mount point permission is set to 755 by default, user
3818 3818  .Sy cindys
3819 3819  will be unable to mount file systems under
3820 3820  .Em tank/cindys .
3821 3821  Add an ACE similar to the following syntax to provide mount point access:
3822 3822  .Bd -literal
3823 3823  # chmod A+user:cindys:add_subdirectory:allow /tank/cindys
3824 3824  .Ed
3825 3825  .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset
3826 3826  The following example shows how to grant anyone in the group
3827 3827  .Sy staff
3828 3828  to create file systems in
3829 3829  .Em tank/users .
3830 3830  This syntax also allows staff members to destroy their own file systems, but not
3831 3831  destroy anyone else's file system.
3832 3832  The permissions on
3833 3833  .Em tank/users
3834 3834  are also displayed.
3835 3835  .Bd -literal
3836 3836  # zfs allow staff create,mount tank/users
3837 3837  # zfs allow -c destroy tank/users
3838 3838  # zfs allow tank/users
3839 3839  ---- Permissions on tank/users ---------------------------------------
3840 3840  Permission sets:
3841 3841          destroy
3842 3842  Local+Descendent permissions:
3843 3843          group staff create,mount
3844 3844  .Ed
3845 3845  .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset
3846 3846  The following example shows how to define and grant a permission set on the
3847 3847  .Em tank/users
3848 3848  file system.
3849 3849  The permissions on
3850 3850  .Em tank/users
3851 3851  are also displayed.
3852 3852  .Bd -literal
3853 3853  # zfs allow -s @pset create,destroy,snapshot,mount tank/users
3854 3854  # zfs allow staff @pset tank/users
3855 3855  # zfs allow tank/users
3856 3856  ---- Permissions on tank/users ---------------------------------------
3857 3857  Permission sets:
3858 3858          @pset create,destroy,mount,snapshot
3859 3859  Local+Descendent permissions:
3860 3860          group staff @pset
3861 3861  .Ed
3862 3862  .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset
3863 3863  The following example shows to grant the ability to set quotas and reservations
3864 3864  on the
3865 3865  .Em users/home
3866 3866  file system.
3867 3867  The permissions on
3868 3868  .Em users/home
3869 3869  are also displayed.
3870 3870  .Bd -literal
3871 3871  # zfs allow cindys quota,reservation users/home
3872 3872  # zfs allow users/home
3873 3873  ---- Permissions on users/home ---------------------------------------
3874 3874  Local+Descendent permissions:
3875 3875          user cindys quota,reservation
3876 3876  cindys% zfs set quota=10G users/home/marks
3877 3877  cindys% zfs get quota users/home/marks
3878 3878  NAME              PROPERTY  VALUE  SOURCE
3879 3879  users/home/marks  quota     10G    local
3880 3880  .Ed
3881 3881  .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset
3882 3882  The following example shows how to remove the snapshot permission from the
3883 3883  .Sy staff
3884 3884  group on the
3885 3885  .Em tank/users
3886 3886  file system.
3887 3887  The permissions on
3888 3888  .Em tank/users
3889 3889  are also displayed.
3890 3890  .Bd -literal
3891 3891  # zfs unallow staff snapshot tank/users
3892 3892  # zfs allow tank/users
3893 3893  ---- Permissions on tank/users ---------------------------------------
3894 3894  Permission sets:
3895 3895          @pset create,destroy,mount,snapshot
3896 3896  Local+Descendent permissions:
3897 3897          group staff @pset
3898 3898  .Ed
3899 3899  .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset
3900 3900  The following example shows how to see what has changed between a prior
3901 3901  snapshot of a ZFS dataset and its current state.
3902 3902  The
3903 3903  .Fl F
3904 3904  option is used to indicate type information for the files affected.
3905 3905  .Bd -literal
3906 3906  # zfs diff -F tank/test@before tank/test
3907 3907  M       /       /tank/test/
3908 3908  M       F       /tank/test/linked      (+1)
3909 3909  R       F       /tank/test/oldname -> /tank/test/newname
3910 3910  -       F       /tank/test/deleted
3911 3911  +       F       /tank/test/created
3912 3912  M       F       /tank/test/modified
3913 3913  .Ed

3914 3914  .El
3915 3915  .Sh INTERFACE STABILITY
3916 3916  .Sy Committed .
3917 3917  .Sh SEE ALSO
3918 3918  .Xr gzip 1 ,
3919 3919  .Xr ssh 1 ,
3920 3920  .Xr mount 1M ,
3921 3921  .Xr share 1M ,
3922 3922  .Xr sharemgr 1M ,
3923 3923  .Xr unshare 1M ,
     3924 +.Xr zfs-program 1M ,
3924 3925  .Xr zonecfg 1M ,
3925 3926  .Xr zpool 1M ,
3926 3927  .Xr chmod 2 ,
3927 3928  .Xr stat 2 ,
3928 3929  .Xr write 2 ,
3929 3930  .Xr fsync 3C ,
3930 3931  .Xr dfstab 4 ,
3931 3932  .Xr acl 5 ,
3932 3933  .Xr attributes 5
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX