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 https://opensource.org/licenses/CDDL-1.0. 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.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. 22.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org> 23.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. 24.\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org> 25.\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org> 26.\" Copyright (c) 2012, Bryan Drewery <bdrewery@FreeBSD.org> 27.\" Copyright (c) 2013, Steven Hartland <smh@FreeBSD.org> 28.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. 29.\" Copyright (c) 2014, Joyent, Inc. All rights reserved. 30.\" Copyright (c) 2014 by Adam Stevko. All rights reserved. 31.\" Copyright (c) 2014 Integros [integros.com] 32.\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved. 33.\" Copyright (c) 2014, Xin LI <delphij@FreeBSD.org> 34.\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved. 35.\" Copyright 2019 Richard Laager. All rights reserved. 36.\" Copyright 2018 Nexenta Systems, Inc. 37.\" Copyright 2019 Joyent, Inc. 38.\" Copyright (c) 2019, Kjeld Schouten-Lebbing 39.\" Copyright (c) 2022 Hewlett Packard Enterprise Development LP. 40.\" 41.Dd July 21, 2022 42.Dt ZFSPROPS 7 43.Os 44. 45.Sh NAME 46.Nm zfsprops 47.Nd native and user-defined properties of ZFS datasets 48. 49.Sh DESCRIPTION 50Properties are divided into two types, native properties and user-defined 51.Po or 52.Qq user 53.Pc 54properties. 55Native properties either export internal statistics or control ZFS behavior. 56In addition, native properties are either editable or read-only. 57User properties have no effect on ZFS behavior, but you can use them to annotate 58datasets in a way that is meaningful in your environment. 59For more information about user properties, see the 60.Sx User Properties 61section, below. 62. 63.Ss Native Properties 64Every dataset has a set of properties that export statistics about the dataset 65as well as control various behaviors. 66Properties are inherited from the parent unless overridden by the child. 67Some properties apply only to certain types of datasets 68.Pq file systems, volumes, or snapshots . 69.Pp 70The values of numeric properties can be specified using human-readable suffixes 71.Po for example, 72.Sy k , 73.Sy KB , 74.Sy M , 75.Sy Gb , 76and so forth, up to 77.Sy Z 78for zettabyte 79.Pc . 80The following are all valid 81.Pq and equal 82specifications: 83.Li 1536M, 1.5g, 1.50GB . 84.Pp 85The values of non-numeric properties are case sensitive and must be lowercase, 86except for 87.Sy mountpoint , 88.Sy sharenfs , 89and 90.Sy sharesmb . 91.Pp 92The following native properties consist of read-only statistics about the 93dataset. 94These properties can be neither set, nor inherited. 95Native properties apply to all dataset types unless otherwise noted. 96.Bl -tag -width "usedbyrefreservation" 97.It Sy available 98The amount of space available to the dataset and all its children, assuming that 99there is no other activity in the pool. 100Because space is shared within a pool, availability can be limited by any number 101of factors, including physical pool size, quotas, reservations, or other 102datasets within the pool. 103.Pp 104This property can also be referred to by its shortened column name, 105.Sy avail . 106.It Sy compressratio 107For non-snapshots, the compression ratio achieved for the 108.Sy used 109space of this dataset, expressed as a multiplier. 110The 111.Sy used 112property includes descendant datasets, and, for clones, does not include the 113space shared with the origin snapshot. 114For snapshots, the 115.Sy compressratio 116is the same as the 117.Sy refcompressratio 118property. 119Compression can be turned on by running: 120.Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . 121The default value is 122.Sy off . 123.It Sy createtxg 124The transaction group (txg) in which the dataset was created. 125Bookmarks have the same 126.Sy createtxg 127as the snapshot they are initially tied to. 128This property is suitable for ordering a list of snapshots, 129e.g. for incremental send and receive. 130.It Sy creation 131The time this dataset was created. 132.It Sy clones 133For snapshots, this property is a comma-separated list of filesystems or volumes 134which are clones of this snapshot. 135The clones' 136.Sy origin 137property is this snapshot. 138If the 139.Sy clones 140property is not empty, then this snapshot can not be destroyed 141.Po even with the 142.Fl r 143or 144.Fl f 145options 146.Pc . 147The roles of origin and clone can be swapped by promoting the clone with the 148.Nm zfs Cm promote 149command. 150.It Sy defer_destroy 151This property is 152.Sy on 153if the snapshot has been marked for deferred destroy by using the 154.Nm zfs Cm destroy Fl d 155command. 156Otherwise, the property is 157.Sy off . 158.It Sy encryptionroot 159For encrypted datasets, indicates where the dataset is currently inheriting its 160encryption key from. 161Loading or unloading a key for the 162.Sy encryptionroot 163will implicitly load / unload the key for any inheriting datasets (see 164.Nm zfs Cm load-key 165and 166.Nm zfs Cm unload-key 167for details). 168Clones will always share an 169encryption key with their origin. 170See the 171.Sx Encryption 172section of 173.Xr zfs-load-key 8 174for details. 175.It Sy filesystem_count 176The total number of filesystems and volumes that exist under this location in 177the dataset tree. 178This value is only available when a 179.Sy filesystem_limit 180has been set somewhere in the tree under which the dataset resides. 181.It Sy keystatus 182Indicates if an encryption key is currently loaded into ZFS. 183The possible values are 184.Sy none , 185.Sy available , 186and 187.Sy unavailable . 188See 189.Nm zfs Cm load-key 190and 191.Nm zfs Cm unload-key . 192.It Sy guid 193The 64 bit GUID of this dataset or bookmark which does not change over its 194entire lifetime. 195When a snapshot is sent to another pool, the received snapshot has the same GUID. 196Thus, the 197.Sy guid 198is suitable to identify a snapshot across pools. 199.It Sy logicalreferenced 200The amount of space that is 201.Qq logically 202accessible by this dataset. 203See the 204.Sy referenced 205property. 206The logical space ignores the effect of the 207.Sy compression 208and 209.Sy copies 210properties, giving a quantity closer to the amount of data that applications 211see. 212However, it does include space consumed by metadata. 213.Pp 214This property can also be referred to by its shortened column name, 215.Sy lrefer . 216.It Sy logicalused 217The amount of space that is 218.Qq logically 219consumed by this dataset and all its descendents. 220See the 221.Sy used 222property. 223The logical space ignores the effect of the 224.Sy compression 225and 226.Sy copies 227properties, giving a quantity closer to the amount of data that applications 228see. 229However, it does include space consumed by metadata. 230.Pp 231This property can also be referred to by its shortened column name, 232.Sy lused . 233.It Sy mounted 234For file systems, indicates whether the file system is currently mounted. 235This property can be either 236.Sy yes 237or 238.Sy no . 239.It Sy objsetid 240A unique identifier for this dataset within the pool. 241Unlike the dataset's 242.Sy guid , No the Sy objsetid 243of a dataset is not transferred to other pools when the snapshot is copied 244with a send/receive operation. 245The 246.Sy objsetid 247can be reused (for a new dataset) after the dataset is deleted. 248.It Sy origin 249For cloned file systems or volumes, the snapshot from which the clone was 250created. 251See also the 252.Sy clones 253property. 254.It Sy receive_resume_token 255For filesystems or volumes which have saved partially-completed state from 256.Nm zfs Cm receive Fl s , 257this opaque token can be provided to 258.Nm zfs Cm send Fl t 259to resume and complete the 260.Nm zfs Cm receive . 261.It Sy redact_snaps 262For bookmarks, this is the list of snapshot guids the bookmark contains a redaction 263list for. 264For snapshots, this is the list of snapshot guids the snapshot is redacted with 265respect to. 266.It Sy referenced 267The amount of data that is accessible by this dataset, which may or may not be 268shared with other datasets in the pool. 269When a snapshot or clone is created, it initially references the same amount of 270space as the file system or snapshot it was created from, since its contents are 271identical. 272.Pp 273This property can also be referred to by its shortened column name, 274.Sy refer . 275.It Sy refcompressratio 276The compression ratio achieved for the 277.Sy referenced 278space of this dataset, expressed as a multiplier. 279See also the 280.Sy compressratio 281property. 282.It Sy snapshot_count 283The total number of snapshots that exist under this location in the dataset 284tree. 285This value is only available when a 286.Sy snapshot_limit 287has been set somewhere in the tree under which the dataset resides. 288.It Sy type 289The type of dataset: 290.Sy filesystem , 291.Sy volume , 292.Sy snapshot , 293or 294.Sy bookmark . 295.It Sy used 296The amount of space consumed by this dataset and all its descendents. 297This is the value that is checked against this dataset's quota and reservation. 298The space used does not include this dataset's reservation, but does take into 299account the reservations of any descendent datasets. 300The amount of space that a dataset consumes from its parent, as well as the 301amount of space that is freed if this dataset is recursively destroyed, is the 302greater of its space used and its reservation. 303.Pp 304The used space of a snapshot 305.Po see the 306.Sx Snapshots 307section of 308.Xr zfsconcepts 7 309.Pc 310is space that is referenced exclusively by this snapshot. 311If this snapshot is destroyed, the amount of 312.Sy used 313space will be freed. 314Space that is shared by multiple snapshots isn't accounted for in this metric. 315When a snapshot is destroyed, space that was previously shared with this 316snapshot can become unique to snapshots adjacent to it, thus changing the used 317space of those snapshots. 318The used space of the latest snapshot can also be affected by changes in the 319file system. 320Note that the 321.Sy used 322space of a snapshot is a subset of the 323.Sy written 324space of the snapshot. 325.Pp 326The amount of space used, available, or referenced does not take into account 327pending changes. 328Pending changes are generally accounted for within a few seconds. 329Committing a change to a disk using 330.Xr fsync 2 331or 332.Sy O_SYNC 333does not necessarily guarantee that the space usage information is updated 334immediately. 335.It Sy usedby* 336The 337.Sy usedby* 338properties decompose the 339.Sy used 340properties into the various reasons that space is used. 341Specifically, 342.Sy used No = 343.Sy usedbychildren No + 344.Sy usedbydataset No + 345.Sy usedbyrefreservation No + 346.Sy usedbysnapshots . 347These properties are only available for datasets created on 348.Nm zpool 349.Qo version 13 Qc 350pools. 351.It Sy usedbychildren 352The amount of space used by children of this dataset, which would be freed if 353all the dataset's children were destroyed. 354.It Sy usedbydataset 355The amount of space used by this dataset itself, which would be freed if the 356dataset were destroyed 357.Po after first removing any 358.Sy refreservation 359and destroying any necessary snapshots or descendents 360.Pc . 361.It Sy usedbyrefreservation 362The amount of space used by a 363.Sy refreservation 364set on this dataset, which would be freed if the 365.Sy refreservation 366was removed. 367.It Sy usedbysnapshots 368The amount of space consumed by snapshots of this dataset. 369In particular, it is the amount of space that would be freed if all of this 370dataset's snapshots were destroyed. 371Note that this is not simply the sum of the snapshots' 372.Sy used 373properties because space can be shared by multiple snapshots. 374.It Sy userused Ns @ Ns Ar user 375The amount of space consumed by the specified user in this dataset. 376Space is charged to the owner of each file, as displayed by 377.Nm ls Fl l . 378The amount of space charged is displayed by 379.Nm du No and Nm ls Fl s . 380See the 381.Nm zfs Cm userspace 382command for more information. 383.Pp 384Unprivileged users can access only their own space usage. 385The root user, or a user who has been granted the 386.Sy userused 387privilege with 388.Nm zfs Cm allow , 389can access everyone's usage. 390.Pp 391The 392.Sy userused Ns @ Ns Ar … 393properties are not displayed by 394.Nm zfs Cm get Sy all . 395The user's name must be appended after the 396.Sy @ 397symbol, using one of the following forms: 398.Bl -bullet -compact -offset 4n 399.It 400POSIX name 401.Pq Qq joe 402.It 403POSIX numeric ID 404.Pq Qq 789 405.It 406SID name 407.Pq Qq joe.smith@mydomain 408.It 409SID numeric ID 410.Pq Qq S-1-123-456-789 411.El 412.Pp 413Files created on Linux always have POSIX owners. 414.It Sy userobjused Ns @ Ns Ar user 415The 416.Sy userobjused 417property is similar to 418.Sy userused 419but instead it counts the number of objects consumed by a user. 420This property counts all objects allocated on behalf of the user, 421it may differ from the results of system tools such as 422.Nm df Fl i . 423.Pp 424When the property 425.Sy xattr Ns = Ns Sy on 426is set on a file system additional objects will be created per-file to store 427extended attributes. 428These additional objects are reflected in the 429.Sy userobjused 430value and are counted against the user's 431.Sy userobjquota . 432When a file system is configured to use 433.Sy xattr Ns = Ns Sy sa 434no additional internal objects are normally required. 435.It Sy userrefs 436This property is set to the number of user holds on this snapshot. 437User holds are set by using the 438.Nm zfs Cm hold 439command. 440.It Sy groupused Ns @ Ns Ar group 441The amount of space consumed by the specified group in this dataset. 442Space is charged to the group of each file, as displayed by 443.Nm ls Fl l . 444See the 445.Sy userused Ns @ Ns Ar user 446property for more information. 447.Pp 448Unprivileged users can only access their own groups' space usage. 449The root user, or a user who has been granted the 450.Sy groupused 451privilege with 452.Nm zfs Cm allow , 453can access all groups' usage. 454.It Sy groupobjused Ns @ Ns Ar group 455The number of objects consumed by the specified group in this dataset. 456Multiple objects may be charged to the group for each file when extended 457attributes are in use. 458See the 459.Sy userobjused Ns @ Ns Ar user 460property for more information. 461.Pp 462Unprivileged users can only access their own groups' space usage. 463The root user, or a user who has been granted the 464.Sy groupobjused 465privilege with 466.Nm zfs Cm allow , 467can access all groups' usage. 468.It Sy projectused Ns @ Ns Ar project 469The amount of space consumed by the specified project in this dataset. 470Project is identified via the project identifier (ID) that is object-based 471numeral attribute. 472An object can inherit the project ID from its parent object (if the 473parent has the flag of inherit project ID that can be set and changed via 474.Nm chattr Fl /+P 475or 476.Nm zfs project Fl s ) 477when being created. 478The privileged user can set and change object's project 479ID via 480.Nm chattr Fl p 481or 482.Nm zfs project Fl s 483anytime. 484Space is charged to the project of each file, as displayed by 485.Nm lsattr Fl p 486or 487.Nm zfs project . 488See the 489.Sy userused Ns @ Ns Ar user 490property for more information. 491.Pp 492The root user, or a user who has been granted the 493.Sy projectused 494privilege with 495.Nm zfs allow , 496can access all projects' usage. 497.It Sy projectobjused Ns @ Ns Ar project 498The 499.Sy projectobjused 500is similar to 501.Sy projectused 502but instead it counts the number of objects consumed by project. 503When the property 504.Sy xattr Ns = Ns Sy on 505is set on a fileset, ZFS will create additional objects per-file to store 506extended attributes. 507These additional objects are reflected in the 508.Sy projectobjused 509value and are counted against the project's 510.Sy projectobjquota . 511When a filesystem is configured to use 512.Sy xattr Ns = Ns Sy sa 513no additional internal objects are required. 514See the 515.Sy userobjused Ns @ Ns Ar user 516property for more information. 517.Pp 518The root user, or a user who has been granted the 519.Sy projectobjused 520privilege with 521.Nm zfs allow , 522can access all projects' objects usage. 523.It Sy snapshots_changed 524Provides a mechanism to quickly determine whether snapshot list has 525changed without having to mount a dataset or iterate the snapshot list. 526Specifies the time at which a snapshot for a dataset was last 527created or deleted. 528.Pp 529This allows us to be more efficient how often we query snapshots. 530The property is persistent across mount and unmount operations only if the 531.Sy extensible_dataset 532feature is enabled. 533.It Sy volblocksize 534For volumes, specifies the block size of the volume. 535The 536.Sy blocksize 537cannot be changed once the volume has been written, so it should be set at 538volume creation time. 539The default 540.Sy blocksize 541for volumes is 16 Kbytes. 542Any power of 2 from 512 bytes to 128 Kbytes is valid. 543.Pp 544This property can also be referred to by its shortened column name, 545.Sy volblock . 546.It Sy written 547The amount of space 548.Sy referenced 549by this dataset, that was written since the previous snapshot 550.Pq i.e. that is not referenced by the previous snapshot . 551.It Sy written Ns @ Ns Ar snapshot 552The amount of 553.Sy referenced 554space written to this dataset since the specified snapshot. 555This is the space that is referenced by this dataset but was not referenced by 556the specified snapshot. 557.Pp 558The 559.Ar snapshot 560may be specified as a short snapshot name 561.Pq just the part after the Sy @ , 562in which case it will be interpreted as a snapshot in the same filesystem as 563this dataset. 564The 565.Ar snapshot 566may be a full snapshot name 567.Pq Ar filesystem Ns @ Ns Ar snapshot , 568which for clones may be a snapshot in the origin's filesystem 569.Pq or the origin of the origin's filesystem, etc. 570.El 571.Pp 572The following native properties can be used to change the behavior of a ZFS 573dataset. 574.Bl -tag -width "" 575.It Xo 576.Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns 577.Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x 578.Xc 579Controls how ACEs are inherited when files and directories are created. 580.Bl -tag -compact -offset 4n -width "passthrough-x" 581.It Sy discard 582does not inherit any ACEs. 583.It Sy noallow 584only inherits inheritable ACEs that specify 585.Qq deny 586permissions. 587.It Sy restricted 588default, removes the 589.Sy write_acl 590and 591.Sy write_owner 592permissions when the ACE is inherited. 593.It Sy passthrough 594inherits all inheritable ACEs without any modifications. 595.It Sy passthrough-x 596same meaning as 597.Sy passthrough , 598except that the 599.Sy owner@ , group@ , No and Sy everyone@ 600ACEs inherit the execute permission only if the file creation mode also requests 601the execute bit. 602.El 603.Pp 604When the property value is set to 605.Sy passthrough , 606files are created with a mode determined by the inheritable ACEs. 607If no inheritable ACEs exist that affect the mode, then the mode is set in 608accordance to the requested mode from the application. 609.Pp 610The 611.Sy aclinherit 612property does not apply to POSIX ACLs. 613.It Xo 614.Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns 615.Sy passthrough Ns | Ns Sy restricted Ns 616.Xc 617Controls how an ACL is modified during chmod(2) and how inherited ACEs 618are modified by the file creation mode: 619.Bl -tag -compact -offset 4n -width "passthrough" 620.It Sy discard 621default, deletes all 622.Sy ACEs 623except for those representing 624the mode of the file or directory requested by 625.Xr chmod 2 . 626.It Sy groupmask 627reduces permissions granted in all 628.Sy ALLOW 629entries found in the 630.Sy ACL 631such that they are no greater than the group permissions specified by 632.Xr chmod 2 . 633.It Sy passthrough 634indicates that no changes are made to the ACL other than creating or updating 635the necessary ACL entries to represent the new mode of the file or directory. 636.It Sy restricted 637will cause the 638.Xr chmod 2 639operation to return an error when used on any file or directory which has 640a non-trivial ACL whose entries can not be represented by a mode. 641.Xr chmod 2 642is required to change the set user ID, set group ID, or sticky bits on a file 643or directory, as they do not have equivalent ACL entries. 644In order to use 645.Xr chmod 2 646on a file or directory with a non-trivial ACL when 647.Sy aclmode 648is set to 649.Sy restricted , 650you must first remove all ACL entries which do not represent the current mode. 651.El 652.It Sy acltype Ns = Ns Sy off Ns | Ns Sy nfsv4 Ns | Ns Sy posix 653Controls whether ACLs are enabled and if so what type of ACL to use. 654When this property is set to a type of ACL not supported by the current 655platform, the behavior is the same as if it were set to 656.Sy off . 657.Bl -tag -compact -offset 4n -width "posixacl" 658.It Sy off 659default on Linux, when a file system has the 660.Sy acltype 661property set to off then ACLs are disabled. 662.It Sy noacl 663an alias for 664.Sy off 665.It Sy nfsv4 666default on 667.Fx , 668indicates that NFSv4-style ZFS ACLs should be used. 669These ACLs can be managed with the 670.Xr getfacl 1 671and 672.Xr setfacl 1 . 673The 674.Sy nfsv4 675ZFS ACL type is not yet supported on Linux. 676.It Sy posix 677indicates POSIX ACLs should be used. 678POSIX ACLs are specific to Linux and are not functional on other platforms. 679POSIX ACLs are stored as an extended 680attribute and therefore will not overwrite any existing NFSv4 ACLs which 681may be set. 682.It Sy posixacl 683an alias for 684.Sy posix 685.El 686.Pp 687To obtain the best performance when setting 688.Sy posix 689users are strongly encouraged to set the 690.Sy xattr Ns = Ns Sy sa 691property. 692This will result in the POSIX ACL being stored more efficiently on disk. 693But as a consequence, all new extended attributes will only be 694accessible from OpenZFS implementations which support the 695.Sy xattr Ns = Ns Sy sa 696property. 697See the 698.Sy xattr 699property for more details. 700.It Sy atime Ns = Ns Sy on Ns | Ns Sy off 701Controls whether the access time for files is updated when they are read. 702Turning this property off avoids producing write traffic when reading files and 703can result in significant performance gains, though it might confuse mailers 704and other similar utilities. 705The values 706.Sy on 707and 708.Sy off 709are equivalent to the 710.Sy atime 711and 712.Sy noatime 713mount options. 714The default value is 715.Sy on . 716See also 717.Sy relatime 718below. 719.It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto 720If this property is set to 721.Sy off , 722the file system cannot be mounted, and is ignored by 723.Nm zfs Cm mount Fl a . 724Setting this property to 725.Sy off 726is similar to setting the 727.Sy mountpoint 728property to 729.Sy none , 730except that the dataset still has a normal 731.Sy mountpoint 732property, which can be inherited. 733Setting this property to 734.Sy off 735allows datasets to be used solely as a mechanism to inherit properties. 736One example of setting 737.Sy canmount Ns = Ns Sy off 738is to have two datasets with the same 739.Sy mountpoint , 740so that the children of both datasets appear in the same directory, but might 741have different inherited characteristics. 742.Pp 743When set to 744.Sy noauto , 745a dataset can only be mounted and unmounted explicitly. 746The dataset is not mounted automatically when the dataset is created or 747imported, nor is it mounted by the 748.Nm zfs Cm mount Fl a 749command or unmounted by the 750.Nm zfs Cm unmount Fl a 751command. 752.Pp 753This property is not inherited. 754.It Xo 755.Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns 756.Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns 757.Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr Ns | Ns Sy blake3 758.Xc 759Controls the checksum used to verify data integrity. 760The default value is 761.Sy on , 762which automatically selects an appropriate algorithm 763.Po currently, 764.Sy fletcher4 , 765but this may change in future releases 766.Pc . 767The value 768.Sy off 769disables integrity checking on user data. 770The value 771.Sy noparity 772not only disables integrity but also disables maintaining parity for user data. 773This setting is used internally by a dump device residing on a RAID-Z pool and 774should not be used by any other dataset. 775Disabling checksums is 776.Em NOT 777a recommended practice. 778.Pp 779The 780.Sy sha512 , 781.Sy skein , 782.Sy edonr , 783and 784.Sy blake3 785checksum algorithms require enabling the appropriate features on the pool. 786.Pp 787Please see 788.Xr zpool-features 7 789for more information on these algorithms. 790.Pp 791Changing this property affects only newly-written data. 792.It Xo 793.Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns 794.Sy gzip- Ns Ar N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle Ns | Ns Sy zstd Ns | Ns 795.Sy zstd- Ns Ar N Ns | Ns Sy zstd-fast Ns | Ns Sy zstd-fast- Ns Ar N 796.Xc 797Controls the compression algorithm used for this dataset. 798.Pp 799When set to 800.Sy on 801(the default), indicates that the current default compression algorithm should be used. 802The default balances compression and decompression speed, with compression ratio 803and is expected to work well on a wide variety of workloads. 804Unlike all other settings for this property, 805.Sy on 806does not select a fixed compression type. 807As new compression algorithms are added to ZFS and enabled on a pool, the 808default compression algorithm may change. 809The current default compression algorithm is either 810.Sy lzjb 811or, if the 812.Sy lz4_compress 813feature is enabled, 814.Sy lz4 . 815.Pp 816The 817.Sy lz4 818compression algorithm is a high-performance replacement for the 819.Sy lzjb 820algorithm. 821It features significantly faster compression and decompression, as well as a 822moderately higher compression ratio than 823.Sy lzjb , 824but can only be used on pools with the 825.Sy lz4_compress 826feature set to 827.Sy enabled . 828See 829.Xr zpool-features 7 830for details on ZFS feature flags and the 831.Sy lz4_compress 832feature. 833.Pp 834The 835.Sy lzjb 836compression algorithm is optimized for performance while providing decent data 837compression. 838.Pp 839The 840.Sy gzip 841compression algorithm uses the same compression as the 842.Xr gzip 1 843command. 844You can specify the 845.Sy gzip 846level by using the value 847.Sy gzip- Ns Ar N , 848where 849.Ar N 850is an integer from 1 851.Pq fastest 852to 9 853.Pq best compression ratio . 854Currently, 855.Sy gzip 856is equivalent to 857.Sy gzip-6 858.Po which is also the default for 859.Xr gzip 1 860.Pc . 861.Pp 862The 863.Sy zstd 864compression algorithm provides both high compression ratios and good performance. 865You can specify the 866.Sy zstd 867level by using the value 868.Sy zstd- Ns Ar N , 869where 870.Ar N 871is an integer from 1 872.Pq fastest 873to 19 874.Pq best compression ratio . 875.Sy zstd 876is equivalent to 877.Sy zstd-3 . 878.Pp 879Faster speeds at the cost of the compression ratio can be requested by 880setting a negative 881.Sy zstd 882level. 883This is done using 884.Sy zstd-fast- Ns Ar N , 885where 886.Ar N 887is an integer in 888.Bq Sy 1 Ns - Ns Sy 10 , 20 , 30 , No … , Sy 100 , 500 , 1000 889which maps to a negative 890.Sy zstd 891level. 892The lower the level the faster the compression \(em 893.Sy 1000 894provides the fastest compression and lowest compression ratio. 895.Sy zstd-fast 896is equivalent to 897.Sy zstd-fast- Ns Ar 1 . 898.Pp 899The 900.Sy zle 901compression algorithm compresses runs of zeros. 902.Pp 903This property can also be referred to by its shortened column name 904.Sy compress . 905Changing this property affects only newly-written data. 906.Pp 907When any setting except 908.Sy off 909is selected, compression will explicitly check for blocks consisting of only 910zeroes (the NUL byte). 911When a zero-filled block is detected, it is stored as 912a hole and not compressed using the indicated compression algorithm. 913.Pp 914Any block being compressed must be no larger than 7/8 of its original size 915after compression, otherwise the compression will not be considered worthwhile 916and the block saved uncompressed. 917Note that when the logical block is less than 9188 times the disk sector size this effectively reduces the necessary compression 919ratio; for example, 8 KiB blocks on disks with 4 KiB disk sectors must compress to 1/2 920or less of their original size. 921.It Xo 922.Sy context Ns = Ns Sy none Ns | Ns 923.Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level 924.Xc 925This flag sets the SELinux context for all files in the file system under 926a mount point for that file system. 927See 928.Xr selinux 8 929for more information. 930.It Xo 931.Sy fscontext Ns = Ns Sy none Ns | Ns 932.Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level 933.Xc 934This flag sets the SELinux context for the file system file system being 935mounted. 936See 937.Xr selinux 8 938for more information. 939.It Xo 940.Sy defcontext Ns = Ns Sy none Ns | Ns 941.Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level 942.Xc 943This flag sets the SELinux default context for unlabeled files. 944See 945.Xr selinux 8 946for more information. 947.It Xo 948.Sy rootcontext Ns = Ns Sy none Ns | Ns 949.Ar SELinux-User : Ns Ar SELinux-Role : Ns Ar SELinux-Type : Ns Ar Sensitivity-Level 950.Xc 951This flag sets the SELinux context for the root inode of the file system. 952See 953.Xr selinux 8 954for more information. 955.It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 956Controls the number of copies of data stored for this dataset. 957These copies are in addition to any redundancy provided by the pool, for 958example, mirroring or RAID-Z. 959The copies are stored on different disks, if possible. 960The space used by multiple copies is charged to the associated file and dataset, 961changing the 962.Sy used 963property and counting against quotas and reservations. 964.Pp 965Changing this property only affects newly-written data. 966Therefore, set this property at file system creation time by using the 967.Fl o Sy copies Ns = Ns Ar N 968option. 969.Pp 970Remember that ZFS will not import a pool with a missing top-level vdev. 971Do 972.Em NOT 973create, for example a two-disk striped pool and set 974.Sy copies Ns = Ns Ar 2 975on some datasets thinking you have setup redundancy for them. 976When a disk fails you will not be able to import the pool 977and will have lost all of your data. 978.Pp 979Encrypted datasets may not have 980.Sy copies Ns = Ns Ar 3 981since the implementation stores some encryption metadata where the third copy 982would normally be. 983.It Sy devices Ns = Ns Sy on Ns | Ns Sy off 984Controls whether device nodes can be opened on this file system. 985The default value is 986.Sy on . 987The values 988.Sy on 989and 990.Sy off 991are equivalent to the 992.Sy dev 993and 994.Sy nodev 995mount options. 996.It Xo 997.Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns 998.Sy sha256 Ns Oo , Ns Sy verify Oc Ns | Ns Sy sha512 Ns Oo , Ns Sy verify Oc Ns | Ns Sy skein Ns Oo , Ns Sy verify Oc Ns | Ns 999.Sy edonr , Ns Sy verify Ns | Ns Sy blake3 Ns Oo , Ns Sy verify Oc Ns 1000.Xc 1001Configures deduplication for a dataset. 1002The default value is 1003.Sy off . 1004The default deduplication checksum is 1005.Sy sha256 1006(this may change in the future). 1007When 1008.Sy dedup 1009is enabled, the checksum defined here overrides the 1010.Sy checksum 1011property. 1012Setting the value to 1013.Sy verify 1014has the same effect as the setting 1015.Sy sha256 , Ns Sy verify . 1016.Pp 1017If set to 1018.Sy verify , 1019ZFS will do a byte-to-byte comparison in case of two blocks having the same 1020signature to make sure the block contents are identical. 1021Specifying 1022.Sy verify 1023is mandatory for the 1024.Sy edonr 1025algorithm. 1026.Pp 1027Unless necessary, deduplication should 1028.Em not 1029be enabled on a system. 1030See the 1031.Sx Deduplication 1032section of 1033.Xr zfsconcepts 7 . 1034.It Xo 1035.Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns 1036.Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k 1037.Xc 1038Specifies a compatibility mode or literal value for the size of dnodes in the 1039file system. 1040The default value is 1041.Sy legacy . 1042Setting this property to a value other than 1043.Sy legacy No requires the Sy large_dnode No pool feature to be enabled. 1044.Pp 1045Consider setting 1046.Sy dnodesize 1047to 1048.Sy auto 1049if the dataset uses the 1050.Sy xattr Ns = Ns Sy sa 1051property setting and the workload makes heavy use of extended attributes. 1052This 1053may be applicable to SELinux-enabled systems, Lustre servers, and Samba 1054servers, for example. 1055Literal values are supported for cases where the optimal 1056size is known in advance and for performance testing. 1057.Pp 1058Leave 1059.Sy dnodesize 1060set to 1061.Sy legacy 1062if you need to receive a send stream of this dataset on a pool that doesn't 1063enable the 1064.Sy large_dnode 1065feature, or if you need to import this pool on a system that doesn't support the 1066.Sy large_dnode No feature. 1067.Pp 1068This property can also be referred to by its shortened column name, 1069.Sy dnsize . 1070.It Xo 1071.Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns 1072.Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns 1073.Sy aes-192-gcm Ns | Ns Sy aes-256-gcm 1074.Xc 1075Controls the encryption cipher suite (block cipher, key length, and mode) used 1076for this dataset. 1077Requires the 1078.Sy encryption 1079feature to be enabled on the pool. 1080Requires a 1081.Sy keyformat 1082to be set at dataset creation time. 1083.Pp 1084Selecting 1085.Sy encryption Ns = Ns Sy on 1086when creating a dataset indicates that the default encryption suite will be 1087selected, which is currently 1088.Sy aes-256-gcm . 1089In order to provide consistent data protection, encryption must be specified at 1090dataset creation time and it cannot be changed afterwards. 1091.Pp 1092For more details and caveats about encryption see the 1093.Sx Encryption 1094section of 1095.Xr zfs-load-key 8 . 1096.It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase 1097Controls what format the user's encryption key will be provided as. 1098This property is only set when the dataset is encrypted. 1099.Pp 1100Raw keys and hex keys must be 32 bytes long (regardless of the chosen 1101encryption suite) and must be randomly generated. 1102A raw key can be generated with the following command: 1103.Dl # Nm dd Sy if=/dev/urandom bs=32 count=1 Sy of= Ns Pa /path/to/output/key 1104.Pp 1105Passphrases must be between 8 and 512 bytes long and will be processed through 1106PBKDF2 before being used (see the 1107.Sy pbkdf2iters 1108property). 1109Even though the encryption suite cannot be changed after dataset creation, 1110the keyformat can be with 1111.Nm zfs Cm change-key . 1112.It Xo 1113.Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Ar /absolute/file/path Ns | Ns Sy https:// Ns Ar address Ns | Ns Sy http:// Ns Ar address 1114.Xc 1115Controls where the user's encryption key will be loaded from by default for 1116commands such as 1117.Nm zfs Cm load-key 1118and 1119.Nm zfs Cm mount Fl l . 1120This property is only set for encrypted datasets which are encryption roots. 1121If unspecified, the default is 1122.Sy prompt . 1123.Pp 1124Even though the encryption suite cannot be changed after dataset creation, the 1125keylocation can be with either 1126.Nm zfs Cm set 1127or 1128.Nm zfs Cm change-key . 1129If 1130.Sy prompt 1131is selected ZFS will ask for the key at the command prompt when it is required 1132to access the encrypted data (see 1133.Nm zfs Cm load-key 1134for details). 1135This setting will also allow the key to be passed in via the standard input stream, 1136but users should be careful not to place keys which should be kept secret on 1137the command line. 1138If a file URI is selected, the key will be loaded from the 1139specified absolute file path. 1140If an HTTPS or HTTP URL is selected, it will be GETted using 1141.Xr fetch 3 , 1142libcurl, or nothing, depending on compile-time configuration and run-time availability. 1143The 1144.Sy SSL_CA_CERT_FILE 1145environment variable can be set to set the location 1146of the concatenated certificate store. 1147The 1148.Sy SSL_CA_CERT_PATH 1149environment variable can be set to override the location 1150of the directory containing the certificate authority bundle. 1151The 1152.Sy SSL_CLIENT_CERT_FILE 1153and 1154.Sy SSL_CLIENT_KEY_FILE 1155environment variables can be set to configure the path 1156to the client certificate and its key. 1157.It Sy pbkdf2iters Ns = Ns Ar iterations 1158Controls the number of PBKDF2 iterations that a 1159.Sy passphrase 1160encryption key should be run through when processing it into an encryption key. 1161This property is only defined when encryption is enabled and a keyformat of 1162.Sy passphrase 1163is selected. 1164The goal of PBKDF2 is to significantly increase the 1165computational difficulty needed to brute force a user's passphrase. 1166This is accomplished by forcing the attacker to run each passphrase through a 1167computationally expensive hashing function many times before they arrive at the 1168resulting key. 1169A user who actually knows the passphrase will only have to pay this cost once. 1170As CPUs become better at processing, this number should be 1171raised to ensure that a brute force attack is still not possible. 1172The current default is 1173.Sy 350000 1174and the minimum is 1175.Sy 100000 . 1176This property may be changed with 1177.Nm zfs Cm change-key . 1178.It Sy exec Ns = Ns Sy on Ns | Ns Sy off 1179Controls whether processes can be executed from within this file system. 1180The default value is 1181.Sy on . 1182The values 1183.Sy on 1184and 1185.Sy off 1186are equivalent to the 1187.Sy exec 1188and 1189.Sy noexec 1190mount options. 1191.It Sy filesystem_limit Ns = Ns Ar count Ns | Ns Sy none 1192Limits the number of filesystems and volumes that can exist under this point in 1193the dataset tree. 1194The limit is not enforced if the user is allowed to change the limit. 1195Setting a 1196.Sy filesystem_limit 1197to 1198.Sy on 1199a descendent of a filesystem that already has a 1200.Sy filesystem_limit 1201does not override the ancestor's 1202.Sy filesystem_limit , 1203but rather imposes an additional limit. 1204This feature must be enabled to be used 1205.Po see 1206.Xr zpool-features 7 1207.Pc . 1208.It Sy special_small_blocks Ns = Ns Ar size 1209This value represents the threshold block size for including small file 1210blocks into the special allocation class. 1211Blocks smaller than or equal to this 1212value will be assigned to the special allocation class while greater blocks 1213will be assigned to the regular class. 1214Valid values are zero or a power of two from 512 up to 1048576 (1 MiB). 1215The default size is 0 which means no small file blocks 1216will be allocated in the special class. 1217.Pp 1218Before setting this property, a special class vdev must be added to the 1219pool. 1220See 1221.Xr zpoolconcepts 7 1222for more details on the special allocation class. 1223.It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy 1224Controls the mount point used for this file system. 1225See the 1226.Sx Mount Points 1227section of 1228.Xr zfsconcepts 7 1229for more information on how this property is used. 1230.Pp 1231When the 1232.Sy mountpoint 1233property is changed for a file system, the file system and any children that 1234inherit the mount point are unmounted. 1235If the new value is 1236.Sy legacy , 1237then they remain unmounted. 1238Otherwise, they are automatically remounted in the new location if the property 1239was previously 1240.Sy legacy 1241or 1242.Sy none , 1243or if they were mounted before the property was changed. 1244In addition, any shared file systems are unshared and shared in the new 1245location. 1246.It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off 1247Controls whether the file system should be mounted with 1248.Sy nbmand 1249.Pq Non-blocking mandatory locks . 1250This is used for SMB clients. 1251Changes to this property only take effect when the file system is umounted and 1252remounted. 1253Support for these locks is scarce and not described by POSIX. 1254.It Sy overlay Ns = Ns Sy on Ns | Ns Sy off 1255Allow mounting on a busy directory or a directory which already contains 1256files or directories. 1257This is the default mount behavior for Linux and 1258.Fx 1259file systems. 1260On these platforms the property is 1261.Sy on 1262by default. 1263Set to 1264.Sy off 1265to disable overlay mounts for consistency with OpenZFS on other platforms. 1266.It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata 1267Controls what is cached in the primary cache 1268.Pq ARC . 1269If this property is set to 1270.Sy all , 1271then both user data and metadata is cached. 1272If this property is set to 1273.Sy none , 1274then neither user data nor metadata is cached. 1275If this property is set to 1276.Sy metadata , 1277then only metadata is cached. 1278The default value is 1279.Sy all . 1280.It Sy quota Ns = Ns Ar size Ns | Ns Sy none 1281Limits the amount of space a dataset and its descendents can consume. 1282This property enforces a hard limit on the amount of space used. 1283This includes all space consumed by descendents, including file systems and 1284snapshots. 1285Setting a quota on a descendent of a dataset that already has a quota does not 1286override the ancestor's quota, but rather imposes an additional limit. 1287.Pp 1288Quotas cannot be set on volumes, as the 1289.Sy volsize 1290property acts as an implicit quota. 1291.It Sy snapshot_limit Ns = Ns Ar count Ns | Ns Sy none 1292Limits the number of snapshots that can be created on a dataset and its 1293descendents. 1294Setting a 1295.Sy snapshot_limit 1296on a descendent of a dataset that already has a 1297.Sy snapshot_limit 1298does not override the ancestor's 1299.Sy snapshot_limit , 1300but rather imposes an additional limit. 1301The limit is not enforced if the user is allowed to change the limit. 1302For example, this means that recursive snapshots taken from the global zone are 1303counted against each delegated dataset within a zone. 1304This feature must be enabled to be used 1305.Po see 1306.Xr zpool-features 7 1307.Pc . 1308.It Sy userquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none 1309Limits the amount of space consumed by the specified user. 1310User space consumption is identified by the 1311.Sy userspace@ Ns Ar user 1312property. 1313.Pp 1314Enforcement of user quotas may be delayed by several seconds. 1315This delay means that a user might exceed their quota before the system notices 1316that they are over quota and begins to refuse additional writes with the 1317.Er EDQUOT 1318error message. 1319See the 1320.Nm zfs Cm userspace 1321command for more information. 1322.Pp 1323Unprivileged users can only access their own groups' space usage. 1324The root user, or a user who has been granted the 1325.Sy userquota 1326privilege with 1327.Nm zfs Cm allow , 1328can get and set everyone's quota. 1329.Pp 1330This property is not available on volumes, on file systems before version 4, or 1331on pools before version 15. 1332The 1333.Sy userquota@ Ns Ar … 1334properties are not displayed by 1335.Nm zfs Cm get Sy all . 1336The user's name must be appended after the 1337.Sy @ 1338symbol, using one of the following forms: 1339.Bl -bullet -compact -offset 4n 1340.It 1341POSIX name 1342.Pq Qq joe 1343.It 1344POSIX numeric ID 1345.Pq Qq 789 1346.It 1347SID name 1348.Pq Qq joe.smith@mydomain 1349.It 1350SID numeric ID 1351.Pq Qq S-1-123-456-789 1352.El 1353.Pp 1354Files created on Linux always have POSIX owners. 1355.It Sy userobjquota@ Ns Ar user Ns = Ns Ar size Ns | Ns Sy none 1356The 1357.Sy userobjquota 1358is similar to 1359.Sy userquota 1360but it limits the number of objects a user can create. 1361Please refer to 1362.Sy userobjused 1363for more information about how objects are counted. 1364.It Sy groupquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none 1365Limits the amount of space consumed by the specified group. 1366Group space consumption is identified by the 1367.Sy groupused@ Ns Ar group 1368property. 1369.Pp 1370Unprivileged users can access only their own groups' space usage. 1371The root user, or a user who has been granted the 1372.Sy groupquota 1373privilege with 1374.Nm zfs Cm allow , 1375can get and set all groups' quotas. 1376.It Sy groupobjquota@ Ns Ar group Ns = Ns Ar size Ns | Ns Sy none 1377The 1378.Sy groupobjquota 1379is similar to 1380.Sy groupquota 1381but it limits number of objects a group can consume. 1382Please refer to 1383.Sy userobjused 1384for more information about how objects are counted. 1385.It Sy projectquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none 1386Limits the amount of space consumed by the specified project. 1387Project space consumption is identified by the 1388.Sy projectused@ Ns Ar project 1389property. 1390Please refer to 1391.Sy projectused 1392for more information about how project is identified and set/changed. 1393.Pp 1394The root user, or a user who has been granted the 1395.Sy projectquota 1396privilege with 1397.Nm zfs allow , 1398can access all projects' quota. 1399.It Sy projectobjquota@ Ns Ar project Ns = Ns Ar size Ns | Ns Sy none 1400The 1401.Sy projectobjquota 1402is similar to 1403.Sy projectquota 1404but it limits number of objects a project can consume. 1405Please refer to 1406.Sy userobjused 1407for more information about how objects are counted. 1408.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off 1409Controls whether this dataset can be modified. 1410The default value is 1411.Sy off . 1412The values 1413.Sy on 1414and 1415.Sy off 1416are equivalent to the 1417.Sy ro 1418and 1419.Sy rw 1420mount options. 1421.Pp 1422This property can also be referred to by its shortened column name, 1423.Sy rdonly . 1424.It Sy recordsize Ns = Ns Ar size 1425Specifies a suggested block size for files in the file system. 1426This property is designed solely for use with database workloads that access 1427files in fixed-size records. 1428ZFS automatically tunes block sizes according to internal algorithms optimized 1429for typical access patterns. 1430.Pp 1431For databases that create very large files but access them in small random 1432chunks, these algorithms may be suboptimal. 1433Specifying a 1434.Sy recordsize 1435greater than or equal to the record size of the database can result in 1436significant performance gains. 1437Use of this property for general purpose file systems is strongly discouraged, 1438and may adversely affect performance. 1439.Pp 1440The size specified must be a power of two greater than or equal to 1441.Ar 512 B 1442and less than or equal to 1443.Ar 128 KiB . 1444If the 1445.Sy large_blocks 1446feature is enabled on the pool, the size may be up to 1447.Ar 1 MiB . 1448See 1449.Xr zpool-features 7 1450for details on ZFS feature flags. 1451.Pp 1452Changing the file system's 1453.Sy recordsize 1454affects only files created afterward; existing files are unaffected. 1455.Pp 1456This property can also be referred to by its shortened column name, 1457.Sy recsize . 1458.It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most Ns | Ns Sy some Ns | Ns Sy none 1459Controls what types of metadata are stored redundantly. 1460ZFS stores an extra copy of metadata, so that if a single block is corrupted, 1461the amount of user data lost is limited. 1462This extra copy is in addition to any redundancy provided at the pool level 1463.Pq e.g. by mirroring or RAID-Z , 1464and is in addition to an extra copy specified by the 1465.Sy copies 1466property 1467.Pq up to a total of 3 copies . 1468For example if the pool is mirrored, 1469.Sy copies Ns = Ns 2 , 1470and 1471.Sy redundant_metadata Ns = Ns Sy most , 1472then ZFS stores 6 copies of most metadata, and 4 copies of data and some 1473metadata. 1474.Pp 1475When set to 1476.Sy all , 1477ZFS stores an extra copy of all metadata. 1478If a single on-disk block is corrupt, at worst a single block of user data 1479.Po which is 1480.Sy recordsize 1481bytes long 1482.Pc 1483can be lost. 1484.Pp 1485When set to 1486.Sy most , 1487ZFS stores an extra copy of most types of metadata. 1488This can improve performance of random writes, because less metadata must be 1489written. 1490In practice, at worst about 1000 blocks 1491.Po of 1492.Sy recordsize 1493bytes each 1494.Pc 1495of user data can be lost if a single on-disk block is corrupt. 1496The exact behavior of which metadata blocks are stored redundantly may change in 1497future releases. 1498.Pp 1499When set to 1500.Sy some , 1501ZFS stores an extra copy of only critical metadata. 1502This can improve file create performance since less metadata needs to be written. 1503If a single on-disk block is corrupt, at worst a single user file can be lost. 1504.Pp 1505When set to 1506.Sy none , 1507ZFS does not store any copies of metadata redundantly. 1508If a single on-disk block is corrupt, an entire dataset can be lost. 1509.Pp 1510The default value is 1511.Sy all . 1512.It Sy refquota Ns = Ns Ar size Ns | Ns Sy none 1513Limits the amount of space a dataset can consume. 1514This property enforces a hard limit on the amount of space used. 1515This hard limit does not include space used by descendents, including file 1516systems and snapshots. 1517.It Sy refreservation Ns = Ns Ar size Ns | Ns Sy none Ns | Ns Sy auto 1518The minimum amount of space guaranteed to a dataset, not including its 1519descendents. 1520When the amount of space used is below this value, the dataset is treated as if 1521it were taking up the amount of space specified by 1522.Sy refreservation . 1523The 1524.Sy refreservation 1525reservation is accounted for in the parent datasets' space used, and counts 1526against the parent datasets' quotas and reservations. 1527.Pp 1528If 1529.Sy refreservation 1530is set, a snapshot is only allowed if there is enough free pool space outside of 1531this reservation to accommodate the current number of 1532.Qq referenced 1533bytes in the dataset. 1534.Pp 1535If 1536.Sy refreservation 1537is set to 1538.Sy auto , 1539a volume is thick provisioned 1540.Po or 1541.Qq not sparse 1542.Pc . 1543.Sy refreservation Ns = Ns Sy auto 1544is only supported on volumes. 1545See 1546.Sy volsize 1547in the 1548.Sx Native Properties 1549section for more information about sparse volumes. 1550.Pp 1551This property can also be referred to by its shortened column name, 1552.Sy refreserv . 1553.It Sy relatime Ns = Ns Sy on Ns | Ns Sy off 1554Controls the manner in which the access time is updated when 1555.Sy atime Ns = Ns Sy on 1556is set. 1557Turning this property on causes the access time to be updated relative 1558to the modify or change time. 1559Access time is only updated if the previous 1560access time was earlier than the current modify or change time or if the 1561existing access time hasn't been updated within the past 24 hours. 1562The default value is 1563.Sy on . 1564The values 1565.Sy on 1566and 1567.Sy off 1568are equivalent to the 1569.Sy relatime 1570and 1571.Sy norelatime 1572mount options. 1573.It Sy reservation Ns = Ns Ar size Ns | Ns Sy none 1574The minimum amount of space guaranteed to a dataset and its descendants. 1575When the amount of space used is below this value, the dataset is treated as if 1576it were taking up the amount of space specified by its reservation. 1577Reservations are accounted for in the parent datasets' space used, and count 1578against the parent datasets' quotas and reservations. 1579.Pp 1580This property can also be referred to by its shortened column name, 1581.Sy reserv . 1582.It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata 1583Controls what is cached in the secondary cache 1584.Pq L2ARC . 1585If this property is set to 1586.Sy all , 1587then both user data and metadata is cached. 1588If this property is set to 1589.Sy none , 1590then neither user data nor metadata is cached. 1591If this property is set to 1592.Sy metadata , 1593then only metadata is cached. 1594The default value is 1595.Sy all . 1596.It Sy setuid Ns = Ns Sy on Ns | Ns Sy off 1597Controls whether the setuid bit is respected for the file system. 1598The default value is 1599.Sy on . 1600The values 1601.Sy on 1602and 1603.Sy off 1604are equivalent to the 1605.Sy suid 1606and 1607.Sy nosuid 1608mount options. 1609.It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts 1610Controls whether the file system is shared by using 1611.Sy Samba USERSHARES 1612and what options are to be used. 1613Otherwise, the file system is automatically shared and unshared with the 1614.Nm zfs Cm share 1615and 1616.Nm zfs Cm unshare 1617commands. 1618If the property is set to on, the 1619.Xr net 8 1620command is invoked to create a 1621.Sy USERSHARE . 1622.Pp 1623Because SMB shares requires a resource name, a unique resource name is 1624constructed from the dataset name. 1625The constructed name is a copy of the 1626dataset name except that the characters in the dataset name, which would be 1627invalid in the resource name, are replaced with underscore (_) characters. 1628Linux does not currently support additional options which might be available 1629on Solaris. 1630.Pp 1631If the 1632.Sy sharesmb 1633property is set to 1634.Sy off , 1635the file systems are unshared. 1636.Pp 1637The share is created with the ACL (Access Control List) "Everyone:F" ("F" 1638stands for "full permissions", i.e. read and write permissions) and no guest 1639access (which means Samba must be able to authenticate a real user \(em 1640.Xr passwd 5 Ns / Ns Xr shadow 5 Ns - , 1641LDAP- or 1642.Xr smbpasswd 5 Ns -based ) 1643by default. 1644This means that any additional access control 1645(disallow specific user specific access etc) must be done on the underlying file system. 1646.It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Ar opts 1647Controls whether the file system is shared via NFS, and what options are to be 1648used. 1649A file system with a 1650.Sy sharenfs 1651property of 1652.Sy off 1653is managed with the 1654.Xr exportfs 8 1655command and entries in the 1656.Pa /etc/exports 1657file. 1658Otherwise, the file system is automatically shared and unshared with the 1659.Nm zfs Cm share 1660and 1661.Nm zfs Cm unshare 1662commands. 1663If the property is set to 1664.Sy on , 1665the dataset is shared using the default options: 1666.Dl sec=sys,rw,crossmnt,no_subtree_check 1667.Pp 1668Please note that the options are comma-separated, unlike those found in 1669.Xr exports 5 . 1670This is done to negate the need for quoting, as well as to make parsing 1671with scripts easier. 1672.Pp 1673See 1674.Xr exports 5 1675for the meaning of the default options. 1676Otherwise, the 1677.Xr exportfs 8 1678command is invoked with options equivalent to the contents of this property. 1679.Pp 1680When the 1681.Sy sharenfs 1682property is changed for a dataset, the dataset and any children inheriting the 1683property are re-shared with the new options, only if the property was previously 1684.Sy off , 1685or if they were shared before the property was changed. 1686If the new property is 1687.Sy off , 1688the file systems are unshared. 1689.It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput 1690Provide a hint to ZFS about handling of synchronous requests in this dataset. 1691If 1692.Sy logbias 1693is set to 1694.Sy latency 1695.Pq the default , 1696ZFS will use pool log devices 1697.Pq if configured 1698to handle the requests at low latency. 1699If 1700.Sy logbias 1701is set to 1702.Sy throughput , 1703ZFS will not use configured pool log devices. 1704ZFS will instead optimize synchronous operations for global pool throughput and 1705efficient use of resources. 1706.It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible 1707Controls whether the volume snapshot devices under 1708.Pa /dev/zvol/ Ns Aq Ar pool 1709are hidden or visible. 1710The default value is 1711.Sy hidden . 1712.It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible 1713Controls whether the 1714.Pa .zfs 1715directory is hidden or visible in the root of the file system as discussed in 1716the 1717.Sx Snapshots 1718section of 1719.Xr zfsconcepts 7 . 1720The default value is 1721.Sy hidden . 1722.It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled 1723Controls the behavior of synchronous requests 1724.Pq e.g. fsync, O_DSYNC . 1725.Sy standard 1726is the POSIX-specified behavior of ensuring all synchronous requests 1727are written to stable storage and all devices are flushed to ensure 1728data is not cached by device controllers 1729.Pq this is the default . 1730.Sy always 1731causes every file system transaction to be written and flushed before its 1732system call returns. 1733This has a large performance penalty. 1734.Sy disabled 1735disables synchronous requests. 1736File system transactions are only committed to stable storage periodically. 1737This option will give the highest performance. 1738However, it is very dangerous as ZFS would be ignoring the synchronous 1739transaction demands of applications such as databases or NFS. 1740Administrators should only use this option when the risks are understood. 1741.It Sy version Ns = Ns Ar N Ns | Ns Sy current 1742The on-disk version of this file system, which is independent of the pool 1743version. 1744This property can only be set to later supported versions. 1745See the 1746.Nm zfs Cm upgrade 1747command. 1748.It Sy volsize Ns = Ns Ar size 1749For volumes, specifies the logical size of the volume. 1750By default, creating a volume establishes a reservation of equal size. 1751For storage pools with a version number of 9 or higher, a 1752.Sy refreservation 1753is set instead. 1754Any changes to 1755.Sy volsize 1756are reflected in an equivalent change to the reservation 1757.Pq or Sy refreservation . 1758The 1759.Sy volsize 1760can only be set to a multiple of 1761.Sy volblocksize , 1762and cannot be zero. 1763.Pp 1764The reservation is kept equal to the volume's logical size to prevent unexpected 1765behavior for consumers. 1766Without the reservation, the volume could run out of space, resulting in 1767undefined behavior or data corruption, depending on how the volume is used. 1768These effects can also occur when the volume size is changed while it is in use 1769.Pq particularly when shrinking the size . 1770Extreme care should be used when adjusting the volume size. 1771.Pp 1772Though not recommended, a 1773.Qq sparse volume 1774.Po also known as 1775.Qq thin provisioned 1776.Pc 1777can be created by specifying the 1778.Fl s 1779option to the 1780.Nm zfs Cm create Fl V 1781command, or by changing the value of the 1782.Sy refreservation 1783property 1784.Po or 1785.Sy reservation 1786property on pool version 8 or earlier 1787.Pc 1788after the volume has been created. 1789A 1790.Qq sparse volume 1791is a volume where the value of 1792.Sy refreservation 1793is less than the size of the volume plus the space required to store its 1794metadata. 1795Consequently, writes to a sparse volume can fail with 1796.Er ENOSPC 1797when the pool is low on space. 1798For a sparse volume, changes to 1799.Sy volsize 1800are not reflected in the 1801.Sy refreservation . 1802A volume that is not sparse is said to be 1803.Qq thick provisioned . 1804A sparse volume can become thick provisioned by setting 1805.Sy refreservation 1806to 1807.Sy auto . 1808.It Sy volmode Ns = Ns Sy default Ns | Ns Sy full Ns | Ns Sy geom Ns | Ns Sy dev Ns | Ns Sy none 1809This property specifies how volumes should be exposed to the OS. 1810Setting it to 1811.Sy full 1812exposes volumes as fully fledged block devices, providing maximal 1813functionality. 1814The value 1815.Sy geom 1816is just an alias for 1817.Sy full 1818and is kept for compatibility. 1819Setting it to 1820.Sy dev 1821hides its partitions. 1822Volumes with property set to 1823.Sy none 1824are not exposed outside ZFS, but can be snapshotted, cloned, replicated, etc, 1825that can be suitable for backup purposes. 1826Value 1827.Sy default 1828means that volumes exposition is controlled by system-wide tunable 1829.Sy zvol_volmode , 1830where 1831.Sy full , 1832.Sy dev 1833and 1834.Sy none 1835are encoded as 1, 2 and 3 respectively. 1836The default value is 1837.Sy full . 1838.It Sy vscan Ns = Ns Sy on Ns | Ns Sy off 1839Controls whether regular files should be scanned for viruses when a file is 1840opened and closed. 1841In addition to enabling this property, the virus scan service must also be 1842enabled for virus scanning to occur. 1843The default value is 1844.Sy off . 1845This property is not used by OpenZFS. 1846.It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa 1847Controls whether extended attributes are enabled for this file system. 1848Two styles of extended attributes are supported: either directory-based 1849or system-attribute-based. 1850.Pp 1851The default value of 1852.Sy on 1853enables directory-based extended attributes. 1854This style of extended attribute imposes no practical limit 1855on either the size or number of attributes which can be set on a file. 1856Although under Linux the 1857.Xr getxattr 2 1858and 1859.Xr setxattr 2 1860system calls limit the maximum size to 1861.Sy 64K . 1862This is the most compatible 1863style of extended attribute and is supported by all ZFS implementations. 1864.Pp 1865System-attribute-based xattrs can be enabled by setting the value to 1866.Sy sa . 1867The key advantage of this type of xattr is improved performance. 1868Storing extended attributes as system attributes 1869significantly decreases the amount of disk I/O required. 1870Up to 1871.Sy 64K 1872of data may be stored per-file in the space reserved for system attributes. 1873If there is not enough space available for an extended attribute 1874then it will be automatically written as a directory-based xattr. 1875System-attribute-based extended attributes are not accessible 1876on platforms which do not support the 1877.Sy xattr Ns = Ns Sy sa 1878feature. 1879OpenZFS supports 1880.Sy xattr Ns = Ns Sy sa 1881on both 1882.Fx 1883and Linux. 1884.Pp 1885The use of system-attribute-based xattrs is strongly encouraged for users of 1886SELinux or POSIX ACLs. 1887Both of these features heavily rely on extended 1888attributes and benefit significantly from the reduced access time. 1889.Pp 1890The values 1891.Sy on 1892and 1893.Sy off 1894are equivalent to the 1895.Sy xattr 1896and 1897.Sy noxattr 1898mount options. 1899.It Sy jailed Ns = Ns Sy off Ns | Ns Sy on 1900Controls whether the dataset is managed from a jail. 1901See 1902.Xr zfs-jail 8 1903for more information. 1904Jails are a 1905.Fx 1906feature and are not relevant on other platforms. 1907The default value is 1908.Sy off . 1909.It Sy zoned Ns = Ns Sy on Ns | Ns Sy off 1910Controls whether the dataset is managed from a non-global zone or namespace. 1911The default value is 1912.Sy off . 1913.El 1914.Pp 1915The following three properties cannot be changed after the file system is 1916created, and therefore, should be set when the file system is created. 1917If the properties are not set with the 1918.Nm zfs Cm create 1919or 1920.Nm zpool Cm create 1921commands, these properties are inherited from the parent dataset. 1922If the parent dataset lacks these properties due to having been created prior to 1923these features being supported, the new file system will have the default values 1924for these properties. 1925.Bl -tag -width "" 1926.It Xo 1927.Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns 1928.Sy insensitive Ns | Ns Sy mixed 1929.Xc 1930Indicates whether the file name matching algorithm used by the file system 1931should be case-sensitive, case-insensitive, or allow a combination of both 1932styles of matching. 1933The default value for the 1934.Sy casesensitivity 1935property is 1936.Sy sensitive . 1937Traditionally, 1938.Ux 1939and POSIX file systems have case-sensitive file names. 1940.Pp 1941The 1942.Sy mixed 1943value for the 1944.Sy casesensitivity 1945property indicates that the file system can support requests for both 1946case-sensitive and case-insensitive matching behavior. 1947Currently, case-insensitive matching behavior on a file system that supports 1948mixed behavior is limited to the SMB server product. 1949For more information about the 1950.Sy mixed 1951value behavior, see the "ZFS Administration Guide". 1952.It Xo 1953.Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns 1954.Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD 1955.Xc 1956Indicates whether the file system should perform a 1957.Sy unicode 1958normalization of file names whenever two file names are compared, and which 1959normalization algorithm should be used. 1960File names are always stored unmodified, names are normalized as part of any 1961comparison process. 1962If this property is set to a legal value other than 1963.Sy none , 1964and the 1965.Sy utf8only 1966property was left unspecified, the 1967.Sy utf8only 1968property is automatically set to 1969.Sy on . 1970The default value of the 1971.Sy normalization 1972property is 1973.Sy none . 1974This property cannot be changed after the file system is created. 1975.It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off 1976Indicates whether the file system should reject file names that include 1977characters that are not present in the 1978.Sy UTF-8 1979character code set. 1980If this property is explicitly set to 1981.Sy off , 1982the normalization property must either not be explicitly set or be set to 1983.Sy none . 1984The default value for the 1985.Sy utf8only 1986property is 1987.Sy off . 1988This property cannot be changed after the file system is created. 1989.El 1990.Pp 1991The 1992.Sy casesensitivity , 1993.Sy normalization , 1994and 1995.Sy utf8only 1996properties are also new permissions that can be assigned to non-privileged users 1997by using the ZFS delegated administration feature. 1998. 1999.Ss Temporary Mount Point Properties 2000When a file system is mounted, either through 2001.Xr mount 8 2002for legacy mounts or the 2003.Nm zfs Cm mount 2004command for normal file systems, its mount options are set according to its 2005properties. 2006The correlation between properties and mount options is as follows: 2007.Bl -tag -compact -offset Ds -width "rootcontext=" 2008.It Sy atime 2009atime/noatime 2010.It Sy canmount 2011auto/noauto 2012.It Sy devices 2013dev/nodev 2014.It Sy exec 2015exec/noexec 2016.It Sy readonly 2017ro/rw 2018.It Sy relatime 2019relatime/norelatime 2020.It Sy setuid 2021suid/nosuid 2022.It Sy xattr 2023xattr/noxattr 2024.It Sy nbmand 2025mand/nomand 2026.It Sy context Ns = 2027context= 2028.It Sy fscontext Ns = 2029fscontext= 2030.It Sy defcontext Ns = 2031defcontext= 2032.It Sy rootcontext Ns = 2033rootcontext= 2034.El 2035.Pp 2036In addition, these options can be set on a per-mount basis using the 2037.Fl o 2038option, without affecting the property that is stored on disk. 2039The values specified on the command line override the values stored in the 2040dataset. 2041The 2042.Sy nosuid 2043option is an alias for 2044.Sy nodevices , Ns Sy nosetuid . 2045These properties are reported as 2046.Qq temporary 2047by the 2048.Nm zfs Cm get 2049command. 2050If the properties are changed while the dataset is mounted, the new setting 2051overrides any temporary settings. 2052. 2053.Ss User Properties 2054In addition to the standard native properties, ZFS supports arbitrary user 2055properties. 2056User properties have no effect on ZFS behavior, but applications or 2057administrators can use them to annotate datasets 2058.Pq file systems, volumes, and snapshots . 2059.Pp 2060User property names must contain a colon 2061.Pq Qq Sy \&: 2062character to distinguish them from native properties. 2063They may contain lowercase letters, numbers, and the following punctuation 2064characters: colon 2065.Pq Qq Sy \&: , 2066dash 2067.Pq Qq Sy - , 2068period 2069.Pq Qq Sy \&. , 2070and underscore 2071.Pq Qq Sy _ . 2072The expected convention is that the property name is divided into two portions 2073such as 2074.Ar module : Ns Ar property , 2075but this namespace is not enforced by ZFS. 2076User property names can be at most 256 characters, and cannot begin with a dash 2077.Pq Qq Sy - . 2078.Pp 2079When making programmatic use of user properties, it is strongly suggested to use 2080a reversed DNS domain name for the 2081.Ar module 2082component of property names to reduce the chance that two 2083independently-developed packages use the same property name for different 2084purposes. 2085.Pp 2086The values of user properties are arbitrary strings, are always inherited, and 2087are never validated. 2088All of the commands that operate on properties 2089.Po Nm zfs Cm list , 2090.Nm zfs Cm get , 2091.Nm zfs Cm set , 2092and so forth 2093.Pc 2094can be used to manipulate both native properties and user properties. 2095Use the 2096.Nm zfs Cm inherit 2097command to clear a user property. 2098If the property is not defined in any parent dataset, it is removed entirely. 2099Property values are limited to 8192 bytes. 2100