| blob | 1be3d961c3d7f2b5f12121024f3eed28278d3736 |
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 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.