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