logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zfsprops.7 (68126B)


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