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