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