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 November 03, 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 Pnpv 45.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 46.Ar filesystem 47.Nm 48.Cm create 49.Op Fl Pnpsv 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 Pnpv 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.It Fl n 2286Do a dry-run 2287.Pq Qq No-op 2288creation. 2289No datasets will be created. 2290This is useful in conjunction with the 2291.Fl v 2292or 2293.Fl P 2294flags to validate properties that are passed via 2295.Fl o 2296options and those implied by other options. 2297The actual dataset creation can still fail due to insufficient privileges or 2298available capacity. 2299.It Fl P 2300Print machine-parsable verbose information about the created dataset. 2301Each line of output contains a key and one or two values, all separated by tabs. 2302The 2303.Sy create_ancestors 2304and 2305.Sy create 2306keys have 2307.Em filesystem 2308as their only value. 2309The 2310.Sy create_ancestors 2311key only appears if the 2312.Fl p 2313option is used. 2314The 2315.Sy property 2316key has two values, a property's name and that property's value. 2317The 2318.Sy property 2319key may appear zero or more times, once for each property that will be set local 2320to 2321.Em filesystem 2322due to the use of the 2323.Fl o 2324option. 2325.It Fl v 2326Print verbose information about the created dataset. 2327.El 2328.It Xo 2329.Nm 2330.Cm create 2331.Op Fl ps 2332.Op Fl b Ar blocksize 2333.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 2334.Fl V Ar size Ar volume 2335.Xc 2336Creates a volume of the given size. 2337The volume is exported as a block device in 2338.Pa /dev/zvol/{dsk,rdsk}/path , 2339where 2340.Em path 2341is the name of the volume in the ZFS namespace. 2342The size represents the logical size as exported by the device. 2343By default, a reservation of equal size is created. 2344.Pp 2345.Ar size 2346is automatically rounded up to the nearest 128 Kbytes to ensure that the volume 2347has an integral number of blocks regardless of 2348.Sy blocksize . 2349.Bl -tag -width "-b" 2350.It Fl b Ar blocksize 2351Equivalent to 2352.Fl o Sy volblocksize Ns = Ns Ar blocksize . 2353If this option is specified in conjunction with 2354.Fl o Sy volblocksize , 2355the resulting behavior is undefined. 2356.It Fl o Ar property Ns = Ns Ar value 2357Sets the specified property as if the 2358.Nm zfs Cm set Ar property Ns = Ns Ar value 2359command was invoked at the same time the dataset was created. 2360Any editable ZFS property can also be set at creation time. 2361Multiple 2362.Fl o 2363options can be specified. 2364An error results if the same property is specified in multiple 2365.Fl o 2366options. 2367.It Fl p 2368Creates all the non-existing parent datasets. 2369Datasets created in this manner are automatically mounted according to the 2370.Sy mountpoint 2371property inherited from their parent. 2372Any property specified on the command line using the 2373.Fl o 2374option is ignored. 2375If the target filesystem already exists, the operation completes successfully. 2376.It Fl s 2377Creates a sparse volume with no reservation. 2378See 2379.Sy volsize 2380in the 2381.Sx Native Properties 2382section for more information about sparse volumes. 2383.It Fl n 2384Do a dry-run 2385.Pq Qq No-op 2386creation. 2387No datasets will be created. 2388This is useful in conjunction with the 2389.Fl v 2390or 2391.Fl P 2392flags to validate properties that are passed via 2393.Fl o 2394options and those implied by other options. 2395The actual dataset creation can still fail due to insufficient privileges or 2396available capacity. 2397.It Fl P 2398Print machine-parsable verbose information about the created dataset. 2399Each line of output contains a key and one or two values, all separated by tabs. 2400The 2401.Sy create_ancestors 2402and 2403.Sy create 2404keys have 2405.Em volume 2406as their only value. 2407The 2408.Sy create_ancestors 2409key only appears if the 2410.Fl p 2411option is used. 2412The 2413.Sy property 2414key has two values, a property's name and that property's value. 2415The 2416.Sy property 2417key may appear zero or more times, once for each property that will be set local 2418to 2419.Em volume 2420due to the use of the 2421.Fl b 2422or 2423.Fl o 2424options, as well as 2425.Sy refreservation 2426if the volume is not sparse. 2427.It Fl v 2428Print verbose information about the created dataset. 2429.El 2430.It Xo 2431.Nm 2432.Cm destroy 2433.Op Fl Rfnprv 2434.Ar filesystem Ns | Ns Ar volume 2435.Xc 2436Destroys the given dataset. 2437By default, the command unshares any file systems that are currently shared, 2438unmounts any file systems that are currently mounted, and refuses to destroy a 2439dataset that has active dependents 2440.Pq children or clones . 2441.Bl -tag -width "-R" 2442.It Fl R 2443Recursively destroy all dependents, including cloned file systems outside the 2444target hierarchy. 2445.It Fl f 2446Force an unmount of any file systems using the 2447.Nm unmount Fl f 2448command. 2449This option has no effect on non-file systems or unmounted file systems. 2450.It Fl n 2451Do a dry-run 2452.Pq Qq No-op 2453deletion. 2454No data will be deleted. 2455This is useful in conjunction with the 2456.Fl v 2457or 2458.Fl p 2459flags to determine what data would be deleted. 2460.It Fl p 2461Print machine-parsable verbose information about the deleted data. 2462.It Fl r 2463Recursively destroy all children. 2464.It Fl v 2465Print verbose information about the deleted data. 2466.El 2467.Pp 2468Extreme care should be taken when applying either the 2469.Fl r 2470or the 2471.Fl R 2472options, as they can destroy large portions of a pool and cause unexpected 2473behavior for mounted file systems in use. 2474.It Xo 2475.Nm 2476.Cm destroy 2477.Op Fl Rdnprv 2478.Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns 2479.Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... 2480.Xc 2481The given snapshots are destroyed immediately if and only if the 2482.Nm zfs Cm destroy 2483command without the 2484.Fl d 2485option would have destroyed it. 2486Such immediate destruction would occur, for example, if the snapshot had no 2487clones and the user-initiated reference count were zero. 2488.Pp 2489If a snapshot does not qualify for immediate destruction, it is marked for 2490deferred deletion. 2491In this state, it exists as a usable, visible snapshot until both of the 2492preconditions listed above are met, at which point it is destroyed. 2493.Pp 2494An inclusive range of snapshots may be specified by separating the first and 2495last snapshots with a percent sign. 2496The first and/or last snapshots may be left blank, in which case the 2497filesystem's oldest or newest snapshot will be implied. 2498.Pp 2499Multiple snapshots 2500.Pq or ranges of snapshots 2501of the same filesystem or volume may be specified in a comma-separated list of 2502snapshots. 2503Only the snapshot's short name 2504.Po the part after the 2505.Sy @ 2506.Pc 2507should be specified when using a range or comma-separated list to identify 2508multiple snapshots. 2509.Bl -tag -width "-R" 2510.It Fl R 2511Recursively destroy all clones of these snapshots, including the clones, 2512snapshots, and children. 2513If this flag is specified, the 2514.Fl d 2515flag will have no effect. 2516.It Fl d 2517Defer snapshot deletion. 2518.It Fl n 2519Do a dry-run 2520.Pq Qq No-op 2521deletion. 2522No data will be deleted. 2523This is useful in conjunction with the 2524.Fl p 2525or 2526.Fl v 2527flags to determine what data would be deleted. 2528.It Fl p 2529Print machine-parsable verbose information about the deleted data. 2530.It Fl r 2531Destroy 2532.Pq or mark for deferred deletion 2533all snapshots with this name in descendent file systems. 2534.It Fl v 2535Print verbose information about the deleted data. 2536.Pp 2537Extreme care should be taken when applying either the 2538.Fl r 2539or the 2540.Fl R 2541options, as they can destroy large portions of a pool and cause unexpected 2542behavior for mounted file systems in use. 2543.El 2544.It Xo 2545.Nm 2546.Cm destroy 2547.Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark 2548.Xc 2549The given bookmark is destroyed. 2550.It Xo 2551.Nm 2552.Cm snapshot 2553.Op Fl r 2554.Oo Fl o Ar property Ns = Ns value Oc Ns ... 2555.Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... 2556.Xc 2557Creates snapshots with the given names. 2558All previous modifications by successful system calls to the file system are 2559part of the snapshots. 2560Snapshots are taken atomically, so that all snapshots correspond to the same 2561moment in time. 2562See the 2563.Sx Snapshots 2564section for details. 2565.Bl -tag -width "-o" 2566.It Fl o Ar property Ns = Ns Ar value 2567Sets the specified property; see 2568.Nm zfs Cm create 2569for details. 2570.It Fl r 2571Recursively create snapshots of all descendent datasets 2572.El 2573.It Xo 2574.Nm 2575.Cm rollback 2576.Op Fl Rfr 2577.Ar snapshot 2578.Xc 2579Roll back the given dataset to a previous snapshot. 2580When a dataset is rolled back, all data that has changed since the snapshot is 2581discarded, and the dataset reverts to the state at the time of the snapshot. 2582By default, the command refuses to roll back to a snapshot other than the most 2583recent one. 2584In order to do so, all intermediate snapshots and bookmarks must be destroyed by 2585specifying the 2586.Fl r 2587option. 2588.Pp 2589The 2590.Fl rR 2591options do not recursively destroy the child snapshots of a recursive snapshot. 2592Only direct snapshots of the specified filesystem are destroyed by either of 2593these options. 2594To completely roll back a recursive snapshot, you must rollback the individual 2595child snapshots. 2596.Bl -tag -width "-R" 2597.It Fl R 2598Destroy any more recent snapshots and bookmarks, as well as any clones of those 2599snapshots. 2600.It Fl f 2601Used with the 2602.Fl R 2603option to force an unmount of any clone file systems that are to be destroyed. 2604.It Fl r 2605Destroy any snapshots and bookmarks more recent than the one specified. 2606.El 2607.It Xo 2608.Nm 2609.Cm clone 2610.Op Fl p 2611.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 2612.Ar snapshot Ar filesystem Ns | Ns Ar volume 2613.Xc 2614Creates a clone of the given snapshot. 2615See the 2616.Sx Clones 2617section for details. 2618The target dataset can be located anywhere in the ZFS hierarchy, and is created 2619as the same type as the original. 2620.Bl -tag -width "-o" 2621.It Fl o Ar property Ns = Ns Ar value 2622Sets the specified property; see 2623.Nm zfs Cm create 2624for details. 2625.It Fl p 2626Creates all the non-existing parent datasets. 2627Datasets created in this manner are automatically mounted according to the 2628.Sy mountpoint 2629property inherited from their parent. 2630If the target filesystem or volume already exists, the operation completes 2631successfully. 2632.El 2633.It Xo 2634.Nm 2635.Cm promote 2636.Ar clone-filesystem 2637.Xc 2638Promotes a clone file system to no longer be dependent on its 2639.Qq origin 2640snapshot. 2641This makes it possible to destroy the file system that the clone was created 2642from. 2643The clone parent-child dependency relationship is reversed, so that the origin 2644file system becomes a clone of the specified file system. 2645.Pp 2646The snapshot that was cloned, and any snapshots previous to this snapshot, are 2647now owned by the promoted clone. 2648The space they use moves from the origin file system to the promoted clone, so 2649enough space must be available to accommodate these snapshots. 2650No new space is consumed by this operation, but the space accounting is 2651adjusted. 2652The promoted clone must not have any conflicting snapshot names of its own. 2653The 2654.Cm rename 2655subcommand can be used to rename any conflicting snapshots. 2656.It Xo 2657.Nm 2658.Cm rename 2659.Op Fl f 2660.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 2661.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 2662.Xc 2663.It Xo 2664.Nm 2665.Cm rename 2666.Op Fl fp 2667.Ar filesystem Ns | Ns Ar volume 2668.Ar filesystem Ns | Ns Ar volume 2669.Xc 2670Renames the given dataset. 2671The new target can be located anywhere in the ZFS hierarchy, with the exception 2672of snapshots. 2673Snapshots can only be renamed within the parent file system or volume. 2674When renaming a snapshot, the parent file system of the snapshot does not need 2675to be specified as part of the second argument. 2676Renamed file systems can inherit new mount points, in which case they are 2677unmounted and remounted at the new mount point. 2678.Bl -tag -width "-a" 2679.It Fl f 2680Force unmount any filesystems that need to be unmounted in the process. 2681.It Fl p 2682Creates all the nonexistent parent datasets. 2683Datasets created in this manner are automatically mounted according to the 2684.Sy mountpoint 2685property inherited from their parent. 2686.El 2687.It Xo 2688.Nm 2689.Cm rename 2690.Fl r 2691.Ar snapshot Ar snapshot 2692.Xc 2693Recursively rename the snapshots of all descendent datasets. 2694Snapshots are the only dataset that can be renamed recursively. 2695.It Xo 2696.Nm 2697.Cm list 2698.Op Fl r Ns | Ns Fl d Ar depth 2699.Op Fl Hp 2700.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc 2701.Oo Fl s Ar property Oc Ns ... 2702.Oo Fl S Ar property Oc Ns ... 2703.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 2704.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... 2705.Xc 2706Lists the property information for the given datasets in tabular form. 2707If specified, you can list property information by the absolute pathname or the 2708relative pathname. 2709By default, all file systems and volumes are displayed. 2710Snapshots are displayed if the 2711.Sy listsnaps 2712property is 2713.Sy on 2714.Po the default is 2715.Sy off 2716.Pc . 2717The following fields are displayed, 2718.Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns 2719.Sy mountpoint . 2720.Bl -tag -width "-H" 2721.It Fl H 2722Used for scripting mode. 2723Do not print headers and separate fields by a single tab instead of arbitrary 2724white space. 2725.It Fl S Ar property 2726Same as the 2727.Fl s 2728option, but sorts by property in descending order. 2729.It Fl d Ar depth 2730Recursively display any children of the dataset, limiting the recursion to 2731.Ar depth . 2732A 2733.Ar depth 2734of 2735.Sy 1 2736will display only the dataset and its direct children. 2737.It Fl o Ar property 2738A comma-separated list of properties to display. 2739The property must be: 2740.Bl -bullet 2741.It 2742One of the properties described in the 2743.Sx Native Properties 2744section 2745.It 2746A user property 2747.It 2748The value 2749.Sy name 2750to display the dataset name 2751.It 2752The value 2753.Sy space 2754to display space usage properties on file systems and volumes. 2755This is a shortcut for specifying 2756.Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns 2757.Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t 2758.Sy filesystem Ns \&, Ns Sy volume 2759syntax. 2760.El 2761.It Fl p 2762Display numbers in parsable 2763.Pq exact 2764values. 2765.It Fl r 2766Recursively display any children of the dataset on the command line. 2767.It Fl s Ar property 2768A property for sorting the output by column in ascending order based on the 2769value of the property. 2770The property must be one of the properties described in the 2771.Sx Properties 2772section, or the special value 2773.Sy name 2774to sort by the dataset name. 2775Multiple properties can be specified at one time using multiple 2776.Fl s 2777property options. 2778Multiple 2779.Fl s 2780options are evaluated from left to right in decreasing order of importance. 2781The following is a list of sorting criteria: 2782.Bl -bullet 2783.It 2784Numeric types sort in numeric order. 2785.It 2786String types sort in alphabetical order. 2787.It 2788Types inappropriate for a row sort that row to the literal bottom, regardless of 2789the specified ordering. 2790.El 2791.Pp 2792If no sorting options are specified the existing behavior of 2793.Nm zfs Cm list 2794is preserved. 2795.It Fl t Ar type 2796A comma-separated list of types to display, where 2797.Ar type 2798is one of 2799.Sy filesystem , 2800.Sy snapshot , 2801.Sy volume , 2802.Sy bookmark , 2803or 2804.Sy all . 2805For example, specifying 2806.Fl t Sy snapshot 2807displays only snapshots. 2808.El 2809.It Xo 2810.Nm 2811.Cm set 2812.Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... 2813.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... 2814.Xc 2815Sets the property or list of properties to the given value(s) for each dataset. 2816Only some properties can be edited. 2817See the 2818.Sx Properties 2819section for more information on what properties can be set and acceptable 2820values. 2821Numeric values can be specified as exact values, or in a human-readable form 2822with a suffix of 2823.Sy B , K , M , G , T , P , E , Z 2824.Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, 2825or zettabytes, respectively 2826.Pc . 2827User properties can be set on snapshots. 2828For more information, see the 2829.Sx User Properties 2830section. 2831.It Xo 2832.Nm 2833.Cm get 2834.Op Fl r Ns | Ns Fl d Ar depth 2835.Op Fl Hp 2836.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 2837.Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc 2838.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 2839.Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... 2840.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... 2841.Xc 2842Displays properties for the given datasets. 2843If no datasets are specified, then the command displays properties for all 2844datasets on the system. 2845For each property, the following columns are displayed: 2846.Bd -literal 2847 name Dataset name 2848 property Property name 2849 value Property value 2850 source Property source. Can either be local, default, 2851 temporary, inherited, or none (-). 2852.Ed 2853.Pp 2854All columns are displayed by default, though this can be controlled by using the 2855.Fl o 2856option. 2857This command takes a comma-separated list of properties as described in the 2858.Sx Native Properties 2859and 2860.Sx User Properties 2861sections. 2862.Pp 2863The special value 2864.Sy all 2865can be used to display all properties that apply to the given dataset's type 2866.Pq filesystem, volume, snapshot, or bookmark . 2867.Bl -tag -width "-H" 2868.It Fl H 2869Display output in a form more easily parsed by scripts. 2870Any headers are omitted, and fields are explicitly separated by a single tab 2871instead of an arbitrary amount of space. 2872.It Fl d Ar depth 2873Recursively display any children of the dataset, limiting the recursion to 2874.Ar depth . 2875A depth of 2876.Sy 1 2877will display only the dataset and its direct children. 2878.It Fl o Ar field 2879A comma-separated list of columns to display. 2880.Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source 2881is the default value. 2882.It Fl p 2883Display numbers in parsable 2884.Pq exact 2885values. 2886.It Fl r 2887Recursively display properties for any children. 2888.It Fl s Ar source 2889A comma-separated list of sources to display. 2890Those properties coming from a source other than those in this list are ignored. 2891Each source must be one of the following: 2892.Sy local , 2893.Sy default , 2894.Sy inherited , 2895.Sy temporary , 2896and 2897.Sy none . 2898The default value is all sources. 2899.It Fl t Ar type 2900A comma-separated list of types to display, where 2901.Ar type 2902is one of 2903.Sy filesystem , 2904.Sy snapshot , 2905.Sy volume , 2906.Sy bookmark , 2907or 2908.Sy all . 2909.El 2910.It Xo 2911.Nm 2912.Cm inherit 2913.Op Fl rS 2914.Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... 2915.Xc 2916Clears the specified property, causing it to be inherited from an ancestor, 2917restored to default if no ancestor has the property set, or with the 2918.Fl S 2919option reverted to the received value if one exists. 2920See the 2921.Sx Properties 2922section for a listing of default values, and details on which properties can be 2923inherited. 2924.Bl -tag -width "-r" 2925.It Fl r 2926Recursively inherit the given property for all children. 2927.It Fl S 2928Revert the property to the received value if one exists; otherwise operate as 2929if the 2930.Fl S 2931option was not specified. 2932.El 2933.It Xo 2934.Nm 2935.Cm remap 2936.Ar filesystem Ns | Ns Ar volume 2937.Xc 2938Remap the indirect blocks in the given filesystem or volume so that they no 2939longer reference blocks on previously removed vdevs and we can eventually 2940shrink the size of the indirect mapping objects for the previously removed 2941vdevs. Note that remapping all blocks might not be possible and that 2942references from snapshots will still exist and cannot be remapped. 2943.It Xo 2944.Nm 2945.Cm upgrade 2946.Xc 2947Displays a list of file systems that are not the most recent version. 2948.It Xo 2949.Nm 2950.Cm upgrade 2951.Fl v 2952.Xc 2953Displays a list of currently supported file system versions. 2954.It Xo 2955.Nm 2956.Cm upgrade 2957.Op Fl r 2958.Op Fl V Ar version 2959.Fl a | Ar filesystem 2960.Xc 2961Upgrades file systems to a new on-disk version. 2962Once this is done, the file systems will no longer be accessible on systems 2963running older versions of the software. 2964.Nm zfs Cm send 2965streams generated from new snapshots of these file systems cannot be accessed on 2966systems running older versions of the software. 2967.Pp 2968In general, the file system version is independent of the pool version. 2969See 2970.Xr zpool 8 2971for information on the 2972.Nm zpool Cm upgrade 2973command. 2974.Pp 2975In some cases, the file system version and the pool version are interrelated and 2976the pool version must be upgraded before the file system version can be 2977upgraded. 2978.Bl -tag -width "-V" 2979.It Fl V Ar version 2980Upgrade to the specified 2981.Ar version . 2982If the 2983.Fl V 2984flag is not specified, this command upgrades to the most recent version. 2985This 2986option can only be used to increase the version number, and only up to the most 2987recent version supported by this software. 2988.It Fl a 2989Upgrade all file systems on all imported pools. 2990.It Ar filesystem 2991Upgrade the specified file system. 2992.It Fl r 2993Upgrade the specified file system and all descendent file systems. 2994.El 2995.It Xo 2996.Nm 2997.Cm userspace 2998.Op Fl Hinp 2999.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 3000.Oo Fl s Ar field Oc Ns ... 3001.Oo Fl S Ar field Oc Ns ... 3002.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 3003.Ar filesystem Ns | Ns Ar snapshot 3004.Xc 3005Displays space consumed by, and quotas on, each user in the specified filesystem 3006or snapshot. 3007This corresponds to the 3008.Sy userused@ Ns Em user , 3009.Sy userobjused@ Ns Em user , 3010.Sy userquota@ Ns Em user, 3011and 3012.Sy userobjquota@ Ns Em user 3013properties. 3014.Bl -tag -width "-H" 3015.It Fl H 3016Do not print headers, use tab-delimited output. 3017.It Fl S Ar field 3018Sort by this field in reverse order. 3019See 3020.Fl s . 3021.It Fl i 3022Translate SID to POSIX ID. 3023The POSIX ID may be ephemeral if no mapping exists. 3024Normal POSIX interfaces 3025.Po for example, 3026.Xr stat 2 , 3027.Nm ls Fl l 3028.Pc 3029perform this translation, so the 3030.Fl i 3031option allows the output from 3032.Nm zfs Cm userspace 3033to be compared directly with those utilities. 3034However, 3035.Fl i 3036may lead to confusion if some files were created by an SMB user before a 3037SMB-to-POSIX name mapping was established. 3038In such a case, some files will be owned by the SMB entity and some by the POSIX 3039entity. 3040However, the 3041.Fl i 3042option will report that the POSIX entity has the total usage and quota for both. 3043.It Fl n 3044Print numeric ID instead of user/group name. 3045.It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... 3046Display only the specified fields from the following set: 3047.Sy type , 3048.Sy name , 3049.Sy used , 3050.Sy quota . 3051The default is to display all fields. 3052.It Fl p 3053Use exact 3054.Pq parsable 3055numeric output. 3056.It Fl s Ar field 3057Sort output by this field. 3058The 3059.Fl s 3060and 3061.Fl S 3062flags may be specified multiple times to sort first by one field, then by 3063another. 3064The default is 3065.Fl s Sy type Fl s Sy name . 3066.It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... 3067Print only the specified types from the following set: 3068.Sy all , 3069.Sy posixuser , 3070.Sy smbuser , 3071.Sy posixgroup , 3072.Sy smbgroup . 3073The default is 3074.Fl t Sy posixuser Ns \&, Ns Sy smbuser . 3075The default can be changed to include group types. 3076.El 3077.It Xo 3078.Nm 3079.Cm groupspace 3080.Op Fl Hinp 3081.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 3082.Oo Fl s Ar field Oc Ns ... 3083.Oo Fl S Ar field Oc Ns ... 3084.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 3085.Ar filesystem Ns | Ns Ar snapshot 3086.Xc 3087Displays space consumed by, and quotas on, each group in the specified 3088filesystem or snapshot. 3089This subcommand is identical to 3090.Nm zfs Cm userspace , 3091except that the default types to display are 3092.Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . 3093.It Xo 3094.Nm 3095.Cm projectspace 3096.Op Fl Hp 3097.Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 3098.Oo Fl s Ar field Oc Ns ... 3099.Oo Fl S Ar field Oc Ns ... 3100.Ar filesystem Ns | Ns Ar snapshot 3101.Xc 3102Displays space consumed by, and quotas on, each project in the specified 3103filesystem or snapshot. 3104This subcommand is identical to 3105.Nm zfs Cm userspace , 3106except that the project identifier is numeral, not name. 3107So need neither the option 3108.Sy -i 3109for SID to POSIX ID nor 3110.Sy -n 3111for numeric ID, nor 3112.Sy -t 3113for types. 3114.It Xo 3115.Nm 3116.Cm project 3117.Oo Fl d Ns | Ns Fl r Ns Oc 3118.Ar file Ns | Ns Ar directory Ns ... 3119.Xc 3120List project identifier (ID) and inherit flag of files or directories. 3121.Bl -tag -width "-d" 3122.It Fl d 3123Show the directory project ID and inherit flag, not its children. 3124It will overwrite the former specified 3125.Fl r 3126option. 3127.It Fl r 3128Show on subdirectories recursively. 3129It will overwrite the former specified 3130.Fl d 3131option. 3132.El 3133.It Xo 3134.Nm 3135.Cm project 3136.Fl C 3137.Oo Fl kr Ns Oc 3138.Ar file Ns | Ns Ar directory Ns ... 3139.Xc 3140Clear project inherit flag and/or ID on the files or directories. 3141.Bl -tag -width "-k" 3142.It Fl k 3143Keep the project ID unchanged. 3144If not specified, the project ID will be reset as zero. 3145.It Fl r 3146Clear on subdirectories recursively. 3147.El 3148.It Xo 3149.Nm 3150.Cm project 3151.Fl c 3152.Oo Fl 0 Ns Oc 3153.Oo Fl d Ns | Ns Fl r Ns Oc 3154.Op Fl p Ar id 3155.Ar file Ns | Ns Ar directory Ns ... 3156.Xc 3157Check project ID and inherit flag on the files or directories, report the 3158entries without project inherit flag or with different project IDs from the 3159specified (via 3160.Fl p 3161option) value or the target directory's project ID. 3162.Bl -tag -width "-0" 3163.It Fl 0 3164Print file name with a trailing NUL instead of newline (by default), like 3165"find -print0". 3166.It Fl d 3167Check the directory project ID and inherit flag, not its children. 3168It will overwrite the former specified 3169.Fl r 3170option. 3171.It Fl p 3172Specify the referenced ID for comparing with the target files or directories' 3173project IDs. 3174If not specified, the target (top) directory's project ID will be used as the 3175referenced one. 3176.It Fl r 3177Check on subdirectories recursively. 3178It will overwrite the former specified 3179.Fl d 3180option. 3181.El 3182.It Xo 3183.Nm 3184.Cm project 3185.Op Fl p Ar id 3186.Oo Fl rs Ns Oc 3187.Ar file Ns | Ns Ar directory Ns ... 3188.Xc 3189Set project ID and/or inherit flag on the files or directories. 3190.Bl -tag -width "-p" 3191.It Fl p 3192Set the files' or directories' project ID with the given value. 3193.It Fl r 3194Set on subdirectories recursively. 3195.It Fl s 3196Set project inherit flag on the given files or directories. 3197It is usually used for setup tree quota on the directory target with 3198.Fl r 3199option specified together. 3200When setup tree quota, by default the directory's project ID will be set to 3201all its descendants unless you specify the project ID via 3202.Fl p 3203option explicitly. 3204.El 3205.It Xo 3206.Nm 3207.Cm mount 3208.Xc 3209Displays all ZFS file systems currently mounted. 3210.It Xo 3211.Nm 3212.Cm mount 3213.Op Fl Olv 3214.Op Fl o Ar options 3215.Fl a | Ar filesystem 3216.Xc 3217Mounts ZFS file systems. 3218.Bl -tag -width "-O" 3219.It Fl O 3220Perform an overlay mount. 3221See 3222.Xr mount 8 3223for more information. 3224.It Fl a 3225Mount all available ZFS file systems. 3226Invoked automatically as part of the boot process. 3227.It Fl l 3228Load keys for encrypted filesystems as they are being mounted. 3229This is equivalent to executing 3230.Nm Cm load-key 3231on each encryption root before mounting it. 3232Note that if a filesystem has a 3233.Sy keylocation 3234of 3235.Sy prompt 3236this will cause the terminal to interactively block after asking for the key. 3237.It Ar filesystem 3238Mount the specified filesystem. 3239.It Fl o Ar options 3240An optional, comma-separated list of mount options to use temporarily for the 3241duration of the mount. 3242See the 3243.Sx Temporary Mount Point Properties 3244section for details. 3245.It Fl v 3246Report mount progress. 3247.El 3248.It Xo 3249.Nm 3250.Cm unmount 3251.Op Fl f 3252.Fl a | Ar filesystem Ns | Ns Ar mountpoint 3253.Xc 3254Unmounts currently mounted ZFS file systems. 3255.Bl -tag -width "-a" 3256.It Fl a 3257Unmount all available ZFS file systems. 3258Invoked automatically as part of the shutdown process. 3259.It Ar filesystem Ns | Ns Ar mountpoint 3260Unmount the specified filesystem. 3261The command can also be given a path to a ZFS file system mount point on the 3262system. 3263.It Fl f 3264Forcefully unmount the file system, even if it is currently in use. 3265.El 3266.It Xo 3267.Nm 3268.Cm share 3269.Fl a | Ar filesystem 3270.Xc 3271Shares available ZFS file systems. 3272.Bl -tag -width "-a" 3273.It Fl a 3274Share all available ZFS file systems. 3275Invoked automatically as part of the boot process. 3276.It Ar filesystem 3277Share the specified filesystem according to the 3278.Sy sharenfs 3279and 3280.Sy sharesmb 3281properties. 3282File systems are shared when the 3283.Sy sharenfs 3284or 3285.Sy sharesmb 3286property is set. 3287.El 3288.It Xo 3289.Nm 3290.Cm unshare 3291.Fl a | Ar filesystem Ns | Ns Ar mountpoint 3292.Xc 3293Unshares currently shared ZFS file systems. 3294.Bl -tag -width "-a" 3295.It Fl a 3296Unshare all available ZFS file systems. 3297Invoked automatically as part of the shutdown process. 3298.It Ar filesystem Ns | Ns Ar mountpoint 3299Unshare the specified filesystem. 3300The command can also be given a path to a ZFS file system shared on the system. 3301.El 3302.It Xo 3303.Nm 3304.Cm bookmark 3305.Ar snapshot bookmark 3306.Xc 3307Creates a bookmark of the given snapshot. 3308Bookmarks mark the point in time when the snapshot was created, and can be used 3309as the incremental source for a 3310.Nm zfs Cm send 3311command. 3312.Pp 3313This feature must be enabled to be used. 3314See 3315.Xr zpool-features 7 3316for details on ZFS feature flags and the 3317.Sy bookmarks 3318feature. 3319.It Xo 3320.Nm 3321.Cm send 3322.Op Fl DLPRbcehnpvw 3323.Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot 3324.Ar snapshot 3325.Xc 3326Creates a stream representation of the second 3327.Ar snapshot , 3328which is written to standard output. 3329The output can be redirected to a file or to a different system 3330.Po for example, using 3331.Xr ssh 1 3332.Pc . 3333By default, a full stream is generated. 3334.Bl -tag -width "-D" 3335.It Fl D , -dedup 3336Generate a deduplicated stream. 3337Blocks which would have been sent multiple times in the send stream will only be 3338sent once. 3339The receiving system must also support this feature to receive a deduplicated 3340stream. 3341This flag can be used regardless of the dataset's 3342.Sy dedup 3343property, but performance will be much better if the filesystem uses a 3344dedup-capable checksum 3345.Po for example, 3346.Sy sha256 3347.Pc . 3348.It Fl I Ar snapshot 3349Generate a stream package that sends all intermediary snapshots from the first 3350snapshot to the second snapshot. 3351For example, 3352.Fl I Em @a Em fs@d 3353is similar to 3354.Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d . 3355The incremental source may be specified as with the 3356.Fl i 3357option. 3358.It Fl L , -large-block 3359Generate a stream which may contain blocks larger than 128KB. 3360This flag has no effect if the 3361.Sy large_blocks 3362pool feature is disabled, or if the 3363.Sy recordsize 3364property of this filesystem has never been set above 128KB. 3365The receiving system must have the 3366.Sy large_blocks 3367pool feature enabled as well. 3368See 3369.Xr zpool-features 7 3370for details on ZFS feature flags and the 3371.Sy large_blocks 3372feature. 3373.It Fl P , -parsable 3374Print machine-parsable verbose information about the stream package generated. 3375.It Fl R , -replicate 3376Generate a replication stream package, which will replicate the specified 3377file system, and all descendent file systems, up to the named snapshot. 3378When received, all properties, snapshots, descendent file systems, and clones 3379are preserved. 3380.Pp 3381If the 3382.Fl i 3383or 3384.Fl I 3385flags are used in conjunction with the 3386.Fl R 3387flag, an incremental replication stream is generated. 3388The current values of properties, and current snapshot and file system names are 3389set when the stream is received. 3390If the 3391.Fl F 3392flag is specified when this stream is received, snapshots and file systems that 3393do not exist on the sending side are destroyed. 3394If the 3395.Fl R 3396flag is used to send encrypted datasets, then 3397.Fl w 3398must also be specified. 3399.It Fl e , -embed 3400Generate a more compact stream by using 3401.Sy WRITE_EMBEDDED 3402records for blocks which are stored more compactly on disk by the 3403.Sy embedded_data 3404pool feature. 3405This flag has no effect if the 3406.Sy embedded_data 3407feature is disabled. 3408The receiving system must have the 3409.Sy embedded_data 3410feature enabled. 3411If the 3412.Sy lz4_compress 3413feature is active on the sending system, then the receiving system must have 3414that feature enabled as well. 3415Datasets that are sent with this flag may not be received as an encrypted 3416dataset, since encrypted datasets cannot use the 3417.Sy embedded_data 3418feature. 3419See 3420.Xr zpool-features 7 3421for details on ZFS feature flags and the 3422.Sy embedded_data 3423feature. 3424.It Fl b, -backup 3425Sends only received property values whether or not they are overridden by local 3426settings, but only if the dataset has ever been received. 3427Use this option when you want 3428.Nm zfs Cm receive 3429to restore received properties backed up on the sent dataset and to avoid 3430sending local settings that may have nothing to do with the source dataset, 3431but only with how the data is backed up. 3432.It Fl c , -compressed 3433Generate a more compact stream by using compressed WRITE records for blocks 3434which are compressed on disk and in memory 3435.Po see the 3436.Sy compression 3437property for details 3438.Pc . 3439If the 3440.Sy lz4_compress 3441feature is active on the sending system, then the receiving system must have 3442that feature enabled as well. 3443If the 3444.Sy large_blocks 3445feature is enabled on the sending system but the 3446.Fl L 3447option is not supplied in conjunction with 3448.Fl c , 3449then the data will be decompressed before sending so it can be split into 3450smaller block sizes. 3451.It Fl h, -holds 3452Generate a stream package that includes any snapshot holds (created with the 3453.Sy zfs hold 3454command), and indicating to 3455.Sy zfs receive 3456that the holds be applied to the dataset on the receiving system. 3457.It Fl i Ar snapshot 3458Generate an incremental stream from the first 3459.Ar snapshot 3460.Pq the incremental source 3461to the second 3462.Ar snapshot 3463.Pq the incremental target . 3464The incremental source can be specified as the last component of the snapshot 3465name 3466.Po the 3467.Sy @ 3468character and following 3469.Pc 3470and it is assumed to be from the same file system as the incremental target. 3471.Pp 3472If the destination is a clone, the source may be the origin snapshot, which must 3473be fully specified 3474.Po for example, 3475.Em pool/fs@origin , 3476not just 3477.Em @origin 3478.Pc . 3479.It Fl n , -dryrun 3480Do a dry-run 3481.Pq Qq No-op 3482send. 3483Do not generate any actual send data. 3484This is useful in conjunction with the 3485.Fl v 3486or 3487.Fl P 3488flags to determine what data will be sent. 3489In this case, the verbose output will be written to standard output 3490.Po contrast with a non-dry-run, where the stream is written to standard output 3491and the verbose output goes to standard error 3492.Pc . 3493.It Fl p , -props 3494Include the dataset's properties in the stream. 3495This flag is implicit when 3496.Fl R 3497is specified. 3498The receiving system must also support this feature. 3499Sends of encrypted datasets must use 3500.Fl w 3501when using this flag. 3502.It Fl w , -raw 3503For encrypted datasets, send data exactly as it exists on disk. 3504This allows backups to be taken even if encryption keys are not currently 3505loaded. 3506The backup may then be received on an untrusted machine since that machine will 3507not have the encryption keys to read the protected data or alter it without 3508being detected. 3509Upon being received, the dataset will have the same encryption keys as it did 3510on the send side, although the 3511.Sy keylocation 3512property will be defaulted to 3513.Sy prompt 3514if not otherwise provided. 3515For unencrypted datasets, this flag will be equivalent to 3516.Fl Lec . 3517Note that if you do not use this flag for sending encrypted datasets, 3518data will be sent unencrypted and may be re-encrypted with a different 3519encryption key on the receiving system, which will disable the ability 3520to do a raw send to that system for incrementals. 3521.It Fl v , -verbose 3522Print verbose information about the stream package generated. 3523This information includes a per-second report of how much data has been sent. 3524.Pp 3525The format of the stream is committed. 3526You will be able to receive your streams on future versions of ZFS . 3527.El 3528.It Xo 3529.Nm 3530.Cm send 3531.Op Fl Lcew 3532.Op Fl i Ar snapshot Ns | Ns Ar bookmark 3533.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 3534.Xc 3535Generate a send stream, which may be of a filesystem, and may be incremental 3536from a bookmark. 3537If the destination is a filesystem or volume, the pool must be read-only, or the 3538filesystem must not be mounted. 3539When the stream generated from a filesystem or volume is received, the default 3540snapshot name will be 3541.Qq --head-- . 3542.Bl -tag -width "-L" 3543.It Fl L , -large-block 3544Generate a stream which may contain blocks larger than 128KB. 3545This flag has no effect if the 3546.Sy large_blocks 3547pool feature is disabled, or if the 3548.Sy recordsize 3549property of this filesystem has never been set above 128KB. 3550The receiving system must have the 3551.Sy large_blocks 3552pool feature enabled as well. 3553See 3554.Xr zpool-features 7 3555for details on ZFS feature flags and the 3556.Sy large_blocks 3557feature. 3558.It Fl c , -compressed 3559Generate a more compact stream by using compressed WRITE records for blocks 3560which are compressed on disk and in memory 3561.Po see the 3562.Sy compression 3563property for details 3564.Pc . 3565If the 3566.Sy lz4_compress 3567feature is active on the sending system, then the receiving system must have 3568that feature enabled as well. 3569If the 3570.Sy large_blocks 3571feature is enabled on the sending system but the 3572.Fl L 3573option is not supplied in conjunction with 3574.Fl c , 3575then the data will be decompressed before sending so it can be split into 3576smaller block sizes. 3577.It Fl e , -embed 3578Generate a more compact stream by using 3579.Sy WRITE_EMBEDDED 3580records for blocks which are stored more compactly on disk by the 3581.Sy embedded_data 3582pool feature. 3583This flag has no effect if the 3584.Sy embedded_data 3585feature is disabled. 3586The receiving system must have the 3587.Sy embedded_data 3588feature enabled. 3589If the 3590.Sy lz4_compress 3591feature is active on the sending system, then the receiving system must have 3592that feature enabled as well. 3593Datasets that are sent with this flag may not be received as an encrypted 3594dataset, since encrypted datasets cannot use the 3595.Sy embedded_data 3596feature. 3597See 3598.Xr zpool-features 7 3599for details on ZFS feature flags and the 3600.Sy embedded_data 3601feature. 3602.It Fl i Ar snapshot Ns | Ns Ar bookmark 3603Generate an incremental send stream. 3604The incremental source must be an earlier snapshot in the destination's history. 3605It will commonly be an earlier snapshot in the destination's file system, in 3606which case it can be specified as the last component of the name 3607.Po the 3608.Sy # 3609or 3610.Sy @ 3611character and following 3612.Pc . 3613.Pp 3614If the incremental target is a clone, the incremental source can be the origin 3615snapshot, or an earlier snapshot in the origin's filesystem, or the origin's 3616origin, etc. 3617.It Fl w , -raw 3618For encrypted datasets, send data exactly as it exists on disk. 3619This allows backups to be taken even if encryption keys are not currently 3620loaded. 3621The backup may then be received on an untrusted machine since that machine will 3622not have the encryption keys to read the protected data or alter it without 3623being detected. 3624Upon being received, the dataset will have the same encryption keys as it did 3625on the send side, although the 3626.Sy keylocation 3627property will be defaulted to 3628.Sy prompt 3629if not otherwise provided. 3630For unencrypted datasets, this flag will be equivalent to 3631.Fl Lec . 3632Note that if you do not use this flag for sending encrypted datasets, 3633data will be sent unencrypted and may be re-encrypted with a different 3634encryption key on the receiving system, which will disable the ability 3635to do a raw send to that system for incrementals. 3636.El 3637.It Xo 3638.Nm 3639.Cm send 3640.Op Fl Penv 3641.Fl t 3642.Ar receive_resume_token 3643.Xc 3644Creates a send stream which resumes an interrupted receive. 3645The 3646.Ar receive_resume_token 3647is the value of this property on the filesystem or volume that was being 3648received into. 3649See the documentation for 3650.Sy zfs receive -s 3651for more details. 3652.It Xo 3653.Nm 3654.Cm receive 3655.Op Fl Fhnsuv 3656.Op Fl o Sy origin Ns = Ns Ar snapshot 3657.Op Fl o Ar property Ns = Ns Ar value 3658.Op Fl x Ar property 3659.Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 3660.Xc 3661.It Xo 3662.Nm 3663.Cm receive 3664.Op Fl Fhnsuv 3665.Op Fl d Ns | Ns Fl e 3666.Op Fl o Sy origin Ns = Ns Ar snapshot 3667.Op Fl o Ar property Ns = Ns Ar value 3668.Op Fl x Ar property 3669.Ar filesystem 3670.Xc 3671Creates a snapshot whose contents are as specified in the stream provided on 3672standard input. 3673If a full stream is received, then a new file system is created as well. 3674Streams are created using the 3675.Nm zfs Cm send 3676subcommand, which by default creates a full stream. 3677.Nm zfs Cm recv 3678can be used as an alias for 3679.Nm zfs Cm receive . 3680.Pp 3681If an incremental stream is received, then the destination file system must 3682already exist, and its most recent snapshot must match the incremental stream's 3683source. 3684For 3685.Sy zvols , 3686the destination device link is destroyed and recreated, which means the 3687.Sy zvol 3688cannot be accessed during the 3689.Cm receive 3690operation. 3691.Pp 3692When a snapshot replication package stream that is generated by using the 3693.Nm zfs Cm send Fl R 3694command is received, any snapshots that do not exist on the sending location are 3695destroyed by using the 3696.Nm zfs Cm destroy Fl d 3697command. 3698.Pp 3699If 3700.Fl o Em property Ns = Ns Ar value 3701or 3702.Fl x Em property 3703is specified, it applies to the effective value of the property throughout 3704the entire subtree of replicated datasets. 3705Effective property values will be 3706set ( 3707.Fl o 3708) or inherited ( 3709.Fl x 3710) on the topmost in the replicated subtree. 3711In descendant datasets, if the property is set by the send stream, it will be 3712overridden by forcing the property to be inherited from the top‐most file 3713system. 3714Received properties are retained in spite of being overridden and may be 3715restored with 3716.Nm zfs Cm inherit Fl S . 3717Specifying 3718.Fl o Sy origin Ns = Ns Em snapshot 3719is a special case because, even if 3720.Sy origin 3721is a read-only property and cannot be set, it's allowed to receive the send 3722stream as a clone of the given snapshot. 3723.Pp 3724Raw encrypted send streams (created with 3725.Nm zfs Cm send Fl w 3726) may only be received as is, and cannot be re-encrypted, decrypted, or 3727recompressed by the receive process. 3728Unencrypted streams can be received as encrypted datasets, either through 3729inheritance or by specifying encryption parameters with the 3730.Fl o 3731options. 3732Note that the 3733.Sy keylocation 3734property cannot be overridden to 3735.Sy prompt 3736during a receive. 3737This is because the receive process itself is already using 3738stdin for the send stream. 3739Instead, the property can be overridden after the receive completes. 3740.Pp 3741The added security provided by raw sends adds some restrictions to the send 3742and receive process. 3743ZFS will not allow a mix of raw receives and non-raw receives. 3744Specifically, any raw incremental receives that are attempted after 3745a non-raw receive will fail. 3746Non-raw receives do not have this restriction and, therefore, are always 3747possible. 3748Because of this, it is best practice to always use either raw sends for 3749their security benefits or non-raw sends for their flexibility when working 3750with encrypted datasets, but not a combination. 3751.Pp 3752The reason for this restriction stems from the inherent restrictions of the 3753AEAD ciphers that ZFS uses to encrypt data. 3754When using ZFS native encryption, each block of data is encrypted against 3755a randomly generated number known as the "initialization vector" (IV), 3756which is stored in the filesystem metadata. 3757This number is required by the encryption algorithms whenever the data is to 3758be decrypted. 3759Together, all of the IVs provided for all of the blocks in a given snapshot 3760are collectively called an "IV set". 3761When ZFS performs a raw send, the IV set is transferred from the source to 3762the destination in the send stream. 3763When ZFS performs a non-raw send, the data is decrypted by the source 3764system and re-encrypted by the destination system, creating a snapshot with 3765effectively the same data, but a different IV set. 3766In order for decryption to work after a raw send, ZFS must ensure that the 3767IV set used on both the source and destination side match. 3768When an incremental raw receive is performed on top of an existing snapshot, 3769ZFS will check to confirm that the "from" snapshot on both the source and 3770destination were using the same IV set, ensuring the new IV set is consistent. 3771.Pp 3772The name of the snapshot 3773.Pq and file system, if a full stream is received 3774that this subcommand creates depends on the argument type and the use of the 3775.Fl d 3776or 3777.Fl e 3778options. 3779.Pp 3780If the argument is a snapshot name, the specified 3781.Ar snapshot 3782is created. 3783If the argument is a file system or volume name, a snapshot with the same name 3784as the sent snapshot is created within the specified 3785.Ar filesystem 3786or 3787.Ar volume . 3788If neither of the 3789.Fl d 3790or 3791.Fl e 3792options are specified, the provided target snapshot name is used exactly as 3793provided. 3794.Pp 3795The 3796.Fl d 3797and 3798.Fl e 3799options cause the file system name of the target snapshot to be determined by 3800appending a portion of the sent snapshot's name to the specified target 3801.Ar filesystem . 3802If the 3803.Fl d 3804option is specified, all but the first element of the sent snapshot's file 3805system path 3806.Pq usually the pool name 3807is used and any required intermediate file systems within the specified one are 3808created. 3809If the 3810.Fl e 3811option is specified, then only the last element of the sent snapshot's file 3812system name 3813.Pq i.e. the name of the source file system itself 3814is used as the target file system name. 3815.Bl -tag -width "-F" 3816.It Fl F 3817Force a rollback of the file system to the most recent snapshot before 3818performing the receive operation. 3819If receiving an incremental replication stream 3820.Po for example, one generated by 3821.Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I 3822.Pc , 3823destroy snapshots and file systems that do not exist on the sending side. 3824.It Fl d 3825Discard the first element of the sent snapshot's file system name, using the 3826remaining elements to determine the name of the target file system for the new 3827snapshot as described in the paragraph above. 3828.It Fl e 3829Discard all but the last element of the sent snapshot's file system name, using 3830that element to determine the name of the target file system for the new 3831snapshot as described in the paragraph above. 3832.It Fl h 3833Skip the receive of holds. 3834There is no effect if holds are not sent. 3835.It Fl n 3836Do not actually receive the stream. 3837This can be useful in conjunction with the 3838.Fl v 3839option to verify the name the receive operation would use. 3840.It Fl o Sy origin Ns = Ns Ar snapshot 3841Forces the stream to be received as a clone of the given snapshot. 3842If the stream is a full send stream, this will create the filesystem 3843described by the stream as a clone of the specified snapshot. 3844Which snapshot was specified will not affect the success or failure of the 3845receive, as long as the snapshot does exist. 3846If the stream is an incremental send stream, all the normal verification will be 3847performed. 3848.It Fl o Em property Ns = Ns Ar value 3849Sets the specified property as if the command 3850.Nm zfs Cm set Em property Ns = Ns Ar value 3851was invoked immediately before the receive. 3852When receiving a stream from 3853.Nm zfs Cm send Fl R , 3854causes the property to be inherited by all descendant datasets, as though 3855.Nm zfs Cm inherit Em property 3856was run on any descendant datasets that have this property set on the 3857sending system. 3858.Pp 3859Any editable property can be set at receive time. 3860Set-once properties bound to the received data, such as 3861.Sy normalization 3862and 3863.Sy casesensitivity , 3864cannot be set at receive time even when the datasets are newly created by 3865.Nm zfs Cm receive . 3866Additionally both settable properties 3867.Sy version 3868and 3869.Sy volsize 3870cannot be set at receive time. 3871.Pp 3872The 3873.Fl o 3874option may be specified multiple times, for different properties. 3875An error results if the same property is specified in multiple 3876.Fl o 3877or 3878.Fl x 3879options. 3880.Pp 3881The 3882.Fl o 3883option may also be used to override encryption properties upon initial 3884receive. 3885This allows unencrypted streams to be received as encrypted datasets. 3886To cause the received dataset (or root dataset of a recursive stream) to be 3887received as an encryption root, specify encryption properties in the same 3888manner as is required for 3889.Nm 3890.Cm create . 3891For instance: 3892.Bd -literal 3893# zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile 3894.Ed 3895.Pp 3896Note that 3897.Op Fl o Ar keylocation Ns = Ns Ar prompt 3898may not be specified here, since stdin is already being utilized for the send 3899stream. 3900Once the receive has completed, you can use 3901.Nm 3902.Cm set 3903to change this setting after the fact. 3904Similarly, you can receive a dataset as an encrypted child by specifying 3905.Op Fl x Ar encryption 3906to force the property to be inherited. 3907Overriding encryption properties (except for 3908.Sy keylocation ) 3909is not possible with raw send streams. 3910.It Fl s 3911If the receive is interrupted, save the partially received state, rather 3912than deleting it. 3913Interruption may be due to premature termination of the stream 3914.Po e.g. due to network failure or failure of the remote system 3915if the stream is being read over a network connection 3916.Pc , 3917a checksum error in the stream, termination of the 3918.Nm zfs Cm receive 3919process, or unclean shutdown of the system. 3920.Pp 3921The receive can be resumed with a stream generated by 3922.Nm zfs Cm send Fl t Ar token , 3923where the 3924.Ar token 3925is the value of the 3926.Sy receive_resume_token 3927property of the filesystem or volume which is received into. 3928.Pp 3929To use this flag, the storage pool must have the 3930.Sy extensible_dataset 3931feature enabled. 3932See 3933.Xr zpool-features 7 3934for details on ZFS feature flags. 3935.It Fl u 3936File system that is associated with the received stream is not mounted. 3937.It Fl v 3938Print verbose information about the stream and the time required to perform the 3939receive operation. 3940.It Fl x Em property 3941Ensures that the effective value of the specified property after the 3942receive is unaffected by the value of that property in the send stream (if any), 3943as if the property had been excluded from the send stream. 3944.Pp 3945If the specified property is not present in the send stream, this option does 3946nothing. 3947.Pp 3948If a received property needs to be overridden, the effective value will be 3949set or inherited, depending on whether the property is inheritable or not. 3950.Pp 3951In the case of an incremental update, 3952.Fl x 3953leaves any existing local setting or explicit inheritance unchanged. 3954.Pp 3955All 3956.Fl o 3957restrictions (e.g. set-once) apply equally to 3958.Fl x . 3959.El 3960.It Xo 3961.Nm 3962.Cm receive 3963.Fl A 3964.Ar filesystem Ns | Ns Ar volume 3965.Xc 3966Abort an interrupted 3967.Nm zfs Cm receive Fl s , 3968deleting its saved partially received state. 3969.It Xo 3970.Nm 3971.Cm allow 3972.Ar filesystem Ns | Ns Ar volume 3973.Xc 3974Displays permissions that have been delegated on the specified filesystem or 3975volume. 3976See the other forms of 3977.Nm zfs Cm allow 3978for more information. 3979.It Xo 3980.Nm 3981.Cm allow 3982.Op Fl dglu 3983.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 3984.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3985.Ar setname Oc Ns ... 3986.Ar filesystem Ns | Ns Ar volume 3987.Xc 3988.It Xo 3989.Nm 3990.Cm allow 3991.Op Fl dl 3992.Fl e Ns | Ns Sy everyone 3993.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3994.Ar setname Oc Ns ... 3995.Ar filesystem Ns | Ns Ar volume 3996.Xc 3997Delegates ZFS administration permission for the file systems to non-privileged 3998users. 3999.Bl -tag -width "-d" 4000.It Fl d 4001Allow only for the descendent file systems. 4002.It Fl e Ns | Ns Sy everyone 4003Specifies that the permissions be delegated to everyone. 4004.It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ... 4005Explicitly specify that permissions are delegated to the group. 4006.It Fl l 4007Allow 4008.Qq locally 4009only for the specified file system. 4010.It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... 4011Explicitly specify that permissions are delegated to the user. 4012.It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 4013Specifies to whom the permissions are delegated. 4014Multiple entities can be specified as a comma-separated list. 4015If neither of the 4016.Fl gu 4017options are specified, then the argument is interpreted preferentially as the 4018keyword 4019.Sy everyone , 4020then as a user name, and lastly as a group name. 4021To specify a user or group named 4022.Qq everyone , 4023use the 4024.Fl g 4025or 4026.Fl u 4027options. 4028To specify a group with the same name as a user, use the 4029.Fl g 4030options. 4031.It Xo 4032.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4033.Ar setname Oc Ns ... 4034.Xc 4035The permissions to delegate. 4036Multiple permissions may be specified as a comma-separated list. 4037Permission names are the same as ZFS subcommand and property names. 4038See the property list below. 4039Property set names, which begin with 4040.Sy @ , 4041may be specified. 4042See the 4043.Fl s 4044form below for details. 4045.El 4046.Pp 4047If neither of the 4048.Fl dl 4049options are specified, or both are, then the permissions are allowed for the 4050file system or volume, and all of its descendents. 4051.Pp 4052Permissions are generally the ability to use a ZFS subcommand or change a ZFS 4053property. 4054The following permissions are available: 4055.Bd -literal 4056NAME TYPE NOTES 4057allow subcommand Must also have the permission that is 4058 being allowed 4059clone subcommand Must also have the 'create' ability and 4060 'mount' ability in the origin file system 4061create subcommand Must also have the 'mount' ability 4062destroy subcommand Must also have the 'mount' ability 4063diff subcommand Allows lookup of paths within a dataset 4064 given an object number, and the ability 4065 to create snapshots necessary to 4066 'zfs diff'. 4067load-key subcommand Allows loading and unloading of encryption key 4068 (see 'zfs load-key' and 'zfs unload-key'). 4069change-key subcommand Allows changing an encryption key via 4070 'zfs change-key'. 4071mount subcommand Allows mount/umount of ZFS datasets 4072promote subcommand Must also have the 'mount' and 'promote' 4073 ability in the origin file system 4074receive subcommand Must also have the 'mount' and 'create' 4075 ability 4076rename subcommand Must also have the 'mount' and 'create' 4077 ability in the new parent 4078rollback subcommand Must also have the 'mount' ability 4079send subcommand 4080share subcommand Allows sharing file systems over NFS 4081 or SMB protocols 4082snapshot subcommand Must also have the 'mount' ability 4083 4084groupquota other Allows accessing any groupquota@... 4085 property 4086groupused other Allows reading any groupused@... property 4087userprop other Allows changing any user property 4088userquota other Allows accessing any userquota@... 4089 property 4090userused other Allows reading any userused@... property 4091projectobjquota other Allows accessing any projectobjquota@... 4092 property 4093projectquota other Allows accessing any projectquota@... property 4094projectobjused other Allows reading any projectobjused@... property 4095projectused other Allows reading any projectused@... property 4096 4097aclinherit property 4098aclmode property 4099atime property 4100canmount property 4101casesensitivity property 4102checksum property 4103compression property 4104copies property 4105devices property 4106exec property 4107filesystem_limit property 4108mountpoint property 4109nbmand property 4110normalization property 4111primarycache property 4112quota property 4113readonly property 4114recordsize property 4115refquota property 4116refreservation property 4117reservation property 4118secondarycache property 4119setuid property 4120sharenfs property 4121sharesmb property 4122snapdir property 4123snapshot_limit property 4124utf8only property 4125version property 4126volblocksize property 4127volsize property 4128vscan property 4129xattr property 4130zoned property 4131.Ed 4132.It Xo 4133.Nm 4134.Cm allow 4135.Fl c 4136.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4137.Ar setname Oc Ns ... 4138.Ar filesystem Ns | Ns Ar volume 4139.Xc 4140Sets 4141.Qq create time 4142permissions. 4143These permissions are granted 4144.Pq locally 4145to the creator of any newly-created descendent file system. 4146.It Xo 4147.Nm 4148.Cm allow 4149.Fl s No @ Ns Ar setname 4150.Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4151.Ar setname Oc Ns ... 4152.Ar filesystem Ns | Ns Ar volume 4153.Xc 4154Defines or adds permissions to a permission set. 4155The set can be used by other 4156.Nm zfs Cm allow 4157commands for the specified file system and its descendents. 4158Sets are evaluated dynamically, so changes to a set are immediately reflected. 4159Permission sets follow the same naming restrictions as ZFS file systems, but the 4160name must begin with 4161.Sy @ , 4162and can be no more than 64 characters long. 4163.It Xo 4164.Nm 4165.Cm unallow 4166.Op Fl dglru 4167.Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 4168.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4169.Ar setname Oc Ns ... Oc 4170.Ar filesystem Ns | Ns Ar volume 4171.Xc 4172.It Xo 4173.Nm 4174.Cm unallow 4175.Op Fl dlr 4176.Fl e Ns | Ns Sy everyone 4177.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4178.Ar setname Oc Ns ... Oc 4179.Ar filesystem Ns | Ns Ar volume 4180.Xc 4181.It Xo 4182.Nm 4183.Cm unallow 4184.Op Fl r 4185.Fl c 4186.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4187.Ar setname Oc Ns ... Oc 4188.Ar filesystem Ns | Ns Ar volume 4189.Xc 4190Removes permissions that were granted with the 4191.Nm zfs Cm allow 4192command. 4193No permissions are explicitly denied, so other permissions granted are still in 4194effect. 4195For example, if the permission is granted by an ancestor. 4196If no permissions are specified, then all permissions for the specified 4197.Ar user , 4198.Ar group , 4199or 4200.Sy everyone 4201are removed. 4202Specifying 4203.Sy everyone 4204.Po or using the 4205.Fl e 4206option 4207.Pc 4208only removes the permissions that were granted to everyone, not all permissions 4209for every user and group. 4210See the 4211.Nm zfs Cm allow 4212command for a description of the 4213.Fl ldugec 4214options. 4215.Bl -tag -width "-r" 4216.It Fl r 4217Recursively remove the permissions from this file system and all descendents. 4218.El 4219.It Xo 4220.Nm 4221.Cm unallow 4222.Op Fl r 4223.Fl s No @ Ns Ar setname 4224.Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 4225.Ar setname Oc Ns ... Oc 4226.Ar filesystem Ns | Ns Ar volume 4227.Xc 4228Removes permissions from a permission set. 4229If no permissions are specified, then all permissions are removed, thus removing 4230the set entirely. 4231.It Xo 4232.Nm 4233.Cm hold 4234.Op Fl r 4235.Ar tag Ar snapshot Ns ... 4236.Xc 4237Adds a single reference, named with the 4238.Ar tag 4239argument, to the specified snapshot or snapshots. 4240Each snapshot has its own tag namespace, and tags must be unique within that 4241space. 4242.Pp 4243If a hold exists on a snapshot, attempts to destroy that snapshot by using the 4244.Nm zfs Cm destroy 4245command return 4246.Er EBUSY . 4247.Bl -tag -width "-r" 4248.It Fl r 4249Specifies that a hold with the given tag is applied recursively to the snapshots 4250of all descendent file systems. 4251.El 4252.It Xo 4253.Nm 4254.Cm holds 4255.Op Fl r 4256.Ar snapshot Ns ... 4257.Xc 4258Lists all existing user references for the given snapshot or snapshots. 4259.Bl -tag -width "-r" 4260.It Fl r 4261Lists the holds that are set on the named descendent snapshots, in addition to 4262listing the holds on the named snapshot. 4263.El 4264.It Xo 4265.Nm 4266.Cm release 4267.Op Fl r 4268.Ar tag Ar snapshot Ns ... 4269.Xc 4270Removes a single reference, named with the 4271.Ar tag 4272argument, from the specified snapshot or snapshots. 4273The tag must already exist for each snapshot. 4274If a hold exists on a snapshot, attempts to destroy that snapshot by using the 4275.Nm zfs Cm destroy 4276command return 4277.Er EBUSY . 4278.Bl -tag -width "-r" 4279.It Fl r 4280Recursively releases a hold with the given tag on the snapshots of all 4281descendent file systems. 4282.El 4283.It Xo 4284.Nm 4285.Cm diff 4286.Op Fl FHt 4287.Ar snapshot Ar snapshot Ns | Ns Ar filesystem 4288.Xc 4289Display the difference between a snapshot of a given filesystem and another 4290snapshot of that filesystem from a later time or the current contents of the 4291filesystem. 4292The first column is a character indicating the type of change, the other columns 4293indicate pathname, new pathname 4294.Pq in case of rename , 4295change in link count, and optionally file type and/or change time. 4296The types of change are: 4297.Bd -literal 4298- The path has been removed 4299+ The path has been created 4300M The path has been modified 4301R The path has been renamed 4302.Ed 4303.Bl -tag -width "-F" 4304.It Fl F 4305Display an indication of the type of file, in a manner similar to the 4306.Fl 4307option of 4308.Xr ls 1 . 4309.Bd -literal 4310B Block device 4311C Character device 4312/ Directory 4313> Door 4314| Named pipe 4315@ Symbolic link 4316P Event port 4317= Socket 4318F Regular file 4319.Ed 4320.It Fl H 4321Give more parsable tab-separated output, without header lines and without 4322arrows. 4323.It Fl t 4324Display the path's inode change time as the first column of output. 4325.El 4326.It Xo 4327.Nm 4328.Cm program 4329.Op Fl jn 4330.Op Fl t Ar timeout 4331.Op Fl m Ar memory_limit 4332.Ar pool script 4333.Op Ar arg1 No ... 4334.Xc 4335Executes 4336.Ar script 4337as a ZFS channel program on 4338.Ar pool . 4339The ZFS channel 4340program interface allows ZFS administrative operations to be run 4341programmatically via a Lua script. 4342The entire script is executed atomically, with no other administrative 4343operations taking effect concurrently. 4344A library of ZFS calls is made available to channel program scripts. 4345Channel programs may only be run with root privileges. 4346.sp 4347For full documentation of the ZFS channel program interface, see the manual 4348page for 4349.Xr zfs-program 8 . 4350.Bl -tag -width "" 4351.It Fl j 4352Display channel program output in JSON format. 4353When this flag is specified and standard output is empty - 4354channel program encountered an error. 4355The details of such an error will be printed to standard error in plain text. 4356.It Fl n 4357Executes a read-only channel program, which runs faster. 4358The program cannot change on-disk state by calling functions from 4359the zfs.sync submodule. 4360The program can be used to gather information such as properties and 4361determining if changes would succeed (zfs.check.*). 4362Without this flag, all pending changes must be synced to disk before 4363a channel program can complete. 4364.It Fl t Ar timeout 4365Execution time limit, in milliseconds. 4366If a channel program executes for longer than the provided timeout, it will 4367be stopped and an error will be returned. 4368The default timeout is 1000 ms, and can be set to a maximum of 10000 ms. 4369.It Fl m Ar memory-limit 4370Memory limit, in bytes. 4371If a channel program attempts to allocate more memory than the given limit, 4372it will be stopped and an error returned. 4373The default memory limit is 10 MB, and can be set to a maximum of 100 MB. 4374.sp 4375All remaining argument strings are passed directly to the channel program as 4376arguments. 4377See 4378.Xr zfs-program 8 4379for more information. 4380.El 4381.It Xo 4382.Nm Cm load-key 4383.Op Fl nr 4384.Op Fl L Ar keylocation 4385.Fl a Ns | Ns filesystem 4386.Xc 4387Use 4388.Ar keylocation 4389instead of the 4390.Sy keylocation 4391property. 4392This will not change the value of the property on the dataset. 4393Note that if used with either 4394.Fl r 4395or 4396.Fl a 4397.Ar keylocation 4398may only be given as 4399.Sy prompt . 4400.Bl -tag -width Ds 4401.It Fl a 4402Loads the keys for all encryption roots in all imported pools. 4403.It Fl n 4404Do a dry-run 4405.Cm load-key . 4406This will cause zfs to simply check that the provided key is correct. 4407This command may be run even if the key is already loaded. 4408.It Fl r 4409Recursively loads the keys for the specified filesystem and all descendent 4410encryption roots. 4411.El 4412.It Xo 4413.Nm 4414.Cm unload-key 4415.Op Fl r 4416.Fl a Ns | Ns Ar filesystem 4417.Xc 4418Unloads a key from ZFS, removing the ability to access the dataset and all of 4419its children that inherit the 4420.Sy encryption 4421property. 4422This requires that the dataset is not currently open or mounted. 4423Once the key is unloaded the 4424.Sy keystatus 4425property will be set to 4426.Sy unavailable . 4427.Bl -tag -width Ds 4428.It Fl a 4429Unloads the keys for all encryption roots in all imported pools. 4430.It Fl r 4431Recursively unloads the keys for the specified filesystem and all descendent 4432encryption roots. 4433.El 4434.It Xo 4435.Nm 4436.Cm change-key 4437.Op Fl il 4438.Op Fl o Sy keylocation Ns = Ns Ar value 4439.Op Fl o Sy keyformat Ns = Ns Ar value 4440.Op Fl o Sy pbkdf2iters Ns = Ns Ar value 4441.Ar filesystem 4442.Xc 4443Allows a user to change the encryption key used to access a dataset. 4444This command requires that the existing key for the dataset is already loaded 4445into ZFS. 4446This command may also be used to change the 4447.Sy keylocation , keyformat , 4448and 4449.Sy pbkdf2iters 4450properties as needed. 4451If the dataset was not previously an encryption root it will become one. 4452Alternatively, the 4453.Fl i 4454flag may be provided to cause an encryption root to inherit the 4455parent's key instead. 4456.Bl -tag -width Ds 4457.It Fl i 4458Indicates that ZFS should make 4459.Ar filesystem 4460inherit the key of its parent. 4461Note that this command can only be run on an encryption root that has an 4462encrypted parent. 4463.It Fl l 4464Ensures the key is loaded before attempting to change the key. 4465This is effectively equivalent to 4466.Qq Nm Cm load-key Ar filesystem ; Nm Cm change-key Ar filesystem . 4467.It Fl o Sy property Ns = Ns Ar value 4468Allows the user to set encryption key properties 4469.Pq 4470.Sy keyformat , keylocation , 4471and 4472.Sy pbkdf2iters 4473while changing the key. 4474This is the only way to alter 4475.Sy keyformat 4476and 4477.Sy pbkdf2iters 4478after the dataset has been created. 4479.El 4480.El 4481.Sh EXIT STATUS 4482The 4483.Nm 4484utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line 4485options were specified. 4486.Sh EXAMPLES 4487.Bl -tag -width "" 4488.It Sy Example 1 No Creating a ZFS File System Hierarchy 4489The following commands create a file system named 4490.Em pool/home 4491and a file system named 4492.Em pool/home/bob . 4493The mount point 4494.Pa /export/home 4495is set for the parent file system, and is automatically inherited by the child 4496file system. 4497.Bd -literal 4498# zfs create pool/home 4499# zfs set mountpoint=/export/home pool/home 4500# zfs create pool/home/bob 4501.Ed 4502.It Sy Example 2 No Creating a ZFS Snapshot 4503The following command creates a snapshot named 4504.Sy yesterday . 4505This snapshot is mounted on demand in the 4506.Pa .zfs/snapshot 4507directory at the root of the 4508.Em pool/home/bob 4509file system. 4510.Bd -literal 4511# zfs snapshot pool/home/bob@yesterday 4512.Ed 4513.It Sy Example 3 No Creating and Destroying Multiple Snapshots 4514The following command creates snapshots named 4515.Sy yesterday 4516of 4517.Em pool/home 4518and all of its descendent file systems. 4519Each snapshot is mounted on demand in the 4520.Pa .zfs/snapshot 4521directory at the root of its file system. 4522The second command destroys the newly created snapshots. 4523.Bd -literal 4524# zfs snapshot -r pool/home@yesterday 4525# zfs destroy -r pool/home@yesterday 4526.Ed 4527.It Sy Example 4 No Disabling and Enabling File System Compression 4528The following command disables the 4529.Sy compression 4530property for all file systems under 4531.Em pool/home . 4532The next command explicitly enables 4533.Sy compression 4534for 4535.Em pool/home/anne . 4536.Bd -literal 4537# zfs set compression=off pool/home 4538# zfs set compression=on pool/home/anne 4539.Ed 4540.It Sy Example 5 No Listing ZFS Datasets 4541The following command lists all active file systems and volumes in the system. 4542Snapshots are displayed if the 4543.Sy listsnaps 4544property is 4545.Sy on . 4546The default is 4547.Sy off . 4548See 4549.Xr zpool 8 4550for more information on pool properties. 4551.Bd -literal 4552# zfs list 4553NAME USED AVAIL REFER MOUNTPOINT 4554pool 450K 457G 18K /pool 4555pool/home 315K 457G 21K /export/home 4556pool/home/anne 18K 457G 18K /export/home/anne 4557pool/home/bob 276K 457G 276K /export/home/bob 4558.Ed 4559.It Sy Example 6 No Setting a Quota on a ZFS File System 4560The following command sets a quota of 50 Gbytes for 4561.Em pool/home/bob . 4562.Bd -literal 4563# zfs set quota=50G pool/home/bob 4564.Ed 4565.It Sy Example 7 No Listing ZFS Properties 4566The following command lists all properties for 4567.Em pool/home/bob . 4568.Bd -literal 4569# zfs get all pool/home/bob 4570NAME PROPERTY VALUE SOURCE 4571pool/home/bob type filesystem - 4572pool/home/bob creation Tue Jul 21 15:53 2009 - 4573pool/home/bob used 21K - 4574pool/home/bob available 20.0G - 4575pool/home/bob referenced 21K - 4576pool/home/bob compressratio 1.00x - 4577pool/home/bob mounted yes - 4578pool/home/bob quota 20G local 4579pool/home/bob reservation none default 4580pool/home/bob recordsize 128K default 4581pool/home/bob mountpoint /pool/home/bob default 4582pool/home/bob sharenfs off default 4583pool/home/bob checksum on default 4584pool/home/bob compression on local 4585pool/home/bob atime on default 4586pool/home/bob devices on default 4587pool/home/bob exec on default 4588pool/home/bob setuid on default 4589pool/home/bob readonly off default 4590pool/home/bob zoned off default 4591pool/home/bob snapdir hidden default 4592pool/home/bob aclmode discard default 4593pool/home/bob aclinherit restricted default 4594pool/home/bob canmount on default 4595pool/home/bob xattr on default 4596pool/home/bob copies 1 default 4597pool/home/bob version 4 - 4598pool/home/bob utf8only off - 4599pool/home/bob normalization none - 4600pool/home/bob casesensitivity sensitive - 4601pool/home/bob vscan off default 4602pool/home/bob nbmand off default 4603pool/home/bob sharesmb off default 4604pool/home/bob refquota none default 4605pool/home/bob refreservation none default 4606pool/home/bob primarycache all default 4607pool/home/bob secondarycache all default 4608pool/home/bob usedbysnapshots 0 - 4609pool/home/bob usedbydataset 21K - 4610pool/home/bob usedbychildren 0 - 4611pool/home/bob usedbyrefreservation 0 - 4612.Ed 4613.Pp 4614The following command gets a single property value. 4615.Bd -literal 4616# zfs get -H -o value compression pool/home/bob 4617on 4618.Ed 4619The following command lists all properties with local settings for 4620.Em pool/home/bob . 4621.Bd -literal 4622# zfs get -r -s local -o name,property,value all pool/home/bob 4623NAME PROPERTY VALUE 4624pool/home/bob quota 20G 4625pool/home/bob compression on 4626.Ed 4627.It Sy Example 8 No Rolling Back a ZFS File System 4628The following command reverts the contents of 4629.Em pool/home/anne 4630to the snapshot named 4631.Sy yesterday , 4632deleting all intermediate snapshots. 4633.Bd -literal 4634# zfs rollback -r pool/home/anne@yesterday 4635.Ed 4636.It Sy Example 9 No Creating a ZFS Clone 4637The following command creates a writable file system whose initial contents are 4638the same as 4639.Em pool/home/bob@yesterday . 4640.Bd -literal 4641# zfs clone pool/home/bob@yesterday pool/clone 4642.Ed 4643.It Sy Example 10 No Promoting a ZFS Clone 4644The following commands illustrate how to test out changes to a file system, and 4645then replace the original file system with the changed one, using clones, clone 4646promotion, and renaming: 4647.Bd -literal 4648# zfs create pool/project/production 4649 populate /pool/project/production with data 4650# zfs snapshot pool/project/production@today 4651# zfs clone pool/project/production@today pool/project/beta 4652 make changes to /pool/project/beta and test them 4653# zfs promote pool/project/beta 4654# zfs rename pool/project/production pool/project/legacy 4655# zfs rename pool/project/beta pool/project/production 4656 once the legacy version is no longer needed, it can be destroyed 4657# zfs destroy pool/project/legacy 4658.Ed 4659.It Sy Example 11 No Inheriting ZFS Properties 4660The following command causes 4661.Em pool/home/bob 4662and 4663.Em pool/home/anne 4664to inherit the 4665.Sy checksum 4666property from their parent. 4667.Bd -literal 4668# zfs inherit checksum pool/home/bob pool/home/anne 4669.Ed 4670.It Sy Example 12 No Remotely Replicating ZFS Data 4671The following commands send a full stream and then an incremental stream to a 4672remote machine, restoring them into 4673.Em poolB/received/fs@a 4674and 4675.Em poolB/received/fs@b , 4676respectively. 4677.Em poolB 4678must contain the file system 4679.Em poolB/received , 4680and must not initially contain 4681.Em poolB/received/fs . 4682.Bd -literal 4683# zfs send pool/fs@a | \e 4684 ssh host zfs receive poolB/received/fs@a 4685# zfs send -i a pool/fs@b | \e 4686 ssh host zfs receive poolB/received/fs 4687.Ed 4688.It Sy Example 13 No Using the zfs receive -d Option 4689The following command sends a full stream of 4690.Em poolA/fsA/fsB@snap 4691to a remote machine, receiving it into 4692.Em poolB/received/fsA/fsB@snap . 4693The 4694.Em fsA/fsB@snap 4695portion of the received snapshot's name is determined from the name of the sent 4696snapshot. 4697.Em poolB 4698must contain the file system 4699.Em poolB/received . 4700If 4701.Em poolB/received/fsA 4702does not exist, it is created as an empty file system. 4703.Bd -literal 4704# zfs send poolA/fsA/fsB@snap | \e 4705 ssh host zfs receive -d poolB/received 4706.Ed 4707.It Sy Example 14 No Setting User Properties 4708The following example sets the user-defined 4709.Sy com.example:department 4710property for a dataset. 4711.Bd -literal 4712# zfs set com.example:department=12345 tank/accounting 4713.Ed 4714.It Sy Example 15 No Performing a Rolling Snapshot 4715The following example shows how to maintain a history of snapshots with a 4716consistent naming scheme. 4717To keep a week's worth of snapshots, the user destroys the oldest snapshot, 4718renames the remaining snapshots, and then creates a new snapshot, as follows: 4719.Bd -literal 4720# zfs destroy -r pool/users@7daysago 4721# zfs rename -r pool/users@6daysago @7daysago 4722# zfs rename -r pool/users@5daysago @6daysago 4723# zfs rename -r pool/users@4daysago @5daysago 4724# zfs rename -r pool/users@3daysago @4daysago 4725# zfs rename -r pool/users@2daysago @3daysago 4726# zfs rename -r pool/users@yesterday @2daysago 4727# zfs rename -r pool/users@today @yesterday 4728# zfs snapshot -r pool/users@today 4729.Ed 4730.It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System 4731The following commands show how to set 4732.Sy sharenfs 4733property options to enable 4734.Sy rw 4735access for a set of 4736.Sy IP 4737addresses and to enable root access for system 4738.Sy neo 4739on the 4740.Em tank/home 4741file system. 4742.Bd -literal 4743# zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home 4744.Ed 4745.Pp 4746If you are using 4747.Sy DNS 4748for host name resolution, specify the fully qualified hostname. 4749.It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset 4750The following example shows how to set permissions so that user 4751.Sy cindys 4752can create, destroy, mount, and take snapshots on 4753.Em tank/cindys . 4754The permissions on 4755.Em tank/cindys 4756are also displayed. 4757.Bd -literal 4758# zfs allow cindys create,destroy,mount,snapshot tank/cindys 4759# zfs allow tank/cindys 4760---- Permissions on tank/cindys -------------------------------------- 4761Local+Descendent permissions: 4762 user cindys create,destroy,mount,snapshot 4763.Ed 4764.Pp 4765Because the 4766.Em tank/cindys 4767mount point permission is set to 755 by default, user 4768.Sy cindys 4769will be unable to mount file systems under 4770.Em tank/cindys . 4771Add an ACE similar to the following syntax to provide mount point access: 4772.Bd -literal 4773# chmod A+user:cindys:add_subdirectory:allow /tank/cindys 4774.Ed 4775.It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset 4776The following example shows how to grant anyone in the group 4777.Sy staff 4778to create file systems in 4779.Em tank/users . 4780This syntax also allows staff members to destroy their own file systems, but not 4781destroy anyone else's file system. 4782The permissions on 4783.Em tank/users 4784are also displayed. 4785.Bd -literal 4786# zfs allow staff create,mount tank/users 4787# zfs allow -c destroy tank/users 4788# zfs allow tank/users 4789---- Permissions on tank/users --------------------------------------- 4790Permission sets: 4791 destroy 4792Local+Descendent permissions: 4793 group staff create,mount 4794.Ed 4795.It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset 4796The following example shows how to define and grant a permission set on the 4797.Em tank/users 4798file system. 4799The permissions on 4800.Em tank/users 4801are also displayed. 4802.Bd -literal 4803# zfs allow -s @pset create,destroy,snapshot,mount tank/users 4804# zfs allow staff @pset tank/users 4805# zfs allow tank/users 4806---- Permissions on tank/users --------------------------------------- 4807Permission sets: 4808 @pset create,destroy,mount,snapshot 4809Local+Descendent permissions: 4810 group staff @pset 4811.Ed 4812.It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset 4813The following example shows to grant the ability to set quotas and reservations 4814on the 4815.Em users/home 4816file system. 4817The permissions on 4818.Em users/home 4819are also displayed. 4820.Bd -literal 4821# zfs allow cindys quota,reservation users/home 4822# zfs allow users/home 4823---- Permissions on users/home --------------------------------------- 4824Local+Descendent permissions: 4825 user cindys quota,reservation 4826cindys% zfs set quota=10G users/home/marks 4827cindys% zfs get quota users/home/marks 4828NAME PROPERTY VALUE SOURCE 4829users/home/marks quota 10G local 4830.Ed 4831.It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset 4832The following example shows how to remove the snapshot permission from the 4833.Sy staff 4834group on the 4835.Em tank/users 4836file system. 4837The permissions on 4838.Em tank/users 4839are also displayed. 4840.Bd -literal 4841# zfs unallow staff snapshot tank/users 4842# zfs allow tank/users 4843---- Permissions on tank/users --------------------------------------- 4844Permission sets: 4845 @pset create,destroy,mount,snapshot 4846Local+Descendent permissions: 4847 group staff @pset 4848.Ed 4849.It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset 4850The following example shows how to see what has changed between a prior 4851snapshot of a ZFS dataset and its current state. 4852The 4853.Fl F 4854option is used to indicate type information for the files affected. 4855.Bd -literal 4856# zfs diff -F tank/test@before tank/test 4857M / /tank/test/ 4858M F /tank/test/linked (+1) 4859R F /tank/test/oldname -> /tank/test/newname 4860- F /tank/test/deleted 4861+ F /tank/test/created 4862M F /tank/test/modified 4863.Ed 4864.El 4865.Sh INTERFACE STABILITY 4866.Sy Committed . 4867.Sh SEE ALSO 4868.Xr gzip 1 , 4869.Xr ssh 1 , 4870.Xr chmod 2 , 4871.Xr stat 2 , 4872.Xr write 2 , 4873.Xr fsync 3C , 4874.Xr dfstab 5 , 4875.Xr acl 7 , 4876.Xr attributes 7 , 4877.Xr mount 8 , 4878.Xr share 8 , 4879.Xr sharemgr 8 , 4880.Xr unshare 8 , 4881.Xr zfs-program 8 , 4882.Xr zonecfg 8 , 4883.Xr zpool 8 4884