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