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