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