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