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