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