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

zfsconcepts.7 (8601B)


  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) 2013 by Saso Kiselkov. All rights reserved.
  25. .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
  26. .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
  27. .\" Copyright (c) 2014 Integros [integros.com]
  28. .\" Copyright 2019 Richard Laager. All rights reserved.
  29. .\" Copyright 2018 Nexenta Systems, Inc.
  30. .\" Copyright 2019 Joyent, Inc.
  31. .\" Copyright 2023 Klara, Inc.
  32. .\"
  33. .Dd October 6, 2023
  34. .Dt ZFSCONCEPTS 7
  35. .Os
  36. .
  37. .Sh NAME
  38. .Nm zfsconcepts
  39. .Nd overview of ZFS concepts
  40. .
  41. .Sh DESCRIPTION
  42. .Ss ZFS File System Hierarchy
  43. A ZFS storage pool is a logical collection of devices that provide space for
  44. datasets.
  45. A storage pool is also the root of the ZFS file system hierarchy.
  46. .Pp
  47. The root of the pool can be accessed as a file system, such as mounting and
  48. unmounting, taking snapshots, and setting properties.
  49. The physical storage characteristics, however, are managed by the
  50. .Xr zpool 8
  51. command.
  52. .Pp
  53. See
  54. .Xr zpool 8
  55. for more information on creating and administering pools.
  56. .Ss Snapshots
  57. A snapshot is a read-only copy of a file system or volume.
  58. Snapshots can be created extremely quickly, and initially consume no additional
  59. space within the pool.
  60. As data within the active dataset changes, the snapshot consumes more data than
  61. would otherwise be shared with the active dataset.
  62. .Pp
  63. Snapshots can have arbitrary names.
  64. Snapshots of volumes can be cloned or rolled back, visibility is determined
  65. by the
  66. .Sy snapdev
  67. property of the parent volume.
  68. .Pp
  69. File system snapshots can be accessed under the
  70. .Pa .zfs/snapshot
  71. directory in the root of the file system.
  72. Snapshots are automatically mounted on demand and may be unmounted at regular
  73. intervals.
  74. The availability and visibility of the
  75. .Pa .zfs
  76. directory can be controlled by the
  77. .Sy snapdir
  78. property.
  79. .Ss Bookmarks
  80. A bookmark is like a snapshot, a read-only copy of a file system or volume.
  81. Bookmarks can be created extremely quickly, compared to snapshots, and they
  82. consume no additional space within the pool.
  83. Bookmarks can also have arbitrary names, much like snapshots.
  84. .Pp
  85. Unlike snapshots, bookmarks can not be accessed through the filesystem in any
  86. way.
  87. From a storage standpoint a bookmark just provides a way to reference
  88. when a snapshot was created as a distinct object.
  89. Bookmarks are initially tied to a snapshot, not the filesystem or volume,
  90. and they will survive if the snapshot itself is destroyed.
  91. Since they are very light weight there's little incentive to destroy them.
  92. .Ss Clones
  93. A clone is a writable volume or file system whose initial contents are the same
  94. as another dataset.
  95. As with snapshots, creating a clone is nearly instantaneous, and initially
  96. consumes no additional space.
  97. .Pp
  98. Clones can only be created from a snapshot.
  99. When a snapshot is cloned, it creates an implicit dependency between the parent
  100. and child.
  101. Even though the clone is created somewhere else in the dataset hierarchy, the
  102. original snapshot cannot be destroyed as long as a clone exists.
  103. The
  104. .Sy origin
  105. property exposes this dependency, and the
  106. .Cm destroy
  107. command lists any such dependencies, if they exist.
  108. .Pp
  109. The clone parent-child dependency relationship can be reversed by using the
  110. .Cm promote
  111. subcommand.
  112. This causes the
  113. .Qq origin
  114. file system to become a clone of the specified file system, which makes it
  115. possible to destroy the file system that the clone was created from.
  116. .Ss "Mount Points"
  117. Creating a ZFS file system is a simple operation, so the number of file systems
  118. per system is likely to be numerous.
  119. To cope with this, ZFS automatically manages mounting and unmounting file
  120. systems without the need to edit the
  121. .Pa /etc/fstab
  122. file.
  123. All automatically managed file systems are mounted by ZFS at boot time.
  124. .Pp
  125. By default, file systems are mounted under
  126. .Pa /path ,
  127. where
  128. .Ar path
  129. is the name of the file system in the ZFS namespace.
  130. Directories are created and destroyed as needed.
  131. .Pp
  132. A file system can also have a mount point set in the
  133. .Sy mountpoint
  134. property.
  135. This directory is created as needed, and ZFS automatically mounts the file
  136. system when the
  137. .Nm zfs Cm mount Fl a
  138. command is invoked
  139. .Po without editing
  140. .Pa /etc/fstab
  141. .Pc .
  142. The
  143. .Sy mountpoint
  144. property can be inherited, so if
  145. .Em pool/home
  146. has a mount point of
  147. .Pa /export/stuff ,
  148. then
  149. .Em pool/home/user
  150. automatically inherits a mount point of
  151. .Pa /export/stuff/user .
  152. .Pp
  153. A file system
  154. .Sy mountpoint
  155. property of
  156. .Sy none
  157. prevents the file system from being mounted.
  158. .Pp
  159. If needed, ZFS file systems can also be managed with traditional tools
  160. .Po
  161. .Nm mount ,
  162. .Nm umount ,
  163. .Pa /etc/fstab
  164. .Pc .
  165. If a file system's mount point is set to
  166. .Sy legacy ,
  167. ZFS makes no attempt to manage the file system, and the administrator is
  168. responsible for mounting and unmounting the file system.
  169. Because pools must
  170. be imported before a legacy mount can succeed, administrators should ensure
  171. that legacy mounts are only attempted after the zpool import process
  172. finishes at boot time.
  173. For example, on machines using systemd, the mount option
  174. .Pp
  175. .Nm x-systemd.requires=zfs-import.target
  176. .Pp
  177. will ensure that the zfs-import completes before systemd attempts mounting
  178. the filesystem.
  179. See
  180. .Xr systemd.mount 5
  181. for details.
  182. .Ss Deduplication
  183. Deduplication is the process for removing redundant data at the block level,
  184. reducing the total amount of data stored.
  185. If a file system has the
  186. .Sy dedup
  187. property enabled, duplicate data blocks are removed synchronously.
  188. The result
  189. is that only unique data is stored and common components are shared among files.
  190. .Pp
  191. Deduplicating data is a very resource-intensive operation.
  192. It is generally recommended that you have at least 1.25 GiB of RAM
  193. per 1 TiB of storage when you enable deduplication.
  194. Calculating the exact requirement depends heavily
  195. on the type of data stored in the pool.
  196. .Pp
  197. Enabling deduplication on an improperly-designed system can result in
  198. performance issues (slow I/O and administrative operations).
  199. It can potentially lead to problems importing a pool due to memory exhaustion.
  200. Deduplication can consume significant processing power (CPU) and memory as well
  201. as generate additional disk I/O.
  202. .Pp
  203. Before creating a pool with deduplication enabled, ensure that you have planned
  204. your hardware requirements appropriately and implemented appropriate recovery
  205. practices, such as regular backups.
  206. Consider using the
  207. .Sy compression
  208. property as a less resource-intensive alternative.
  209. .Ss Block cloning
  210. Block cloning is a facility that allows a file (or parts of a file) to be
  211. .Qq cloned ,
  212. that is, a shallow copy made where the existing data blocks are referenced
  213. rather than copied.
  214. Later modifications to the data will cause a copy of the data block to be taken
  215. and that copy modified.
  216. This facility is used to implement
  217. .Qq reflinks
  218. or
  219. .Qq file-level copy-on-write .
  220. .Pp
  221. Cloned blocks are tracked in a special on-disk structure called the Block
  222. Reference Table
  223. .Po BRT
  224. .Pc .
  225. Unlike deduplication, this table has minimal overhead, so can be enabled at all
  226. times.
  227. .Pp
  228. Also unlike deduplication, cloning must be requested by a user program.
  229. Many common file copying programs, including newer versions of
  230. .Nm /bin/cp ,
  231. will try to create clones automatically.
  232. Look for
  233. .Qq clone ,
  234. .Qq dedupe
  235. or
  236. .Qq reflink
  237. in the documentation for more information.
  238. .Pp
  239. There are some limitations to block cloning.
  240. Only whole blocks can be cloned, and blocks can not be cloned if they are not
  241. yet written to disk, or if they are encrypted, or the source and destination
  242. .Sy recordsize
  243. properties differ.
  244. The OS may add additional restrictions;
  245. for example, most versions of Linux will not allow clones across datasets.