man/man8/zfsconcepts.8

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