# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2026-08-16 15:11-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Yaml Front Matter Hash Value: description #: documentation/content/en/books/handbook/zfs/_index.adoc:1 #, no-wrap msgid "ZFS is an advanced file system designed to solve major problems found in previous storage subsystem software" msgstr "" #. type: Yaml Front Matter Hash Value: part #: documentation/content/en/books/handbook/zfs/_index.adoc:1 #, no-wrap msgid "Part III. System Administration" msgstr "" #. type: Yaml Front Matter Hash Value: title #: documentation/content/en/books/handbook/zfs/_index.adoc:1 #, no-wrap msgid "Chapter 23. The Z File System (ZFS)" msgstr "" #. type: Title = #: documentation/content/en/books/handbook/zfs/_index.adoc:15 #, no-wrap msgid "The Z File System (ZFS)" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:52 msgid "" "ZFS is an advanced file system designed to solve major problems found in " "previous storage subsystem software." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:54 msgid "" "Originally developed at Sun Microsystems(TM), ongoing open source ZFS " "development has moved to the https://openzfs.org[OpenZFS Project]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:56 msgid "ZFS has three major design goals:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:58 msgid "" "Data integrity: All data includes a crossref:zfs[zfs-term-checksum,checksum] " "of the data. ZFS calculates checksums and writes them along with the data. " "When reading that data later, ZFS recalculates the checksums. If the " "checksums do not match, meaning detecting one or more data errors, ZFS will " "attempt to automatically correct errors when ditto-, mirror-, or parity-" "blocks are available." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:59 msgid "" "Pooled storage: adding physical storage devices to a pool, and allocating " "storage space from that shared pool. Space is available to all file systems " "and volumes, and increases by adding new storage devices to the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:62 msgid "" "Performance: caching mechanisms provide increased performance. " "crossref:zfs[zfs-term-arc,ARC] is an advanced memory-based read cache. ZFS " "provides a second level disk-based read cache with crossref:zfs[zfs-term-" "l2arc,L2ARC], and a disk-based synchronous write cache named " "crossref:zfs[zfs-term-zil,ZIL]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:64 msgid "" "A complete list of features and terminology is in crossref:zfs[zfs-term, ZFS " "Features and Terminology]." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:66 #, no-wrap msgid "What Makes ZFS Different" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:80 msgid "" "More than a file system, ZFS is fundamentally different from traditional " "file systems. Combining the traditionally separate roles of volume manager " "and file system provides ZFS with unique advantages. The file system is now " "aware of the underlying structure of the disks. Traditional file systems " "could exist on a single disk at a time. If there were two disks then " "creating two separate file systems was necessary. A traditional hardware " "RAID configuration avoided this problem by presenting the operating system " "with a single logical disk made up of the space provided by physical disks " "on top of which the operating system placed a file system. Even with " "software RAID solutions like those provided by GEOM, the UFS file system " "living on top of the RAID believes it is dealing with a single device. ZFS' " "combination of the volume manager and the file system solves this and allows " "the creation of file systems that all share a pool of available storage. " "One big advantage of ZFS' awareness of the physical disk layout is that " "existing file systems grow automatically when adding extra disks to the " "pool. This new space then becomes available to the file systems. ZFS can " "also apply different properties to each file system. This makes it useful " "to create separate file systems and datasets instead of a single monolithic " "file system." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:82 #, no-wrap msgid "Quick Start Guide" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:86 msgid "" "The FreeBSD installer can install the system directly onto a ZFS pool, a " "configuration known as Root-on-ZFS; see crossref:bsdinstall[bsdinstall-part-" "zfs,Guided Root-on-ZFS]. This section shows how to create and manage " "additional ZFS pools and datasets on a running system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:89 msgid "" "FreeBSD can mount ZFS pools and datasets during system initialization. To " "enable it, run:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:93 #, no-wrap msgid "# sysrc zfs_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:97 msgid "" "This adds `zfs_enable=\"YES\"` to [.filename]#/etc/rc.conf#. Running " "`service zfs enable` makes the same change." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:99 msgid "Then start the service:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:103 #, no-wrap msgid "# service zfs start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:107 msgid "" "The examples in this section assume three SATA disks with the device names " "[.filename]#ada0#, [.filename]#ada1#, and [.filename]#ada2#. Users of SCSI/" "SAS hardware should instead use [.filename]#da# device names, and users of " "NVMe storage [.filename]#nda# device names." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:109 #, no-wrap msgid "Single Disk Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:113 msgid "" "Create a GPT partition on an empty disk first. Then add a partition of type " "`freebsd-zfs` from which a single, non-redundant pool is created:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:119 #, no-wrap msgid "" "# gpart create -s gpt ada1\n" "# gpart add -t freebsd-zfs ada1\n" "# zpool create example /dev/ada1p1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:122 msgid "To view the new pool, review the output of `df`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:128 #, no-wrap msgid "" "# df /example\n" "Filesystem 1K-blocks Used Avail Capacity Mounted on\n" "example 17547136 0 17547136 0% /example\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:132 msgid "" "This output shows creating and mounting of the `example` pool, and that it " "is now accessible as a file system. Create files for users to browse:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:143 #, no-wrap msgid "" "# cd /example\n" "# ls\n" "# touch testfile\n" "# ls -al\n" "total 4\n" "drwxr-xr-x 2 root wheel 3 Aug 29 23:15 .\n" "drwxr-xr-x 21 root wheel 512 Aug 29 23:12 ..\n" "-rw-r--r-- 1 root wheel 0 Aug 29 23:15 testfile\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:147 msgid "" "This pool is not using any advanced ZFS features and properties yet. To " "create a dataset on this pool with compression enabled:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:152 #, no-wrap msgid "" "# zfs create example/compressed\n" "# zfs set compression=gzip example/compressed\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:156 msgid "" "The `example/compressed` dataset is now a ZFS compressed file system. Try " "copying some large files to [.filename]#/example/compressed#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:158 msgid "Disable compression with:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:162 #, no-wrap msgid "# zfs set compression=off example/compressed\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:165 msgid "To unmount a file system, use `zfs umount` and then verify with `df`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:172 #, no-wrap msgid "" "# zfs umount example/compressed\n" "# df\n" "Filesystem 1K-blocks Used Avail Capacity Mounted on\n" "example 17547008 0 17547008 0% /example\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:175 msgid "" "To re-mount the file system to make it accessible again, use `zfs mount` and " "verify with `df`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:183 #, no-wrap msgid "" "# zfs mount example/compressed\n" "# df\n" "Filesystem 1K-blocks Used Avail Capacity Mounted on\n" "example 17547008 0 17547008 0% /example\n" "example/compressed 17547008 0 17547008 0% /example/compressed\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:186 msgid "Running `mount` shows the pool and file systems:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:195 #, no-wrap msgid "" "# mount\n" "/dev/ada0p1 on / (ufs, local)\n" "devfs on /dev (devfs, local)\n" "/dev/ada0p2 on /usr (ufs, local, soft-updates)\n" "example on /example (zfs, local)\n" "example/compressed on /example/compressed (zfs, local)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:201 msgid "" "Use ZFS datasets like any file system after creation. Set other available " "features on a per-dataset basis when needed. The example below creates a " "new file system called `data`. It assumes the file system contains " "important files and configures it to store two copies of each data block." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:206 #, no-wrap msgid "" "# zfs create example/data\n" "# zfs set copies=2 example/data\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:209 msgid "Use `df` to see the data and space usage:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:220 #, no-wrap msgid "" "# df\n" "Filesystem 1K-blocks Used Avail Capacity Mounted on\n" "/dev/ada0p1 2026030 235234 1628714 13% /\n" "devfs 1 1 0 100% /dev\n" "/dev/ada0p2 54098308 1032864 48737580 2% /usr\n" "example 17547008 0 17547008 0% /example\n" "example/compressed 17547008 0 17547008 0% /example/compressed\n" "example/data 17547008 0 17547008 0% /example/data\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:225 msgid "" "Notice that all file systems in the pool have the same available space. " "Using `df` in these examples shows that the file systems use the space they " "need and all draw from the same pool. ZFS gets rid of concepts such as " "volumes and partitions, and allows several file systems to share the same " "pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:227 msgid "To destroy the file systems and then the pool that is no longer needed:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:233 #, no-wrap msgid "" "# zfs destroy example/compressed\n" "# zfs destroy example/data\n" "# zpool destroy example\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:236 #, no-wrap msgid "RAID-Z" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:242 msgid "" "Disks fail. One way to avoid data loss from disk failure is to use RAID. " "ZFS supports this feature in its pool design. RAID-Z pools require three or " "more disks but provide more usable space than mirrored pools." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:245 msgid "" "This example creates a RAID-Z pool. First the GPT partitions are created on " "each disk, then specify these GPT partitions to add to the pool using the " "`raidz` keyword:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:255 #, no-wrap msgid "" "# gpart create -s gpt ada0\n" "# gpart add -t freebsd-zfs ada0\n" "# gpart create -s gpt ada1\n" "# gpart add -t freebsd-zfs ada1\n" "# gpart create -s gpt ada2\n" "# gpart add -t freebsd-zfs ada2\n" "# zpool create storage raidz ada0p1 ada1p1 ada2p1\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:263 msgid "" "Keeping the number of devices used in a RAID-Z configuration between three " "and nine is recommended. For environments requiring a single pool " "consisting of 10 disks or more, consider breaking it up into smaller RAID-Z " "groups. If two disks are available, ZFS mirroring provides redundancy if " "required. Refer to man:zpool[8] for more details." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:267 msgid "" "The previous example created the `storage` zpool. This example makes a new " "file system called `home` in that pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:271 #, no-wrap msgid "# zfs create storage/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:274 msgid "Enable compression and store an extra copy of directories and files:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:279 #, no-wrap msgid "" "# zfs set copies=2 storage/home\n" "# zfs set compression=gzip storage/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:282 msgid "" "To make this the new home directory for users, copy the user data to this " "directory and create the appropriate symbolic links:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:289 #, no-wrap msgid "" "# cp -rp /home/* /storage/home\n" "# rm -rf /home /usr/home\n" "# ln -s /storage/home /home\n" "# ln -s /storage/home /usr/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:293 msgid "" "User data is now stored on the freshly-created [.filename]#/storage/home#. " "Test by adding a new user and logging in as that user." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:295 msgid "Create a file system snapshot to roll back to later:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:299 #, no-wrap msgid "# zfs snapshot storage/home@2026-07-11\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:302 msgid "ZFS creates snapshots of a dataset, not a single directory or file." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:305 msgid "" "The `@` character is a delimiter between the file system or volume name and " "the snapshot name. Before deleting an important directory, back up the file " "system, then roll back to an earlier snapshot in which the directory still " "exists:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:309 #, no-wrap msgid "# zfs rollback storage/home@2026-07-11\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:313 msgid "" "To list all available snapshots, run `ls` in the file system's " "[.filename]#.zfs/snapshot# directory. For example, to see the snapshot " "taken:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:317 #, no-wrap msgid "# ls /storage/home/.zfs/snapshot\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:322 msgid "" "Write a script to take regular snapshots of user data. Over time, snapshots " "can use up a lot of disk space. Remove the previous snapshot using the " "command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:326 #, no-wrap msgid "# zfs destroy storage/home@2026-07-11\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:330 msgid "" "After testing, make [.filename]#/storage/home# the real [.filename]#/home# " "with this command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:334 #, no-wrap msgid "# zfs set mountpoint=/home storage/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:337 msgid "" "Run `df` and `mount` to confirm that the system now treats the file system " "as the real [.filename]#/home#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:353 #, no-wrap msgid "" "# mount\n" "/dev/ada0p1 on / (ufs, local)\n" "devfs on /dev (devfs, local)\n" "/dev/ada0p2 on /usr (ufs, local, soft-updates)\n" "storage on /storage (zfs, local)\n" "storage/home on /home (zfs, local)\n" "# df\n" "Filesystem 1K-blocks Used Avail Capacity Mounted on\n" "/dev/ada0p1 2026030 235240 1628708 13% /\n" "devfs 1 1 0 100% /dev\n" "/dev/ada0p2 54098308 1032826 48737618 2% /usr\n" "storage 26320512 0 26320512 0% /storage\n" "storage/home 26320512 0 26320512 0% /home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:357 msgid "" "This completes the RAID-Z configuration. Add daily status updates about the " "created file systems to the nightly man:periodic[8] runs by adding this line " "to [.filename]#/etc/periodic.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:361 #, no-wrap msgid "daily_status_zfs_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:364 msgid "" "man:periodic[8] can also run scheduled scrubs of the pool; see " "crossref:zfs[zfs-zpool-scrub,Scrubbing a Pool]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:366 #, no-wrap msgid "Recovering RAID-Z" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:370 msgid "" "Every software RAID has a method of monitoring its `state`. View the status " "of RAID-Z devices using:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:374 #, no-wrap msgid "# zpool status -x\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:377 msgid "" "If all pools are crossref:zfs[zfs-term-online,Online] and everything is " "normal, the message shows:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:381 #, no-wrap msgid "all pools are healthy\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:385 msgid "" "If there is a problem, perhaps a disk being in the crossref:zfs[zfs-term-" "offline,Offline] state, the pool state will look like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:397 #, no-wrap msgid "" " pool: storage\n" " state: DEGRADED\n" "status: One or more devices has been taken offline by the administrator.\n" " Sufficient replicas exist for the pool to continue functioning in a\n" " degraded state.\n" "action: Online the device using 'zpool online' or replace the device with\n" " 'zpool replace'.\n" " scan: none requested\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:404 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " storage DEGRADED 0 0 0\n" " raidz1-0 DEGRADED 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 OFFLINE 0 0 0\n" " ada2p1 ONLINE 0 0 0\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:406 #: documentation/content/en/books/handbook/zfs/_index.adoc:442 #: documentation/content/en/books/handbook/zfs/_index.adoc:488 #: documentation/content/en/books/handbook/zfs/_index.adoc:533 #: documentation/content/en/books/handbook/zfs/_index.adoc:555 #: documentation/content/en/books/handbook/zfs/_index.adoc:586 #: documentation/content/en/books/handbook/zfs/_index.adoc:703 #: documentation/content/en/books/handbook/zfs/_index.adoc:759 #: documentation/content/en/books/handbook/zfs/_index.adoc:796 #: documentation/content/en/books/handbook/zfs/_index.adoc:833 #: documentation/content/en/books/handbook/zfs/_index.adoc:882 #: documentation/content/en/books/handbook/zfs/_index.adoc:931 #: documentation/content/en/books/handbook/zfs/_index.adoc:1047 #: documentation/content/en/books/handbook/zfs/_index.adoc:1137 #: documentation/content/en/books/handbook/zfs/_index.adoc:1215 #: documentation/content/en/books/handbook/zfs/_index.adoc:1241 #: documentation/content/en/books/handbook/zfs/_index.adoc:1270 #: documentation/content/en/books/handbook/zfs/_index.adoc:1343 #: documentation/content/en/books/handbook/zfs/_index.adoc:1457 #: documentation/content/en/books/handbook/zfs/_index.adoc:1501 #: documentation/content/en/books/handbook/zfs/_index.adoc:1526 #: documentation/content/en/books/handbook/zfs/_index.adoc:1547 #: documentation/content/en/books/handbook/zfs/_index.adoc:1583 #: documentation/content/en/books/handbook/zfs/_index.adoc:1793 #, no-wrap msgid "errors: No known data errors\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:409 msgid "" "\"OFFLINE\" shows the administrator took [.filename]#ada1p1# offline using:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:413 #, no-wrap msgid "# zpool offline storage ada1p1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:418 msgid "" "Power down the computer now and replace [.filename]#ada1p1#. Recreate the " "GPT partition of type `freebsd-zfs` on the new disk. Power up the computer " "and return [.filename]#ada1p1# to the pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:422 #, no-wrap msgid "# zpool replace storage ada1p1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:425 msgid "" "Next, check the status again, this time without `-x` to display all pools:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:433 #, no-wrap msgid "" "# zpool status storage\n" " pool: storage\n" " state: ONLINE\n" " scan: resilvered 3.21G in 00:04:36 with 0 errors on Sat Jul 11 10:32:19 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:440 #: documentation/content/en/books/handbook/zfs/_index.adoc:486 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " storage ONLINE 0 0 0\n" " raidz1-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 0\n" " ada2p1 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:445 msgid "In this example, everything is normal." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:447 #, no-wrap msgid "Data Verification" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:451 msgid "" "ZFS uses checksums to verify the integrity of stored data. Creating file " "systems automatically enables them." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:458 msgid "" "Disabling Checksums is possible but _not_ recommended! Checksums take little " "storage space and provide data integrity. Most ZFS features will not work " "properly with checksums disabled. Disabling these checksums will not " "increase performance noticeably." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:461 msgid "" "Verifying the data checksums (called _scrubbing_) ensures integrity of the " "`storage` pool with:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:465 #, no-wrap msgid "# zpool scrub storage\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:471 msgid "" "The duration of a scrub depends on the amount of data stored. Larger " "amounts of data will take proportionally longer to verify. Since scrubbing " "is I/O intensive, ZFS allows a single scrub to run on each pool at a time. " "After scrubbing completes, view the status with `zpool status`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:479 #, no-wrap msgid "" "# zpool status storage\n" " pool: storage\n" " state: ONLINE\n" " scan: scrub repaired 0B in 00:19:16 with 0 errors on Sat Jul 11 10:32:19 2026\n" "config:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:492 msgid "" "Displaying the completion date of the last scrubbing helps decide when to " "start another. Routine scrubs help protect data from silent corruption and " "ensure the integrity of the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:494 msgid "Refer to man:zfs[8] and man:zpool[8] for other ZFS options." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:496 #, no-wrap msgid "`zpool` Administration" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:503 msgid "" "ZFS administration uses two main utilities. The `zpool` utility controls " "the operation of the pool and allows adding, removing, replacing, and " "managing disks. The crossref:zfs[zfs-zfs,`zfs`] utility allows creating, " "destroying, and managing datasets, both crossref:zfs[zfs-term-" "filesystem,file systems] and crossref:zfs[zfs-term-volume,volumes]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:505 #, no-wrap msgid "Creating and Destroying Storage Pools" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:515 msgid "" "The most important decision when creating a ZFS storage pool is which types " "of vdevs to group the physical disks into. See the list of crossref:zfs[zfs-" "term-vdev,vdev types] for details about the possible options. The vdev " "types determine the redundancy, capacity, and performance characteristics of " "a pool. A pool's layout is not fixed forever at creation time. Mirrors " "allow adding new disks to the vdev, and stripes upgrade to mirrors by " "attaching a new disk to the vdev. RAID-Z vdevs grow one disk at a time with " "crossref:zfs[zfs-zpool-raidz-expansion,RAID-Z expansion], which requires " "OpenZFS 2.3 or later, first available in FreeBSD 15.0. Adding new vdevs " "expands a pool at any time, and crossref:zfs[zfs-zpool-attach,removing top-" "level vdevs] is possible within limits. Reshaping a live pool takes time " "and I/O bandwidth, so choosing suitable vdev types up front remains " "important." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:517 msgid "" "Create a simple mirror pool on disks containing GPT partitions of type " "`freebsd-zfs`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:525 #, no-wrap msgid "" "# zpool create mypool mirror /dev/ada1p1 /dev/ada2p1\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:531 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 0\n" " ada2p1 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:536 msgid "" "To create more than one vdev with a single command, specify groups of disks " "separated by the vdev type keyword, `mirror` in this example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:544 #, no-wrap msgid "" "# zpool create mypool mirror /dev/ada1p1 /dev/ada2p1 mirror /dev/ada3p1 /dev/ada4p1\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:553 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 0\n" " ada2p1 ONLINE 0 0 0\n" " mirror-1 ONLINE 0 0 0\n" " ada3p1 ONLINE 0 0 0\n" " ada4p1 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:564 msgid "" "Pools can also use partitions rather than whole disks. Putting ZFS in a " "separate partition allows the same disk to have other partitions for other " "purposes. In particular, it allows adding partitions with bootcode and file " "systems needed for booting. This allows booting from disks that are also " "members of a pool. ZFS adds no performance penalty on FreeBSD when using a " "partition rather than a whole disk. Using partitions also allows the " "administrator to _under-provision_ the disks, using less than the full " "capacity. If a future replacement disk of the same nominal size as the " "original actually has a slightly smaller capacity, the smaller partition " "will still fit, using the replacement disk." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:566 msgid "" "Create a crossref:zfs[zfs-term-vdev-raidz,RAID-Z2] pool using partitions:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:574 #, no-wrap msgid "" "# zpool create mypool raidz2 /dev/ada0p1 /dev/ada1p1 /dev/ada2p1 /dev/ada3p1 /dev/ada4p1 /dev/ada5p1\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:584 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " raidz2-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 0\n" " ada2p1 ONLINE 0 0 0\n" " ada3p1 ONLINE 0 0 0\n" " ada4p1 ONLINE 0 0 0\n" " ada5p1 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:592 msgid "" "ZFS aligns and sizes its smallest writes to each vdev based on the vdev's " "`ashift` value, the base 2 logarithm of the sector size. OpenZFS detects " "the sector size the disks report when creating a vdev and chooses `ashift` " "accordingly. Some drives report 512-byte sectors for compatibility while " "using 4096-byte sectors internally. Create pools on such drives with an " "explicit `-o ashift=12` to force 4096-byte alignment:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:596 #, no-wrap msgid "# zpool create -o ashift=12 mypool mirror /dev/ada1p1 /dev/ada2p1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:601 msgid "" "Setting the man:sysctl[8] variable `vfs.zfs.vdev.min_auto_ashift` to `12` " "gives the same result for pool creation and for later `zpool add` and `zpool " "attach` operations. `ashift` is a property of each vdev, not of the pool as " "a whole. It is fixed when creating the vdev and cannot change afterwards, " "so verify it before committing data to a pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:607 msgid "" "Destroy a pool that is no longer needed to reuse the disks. Destroying a " "pool requires unmounting the file systems in that pool first. If any " "dataset is in use, the unmount operation fails without destroying the pool. " "Force the pool destruction with `-f`. This can cause undefined behavior in " "applications which had open files on those datasets." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:609 #, no-wrap msgid "Pool Properties" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:613 msgid "" "Like datasets, pools have properties that report status and control " "behavior. Display every property of a pool with `zpool get all _mypool_`, " "or name specific properties:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:620 #, no-wrap msgid "" "# zpool get health,capacity mypool\n" "NAME PROPERTY VALUE SOURCE\n" "mypool health ONLINE -\n" "mypool capacity 27% -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:623 msgid "Change a writable property with `zpool set`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:630 #, no-wrap msgid "" "# zpool set comment=\"Backup pool\" mypool\n" "# zpool get comment mypool\n" "NAME PROPERTY VALUE SOURCE\n" "mypool comment Backup pool local\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:636 msgid "" "Properties like `size`, `capacity`, `fragmentation`, and `health` are read-" "only status values. Others change how the pool behaves; this chapter uses " "`autoexpand` to grow a pool automatically (crossref:zfs[zfs-zpool-" "online,Growing a Pool]), `autoreplace` with hot spares (crossref:zfs[zfs-" "zpool-spares,Hot Spares and Automatic Replacement with zfsd]), `autotrim` on " "SSD pools (crossref:zfs[zfs-zpool-trim,TRIM and Initialization]), and " "`compatibility` for portable pools (crossref:zfs[zfs-zpool-upgrade,Upgrading " "a Storage Pool]). Set properties at pool creation time by passing `-o` to " "`zpool create`, as shown with `ashift` above. man:zpoolprops[7] describes " "every pool property." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:638 #, no-wrap msgid "Adding and Removing Devices" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:643 msgid "" "Two ways exist for adding disks to a pool: attaching a disk to an existing " "vdev with `zpool attach`, or adding vdevs to the pool with `zpool add`. " "Some crossref:zfs[zfs-term-vdev,vdev types] allow adding disks to the vdev " "after creation. RAID-Z vdevs accept new disks only through crossref:zfs[zfs-" "zpool-raidz-expansion,RAID-Z expansion]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:652 msgid "" "A pool created with a single disk lacks redundancy. It can detect " "corruption but can not repair it, because there is no other copy of the " "data. The crossref:zfs[zfs-term-copies,copies] property may be able to " "recover from a small failure such as a bad sector, but does not provide the " "same level of protection as mirroring or RAID-Z. Starting with a pool " "consisting of a single disk vdev, use `zpool attach` to add a new disk to " "the vdev, creating a mirror. Also use `zpool attach` to add new disks to a " "mirror group, increasing redundancy and read performance. When partitioning " "the disks used for the pool, replicate the layout of the first disk on to " "the second. Use `gpart backup` and `gpart restore` to make this process " "easier." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:654 msgid "" "Upgrade the single disk (stripe) vdev [.filename]#ada0p3# to a mirror by " "attaching [.filename]#ada1p3#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:661 #: documentation/content/en/books/handbook/zfs/_index.adoc:1087 #, no-wrap msgid "" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:665 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:682 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool attach mypool ada0p3 ada1p3\n" "Make sure to wait until resilver is done before rebooting.\n" "# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada1\n" "partcode written to ada1p1\n" "bootcode written to ada1\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "status: One or more devices is currently being resilvered. The pool will\n" " continue to function, possibly in a degraded state.\n" "action: Wait for the resilver to complete.\n" " scan: resilver in progress since Sat Jul 11 11:15:25 2026\n" " 738M scanned at 105M/s, 522M issued at 74.6M/s, 781M total\n" " 522M resilvered, 66.84% done, 00:00:03 to go\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:688 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0 (resilvering)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:695 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: resilvered 781M in 00:00:16 with 0 errors on Sat Jul 11 11:18:36 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:701 #: documentation/content/en/books/handbook/zfs/_index.adoc:734 #: documentation/content/en/books/handbook/zfs/_index.adoc:831 #: documentation/content/en/books/handbook/zfs/_index.adoc:1093 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:711 msgid "" "When adding disks to the existing vdev is not an option, an alternative " "method is to add another vdev to the pool. Adding vdevs provides higher " "performance by distributing writes across the vdevs. Each vdev provides its " "own redundancy. Mixing vdev types like `mirror` and `RAID-Z` is possible " "but discouraged. Adding a non-redundant vdev to a pool containing mirror or " "RAID-Z vdevs risks the data on the entire pool. Distributing writes means a " "failure of the non-redundant disk will result in the loss of a fraction of " "every block written to the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:716 msgid "" "ZFS stripes data across each of the vdevs. For example, with two mirror " "vdevs, this is effectively a RAID 10 that stripes writes across two sets of " "mirrors. ZFS allocates space so that each vdev reaches 100% full at the " "same time. Having vdevs with different amounts of free space will lower " "performance, as more data writes go to the less full vdev." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:718 msgid "" "When attaching new devices to a boot pool, remember to update the bootcode." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:720 msgid "" "Attach a second mirror group ([.filename]#ada2p3# and [.filename]#ada3p3#) " "to the existing mirror:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:728 #, no-wrap msgid "" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: resilvered 781M in 00:00:16 with 0 errors on Sat Jul 11 12:11:56 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:748 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool add mypool mirror ada2p3 ada3p3\n" "# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada2\n" "partcode written to ada2p1\n" "bootcode written to ada2\n" "# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada3\n" "partcode written to ada3p1\n" "bootcode written to ada3\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: resilvered 781M in 00:00:16 with 0 errors on Sat Jul 11 09:58:28 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:757 #: documentation/content/en/books/handbook/zfs/_index.adoc:864 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " mirror-1 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0\n" " ada3p3 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:767 msgid "" "`zpool add` also attaches dedicated log and cache devices to an existing " "pool. A crossref:zfs[zfs-term-vdev-log,log] vdev stores the ZFS intent log " "on separate low-latency storage, accelerating synchronous writes such as " "those issued by databases and NFS. Mirror log devices, because losing an " "unmirrored log device together with a system crash costs the pool the last " "few seconds of synchronous writes; see crossref:zfs[zfs-advanced-zil-slog," "\"Synchronous Writes, the ZIL, and SLOG\"] for sizing and tuning guidance. " "A crossref:zfs[zfs-term-vdev-cache,cache] vdev extends the crossref:zfs[zfs-" "term-arc,ARC] with a second level of read cache on fast storage. Cache " "devices need no redundancy, as ZFS reads any block that fails to read from " "the cache from the original pool disks instead. The contents of the cache, " "the crossref:zfs[zfs-term-l2arc,L2ARC], survive reboots by default." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:769 msgid "Add a mirrored log vdev and an NVMe cache device to an existing pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:779 #, no-wrap msgid "" "# zpool add mypool log mirror ada4p2 ada5p2\n" "# zpool add mypool cache nda0p2\n" "# zpool status mypool\n" " pool: mypool\n" " state: ONLINE\n" " scan: resilvered 781M in 00:00:16 with 0 errors on Sat Jul 11 09:58:28 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:794 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " mirror-1 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0\n" " ada3p3 ONLINE 0 0 0\n" " logs\n" " mirror-2 ONLINE 0 0 0\n" " ada4p2 ONLINE 0 0 0\n" " ada5p2 ONLINE 0 0 0\n" " cache\n" " nda0p2 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:800 msgid "" "`zpool detach` removes single disks from a mirror vdev when enough " "redundancy remains. If a single disk remains in a mirror group, that group " "ceases to be a mirror and becomes a stripe, risking the entire pool if that " "remaining disk fails." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:802 msgid "Remove a disk from a three-way mirror group:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:810 #, no-wrap msgid "" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 00:01:11 with 0 errors on Sat Jul 11 03:14:02 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:817 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:825 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool detach mypool ada2p3\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 00:01:11 with 0 errors on Sat Jul 11 03:14:02 2026\n" "config:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:842 msgid "" "`zpool remove` removes entire top-level vdevs from a pool. ZFS evacuates " "the vdev by copying all of its allocated data to the other vdevs in the " "pool, then detaches the disks. Removal works for hot spares, cache, log, " "special, and dedup devices, and for data vdevs that are single disks or " "mirrors. Data vdevs are not removable from pools that contain a top-level " "RAID-Z vdev, and all top-level vdevs in the pool must use the same " "`ashift`. The evacuation runs in the background and the pool stays online " "throughout; monitor progress with `zpool status`. After the removal " "completes, ZFS keeps an in-memory table mapping the blocks of the removed " "vdev to their new locations. The table is small but permanent; `zpool " "remove -n` estimates its memory use before starting a removal." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:844 msgid "Remove one of the two mirror vdevs from a pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:855 #, no-wrap msgid "" "# zpool remove mypool mirror-1\n" "# zpool status mypool\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 00:01:11 with 0 errors on Sat Jul 11 03:14:02 2026\n" "remove: Evacuation of mirror in progress since Sat Jul 11 10:15:31 2026\n" " 1.71G copied out of 2.32G at 111M/s, 73.71% done, 0h0m to go\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:873 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool status mypool\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 00:01:11 with 0 errors on Sat Jul 11 03:14:02 2026\n" "remove: Removal of vdev 1 copied 2.32G in 0h0m, completed on Sat Jul 11 10:15:53 2026\n" " 10.9K memory used for removed device mappings\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:880 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " indirect-1 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:886 msgid "" "The `indirect-1` entry is a placeholder for the removed vdev's remapped " "blocks and contains no disks. Cancel an in-progress removal with `zpool " "remove -s`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:888 #, no-wrap msgid "RAID-Z Expansion" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:891 msgid "" "RAID-Z expansion grows an existing RAID-Z vdev by one disk at a time, " "without changing its parity level." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:896 msgid "" "RAID-Z expansion requires OpenZFS 2.3 or later, first available in FreeBSD " "15.0. Pools created on earlier releases need the `raidz_expansion` feature " "enabled with `zpool upgrade` before expanding." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:899 msgid "" "To expand a RAID-Z vdev, run `zpool attach` with the name of the RAID-Z vdev " "as shown by `zpool status` and the new disk:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:903 #, no-wrap msgid "# zpool attach mypool raidz2-0 ada6p3\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:908 msgid "" "The expansion reflows the existing data across the enlarged set of disks in " "the background while the pool remains online and in use. Add `-w` to make " "`zpool attach` wait until the expansion completes. `zpool status` reports " "progress on the `expand:` line:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:918 #, no-wrap msgid "" "# zpool status mypool\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 06:14:36 with 0 errors on Sat Jul 11 04:31:19 2026\n" "expand: expansion of raidz2-0 in progress since Sat Jul 11 09:42:12 2026\n" " 1.83T / 5.36T copied at 186M/s, 34.14% done, 05:31:43 to go\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:929 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " raidz2-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0\n" " ada3p3 ONLINE 0 0 0\n" " ada4p3 ONLINE 0 0 0\n" " ada5p3 ONLINE 0 0 0\n" " ada6p3 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:934 msgid "" "When the expansion finishes, the capacity of the new disk becomes available:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:939 #, no-wrap msgid "" "# zpool status mypool | grep expand:\n" "expand: expanded raidz2-0 copied 5.36T in 08:23:35, on Sat Jul 11 18:05:47 2026\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:944 msgid "" "Blocks written before the expansion keep their old data-to-parity ratio and " "continue to occupy space accordingly. The full capacity gain from the new " "disk therefore applies to data written after the expansion, while old data " "benefits only when rewritten, for example with crossref:zfs[zfs-zfs-" "rewrite,`zfs rewrite`]. Repeat the procedure to grow a vdev by several " "disks, attaching one at a time." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:946 #, no-wrap msgid "dRAID Pools" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:953 msgid "" "dRAID is a variant of RAID-Z that distributes hot spare capacity across all " "disks in the vdev. A crossref:zfs[zfs-term-vdev-draid,dRAID] vdev is built " "from internal RAID-Z groups plus optional _distributed spares_, all spread " "evenly over every disk. When a disk fails, ZFS rebuilds into the " "distributed spare by reading from and writing to all remaining disks in " "parallel, completing in a fraction of the time a resilver onto a single " "spare disk takes. Replacing the failed disk then rebuilds it from the " "distributed spare, restoring full protection. dRAID targets pools with many " "disks, where RAID-Z rebuild times grow dangerously long." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:955 msgid "The vdev type spells out the complete layout, per man:zpoolconcepts[7]:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:959 #, no-wrap msgid "draid[parity][:datad][:childrenc][:sparess]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:965 msgid "" "_parity_ is the parity level of the internal groups, 1 to 3, defaulting to " "1. _data_ is the number of data devices per redundancy group, defaulting to " "8. _children_ is the total number of disks, serving as a cross-check when " "listing many devices. _spares_ is the number of distributed hot spares, " "defaulting to 0." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:967 msgid "" "Create a pool from a 24-disk dRAID vdev with double parity, 8 data disks per " "redundancy group, and 2 distributed spares:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:971 #, no-wrap msgid "# zpool create mypool draid2:8d:24c:2s ada0 ada1 ada2 ada3 ada4 ada5 ada6 ada7 ada8 ada9 ada10 ada11 ada12 ada13 ada14 ada15 ada16 ada17 ada18 ada19 ada20 ada21 ada22 ada23\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:974 msgid "" "The distributed spares appear under `spares` in `zpool status`, with names " "like `draid2-0-0` for the first spare of the first vdev." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:981 msgid "" "dRAID trades space efficiency for rebuild speed. Unlike RAID-Z, dRAID uses " "a fixed stripe width, padding smaller writes with zeros. With the default " "of 8 data disks and 4 KB sectors, the minimum allocation is 32 KB, which " "reduces usable capacity and compression effectiveness for datasets dominated " "by small blocks. The capacity of the distributed spares is also committed " "up front, whether or not a disk ever fails. Pairing a dRAID pool with a " "crossref:zfs[zfs-zpool-special,special vdev] keeps metadata and small blocks " "off the wide stripes and recovers much of the lost efficiency. For pools " "with a handful of disks, RAID-Z remains the better choice." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:983 #, no-wrap msgid "Special Allocation Classes" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:989 msgid "" "Special allocation classes dedicate vdevs to specific types of pool data. A " "crossref:zfs[zfs-term-vdev-special,special] vdev stores pool metadata such " "as indirect blocks and dnodes, and optionally the data blocks of small " "files. A `dedup` vdev stores the crossref:zfs[zfs-term-" "deduplication,deduplication] tables. Placing this metadata on fast devices " "such as NVMe mirrors speeds up metadata-heavy operations like directory " "traversal, `zfs list`, and deduplication lookups on pools of otherwise " "slower disks." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:991 msgid "Add a mirrored special vdev to an existing pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:995 #, no-wrap msgid "# zpool add mypool special mirror nda0 nda1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:998 msgid "" "New metadata allocations then go to the special vdev; existing metadata " "stays where it is until rewritten." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1000 msgid "" "Setting the `special_small_blocks` dataset property makes the special vdev " "store data blocks up to the given size as well:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1004 #, no-wrap msgid "# zfs set special_small_blocks=16K mypool/projects\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1009 msgid "" "Valid values are zero, which disables storing data blocks in the special " "class, or a power of two from 512 bytes up to 1 MB on FreeBSD 14.x; FreeBSD " "15.0 accepts values up to the maximum block size of 16 MB. Setting the " "property to the dataset's `recordsize` sends all data blocks of that dataset " "to the special class. When a special vdev fills up, new allocations spill " "back to the normal class instead of failing." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1015 msgid "" "A special vdev is not a cache. It holds the only copy of the pool metadata " "allocated to it, and losing it destroys the pool. Match the redundancy of " "special and dedup vdevs to the redundancy of the data vdevs, for example by " "using a mirror." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1019 msgid "" "Removing a special or dedup vdev with `zpool remove` is possible, subject to " "the restrictions described in crossref:zfs[zfs-zpool-attach,Adding and " "Removing Devices]. In practice, the matching `ashift` requirement often " "prevents removal when the special vdev uses devices with a different sector " "size than the data vdevs." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1021 #, no-wrap msgid "Checking the Status of a Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1027 msgid "" "Pool status is important. If a drive goes offline or ZFS detects a read, " "write, or checksum error, the corresponding error count increases. The " "`status` output shows the configuration and status of each device in the " "pool and the status of the entire pool. Actions to take and details about " "the last crossref:zfs[zfs-zpool-scrub,`scrub`] are also shown." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1035 #, no-wrap msgid "" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 02:25:36 with 0 errors on Sat Jul 11 06:51:26 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1045 #: documentation/content/en/books/handbook/zfs/_index.adoc:1341 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " raidz2-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0\n" " ada3p3 ONLINE 0 0 0\n" " ada4p3 ONLINE 0 0 0\n" " ada5p3 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1050 msgid "Options adjust the output to the task at hand:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1052 msgid "" "`-v` displays verbose data error information, printing a complete list of " "the errors found since the last complete pool scrub, including the names of " "affected files." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1053 msgid "" "`-x` displays the status of pools with errors or pools that are otherwise " "unavailable, hiding healthy pools." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1054 msgid "" "`-s` displays the number of slow I/O operations on each leaf vdev, meaning " "operations that did not complete within 30 seconds." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1055 msgid "" "`-e` displays unhealthy vdevs only, keeping the output short for pools with " "many devices; this flag requires FreeBSD 14.1 or later." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1056 msgid "" "`-p` displays numbers as exact, parseable values instead of rounded human-" "readable ones." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1057 msgid "" "`-t` displays the crossref:zfs[zfs-zpool-trim,TRIM] status of each vdev." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1059 msgid "Refer to man:zpool-status[8] for the complete list of options." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1061 #, no-wrap msgid "Clearing Errors" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1067 msgid "" "When detecting an error, ZFS increases the read, write, or checksum error " "counts. Clear the error message and reset the counts with `zpool clear " "_mypool_`. Clearing the error state can be important for automated scripts " "that alert the administrator when the pool encounters an error. Without " "clearing old errors, the scripts may fail to report further errors." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1069 #, no-wrap msgid "Replacing a Functioning Device" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1078 msgid "" "It may be desirable to replace one disk with a different disk. When " "replacing a working disk, the process keeps the old disk online during the " "replacement. The pool never enters a crossref:zfs[zfs-term-" "degraded,degraded] state, reducing the risk of data loss. Running `zpool " "replace` copies the data from the old disk to the new one. After the " "operation completes, ZFS disconnects the old disk from the vdev. If the new " "disk is larger than the old disk, it may be possible to grow the zpool, " "using the new space. See crossref:zfs[zfs-zpool-online,Growing a Pool]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1080 msgid "Replace a functioning device in the pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1097 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool replace mypool ada1p3 ada2p3\n" "Make sure to wait until resilvering finishes before rebooting.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1099 #, no-wrap msgid "When booting from the pool 'mypool', update the boot code on the newly attached disk 'ada2p3'.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1101 #, no-wrap msgid "Assuming GPT partitioning is used and ada0 is the new boot disk, use the following command:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1114 #, no-wrap msgid "" " gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0\n" "# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada2\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "status: One or more devices is currently being resilvered. The pool will\n" " continue to function, possibly in a degraded state.\n" "action: Wait for the resilver to complete.\n" " scan: resilver in progress since Sat Jul 11 14:21:35 2026\n" " 781M / 781M scanned, 604M / 781M issued at 101M/s\n" " 604M resilvered, 77.39% done, 00:00:01 to go\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1122 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " replacing-1 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0 (resilvering)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1129 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: resilvered 781M in 00:00:17 with 0 errors on Sat Jul 11 14:21:52 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1135 #: documentation/content/en/books/handbook/zfs/_index.adoc:1213 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada2p3 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1144 msgid "" "On mirrored vdevs, adding `-s` to `zpool replace` or `zpool attach` performs " "a _sequential resilver_ instead of a healing resilver. A sequential " "resilver copies the data in disk order without verifying each block " "checksum, restoring redundancy much sooner. Since the copy skips checksum " "verification, ZFS starts a crossref:zfs[zfs-zpool-scrub,scrub] of the pool " "automatically after the sequential resilver completes. Sequential " "resilvering works on mirror and crossref:zfs[zfs-zpool-draid,dRAID] vdevs, " "not on RAID-Z. Restart an in-progress resilver from the beginning with " "`zpool resilver _mypool_`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1146 #, no-wrap msgid "Dealing with Failed Devices" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1154 msgid "" "When a disk in a pool fails, the vdev to which the disk belongs enters the " "crossref:zfs[zfs-term-degraded,degraded] state. The data is still " "available, but with reduced performance because ZFS computes missing data " "from the available redundancy. To restore the vdev to a fully functional " "state, replace the failed physical device. ZFS is then instructed to begin " "the crossref:zfs[zfs-term-resilver,resilver] operation. ZFS recomputes data " "on the failed device from available redundancy and writes it to the " "replacement device. After completion, the vdev returns to crossref:zfs[zfs-" "term-online,online] status." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1157 msgid "" "If the vdev does not have any redundancy, or if devices have failed and " "there is not enough redundancy to compensate, the pool enters the " "crossref:zfs[zfs-term-faulted,faulted] state. Unless enough devices can " "reconnect, the pool becomes inoperative, requiring a data restore from " "backups." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1160 msgid "" "When replacing a failed disk, the name of the failed disk changes to the " "GUID of the new disk. A new device name parameter for `zpool replace` is " "not required if the replacement device has the same device name." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1162 msgid "Replace a failed disk using `zpool replace`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1173 #, no-wrap msgid "" "# zpool status\n" " pool: mypool\n" " state: DEGRADED\n" "status: One or more devices could not be opened. Sufficient replicas exist for\n" " the pool to continue functioning in a degraded state.\n" "action: Attach the missing device and online it using 'zpool online'.\n" " see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-2Q\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1179 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool DEGRADED 0 0 0\n" " mirror-0 DEGRADED 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " 316502962686821739 UNAVAIL 0 0 0 was /dev/ada1p3\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1192 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool replace mypool 316502962686821739 ada2p3\n" "# zpool status\n" " pool: mypool\n" " state: DEGRADED\n" "status: One or more devices is currently being resilvered. The pool will\n" " continue to function, possibly in a degraded state.\n" "action: Wait for the resilver to complete.\n" " scan: resilver in progress since Sat Jul 11 14:52:21 2026\n" " 781M / 781M scanned, 641M / 781M issued at 128M/s\n" " 640M resilvered, 82.04% done, 00:00:01 to go\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1200 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool DEGRADED 0 0 0\n" " mirror-0 DEGRADED 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " replacing-1 UNAVAIL 0 0 0\n" " 15732067398082357289 UNAVAIL 0 0 0 was /dev/ada1p3/old\n" " ada2p3 ONLINE 0 0 0 (resilvering)\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1207 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: resilvered 781M in 00:00:17 with 0 errors on Sat Jul 11 14:52:38 2026\n" "config:\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1218 #, no-wrap msgid "Hot Spares and Automatic Replacement with zfsd" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1223 msgid "" "Pools with redundant vdevs can register crossref:zfs[zfs-term-vdev-spare,hot " "spare] disks that stand by to replace a failed device. A spare must be at " "least as large as the device it replaces. Specify spares at pool creation " "time by listing them after the `spare` keyword, as in `zpool create _mypool_ " "mirror _ada0p3_ _ada1p3_ spare _ada3p3_`, or add them to an existing pool " "with `zpool add`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1231 #, no-wrap msgid "" "# zpool add mypool spare ada3p3\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1239 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " ada1p3 ONLINE 0 0 0\n" " spares\n" " ada3p3 AVAIL\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1245 msgid "" "A spare stays idle, shown as `AVAIL`, until a device fails. Activate a " "spare by hand with `zpool replace`, naming the failed device and the spare:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1258 #, no-wrap msgid "" "# zpool replace mypool ada1p3 ada3p3\n" "# zpool status\n" " pool: mypool\n" " state: DEGRADED\n" "status: One or more devices could not be opened. Sufficient replicas exist for\n" " the pool to continue functioning in a degraded state.\n" "action: Attach the missing device and online it using 'zpool online'.\n" " see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-2Q\n" " scan: resilvered 781M in 00:00:21 with 0 errors on Sat Jul 11 09:14:33 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1268 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool DEGRADED 0 0 0\n" " mirror-0 DEGRADED 0 0 0\n" " ada0p3 ONLINE 0 0 0\n" " spare-1 DEGRADED 0 0 0\n" " ada1p3 UNAVAIL 0 0 0 cannot open\n" " ada3p3 ONLINE 0 0 0\n" " spares\n" " ada3p3 INUSE currently in use\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1275 msgid "" "The spare replacement is temporary by design, and the pool stays in this " "state until an administrator resolves it. After physically replacing the " "failed disk and resilvering the new device with crossref:zfs[zfs-zpool-" "replace,`zpool replace`], return the spare to standby with `zpool detach " "_mypool_ _ada3p3_`. To promote the spare to a permanent member of the vdev " "instead, detach the failed device with `zpool detach _mypool_ _ada1p3_`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1278 msgid "" "The `autoreplace` pool property, off by default, controls what happens when " "a new disk appears at the same physical location as a device that previously " "belonged to the pool. With `autoreplace` set to `on`, ZFS replaces the old " "device with the new disk automatically, without requiring a `zpool replace` " "command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1282 #, no-wrap msgid "# zpool set autoreplace=on mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1287 msgid "" "On FreeBSD, automatic reactions to failures, including honoring " "`autoreplace`, are performed by man:zfsd[8], the ZFS fault management daemon " "in the base system. The daemon is not enabled by default. Enable and start " "it with:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1292 #, no-wrap msgid "" "# sysrc zfsd_enable=\"YES\"\n" "# service zfsd start\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1295 msgid "man:zfsd[8] listens for pool events and:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1297 msgid "" "Activates a hot spare when a device disappears from a redundant vdev or when " "a vdev becomes degraded or faulted." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1298 msgid "" "Marks a vdev as faulted when it produces more than 50 I/O errors or more " "than 8 delayed I/O operations in a 60 second period, then activates a hot " "spare." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1299 msgid "" "Marks a vdev as degraded when it produces more than 50 checksum errors in a " "60 second period, then activates a hot spare." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1300 msgid "" "Brings a device back online when it reappears, triggering a resilver of the " "data written while it was missing." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1301 msgid "" "Replaces a missing device with a new disk that appears at the same physical " "location when the pool has `autoreplace` set to `on`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1302 msgid "" "Returns hot spares to standby once the resilver of a permanent replacement " "completes." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1307 msgid "" "FreeBSD uses man:zfsd[8] for fault management. The ZFS Event Daemon (ZED) " "found on Linux OpenZFS platforms is not part of FreeBSD." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1313 msgid "" "Inspect the event stream that drives these decisions with `zpool events`. " "Adding `-v` shows the full payload of each event, and `-f` keeps the command " "running, printing new events as they arrive. ZFS also delivers these events " "to man:devd[8]. The rules in [.filename]#/etc/devd/zfs.conf# log them to " "the system log and serve as a template for custom actions, such as sending " "mail when a pool becomes degraded." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1315 #, no-wrap msgid "Scrubbing a Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1320 msgid "" "Routinely crossref:zfs[zfs-term-scrub,scrub] pools, ideally at least once " "every month. The `scrub` operation is disk-intensive and will reduce " "performance while running. Avoid high-demand periods when scheduling " "`scrub`, or lower its impact with the I/O scheduler tunables described in " "crossref:zfs[zfs-advanced-tuning,Tuning]." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1331 #, no-wrap msgid "" "# zpool scrub mypool\n" "# zpool status\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub in progress since Sat Jul 11 20:52:54 2026\n" " 130G / 8.60T scanned at 649M/s, 116G / 8.60T issued at 580M/s\n" " 0B repaired, 1.32% done, 04:15:41 to go\n" "config:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1350 msgid "" "Pause a running scrub with `zpool scrub -p _mypool_` when it interferes with " "other work; running `zpool scrub _mypool_` again resumes it from where it " "stopped. To cancel a scrub operation instead, run `zpool scrub -s " "_mypool_`. `zpool scrub -w _mypool_` waits until the scrub completes before " "returning, which is useful in scripts. After a scrub reports errors, `zpool " "scrub -e _mypool_` performs an _error scrub_ that re-verifies only the " "blocks with known errors, finishing much faster than a full scrub. The " "error scrub requires OpenZFS 2.2, first shipped in FreeBSD 14.0." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1353 msgid "" "man:periodic[8] can run scrubs automatically. To scrub every pool whose " "last scrub is more than 35 days old, add this line to [.filename]#/etc/" "periodic.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1357 #, no-wrap msgid "daily_scrub_zfs_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1362 msgid "" "Set `daily_scrub_zfs_default_threshold=\"_days_\"` to change the number of " "days between scrubs. man:periodic.conf[5] also describes per-pool " "thresholds. Setting `daily_status_zfs_enable=\"YES\"` adds a pool health " "check to the daily man:periodic[8] report." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1364 #, no-wrap msgid "Self-Healing" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1375 msgid "" "The checksums stored with data blocks enable the file system to _self-" "heal_. This feature will automatically repair data whose checksum does not " "match the one recorded on another device that is part of the storage pool. " "For example, a mirror configuration with two disks where one drive is " "starting to malfunction and cannot properly store the data any more. This " "is worse when the data was not accessed for a long time, as with long term " "archive storage. Traditional file systems need to run commands that check " "and repair the data like man:fsck[8]. These commands take time, and in " "severe cases, an administrator has to decide which repair operation to " "perform. When ZFS detects a data block with a mismatched checksum, it tries " "to read the data from the mirror disk. If that disk can provide the correct " "data, ZFS will give that to the application and correct the data on the disk " "with the wrong checksum. This happens without any interaction from a system " "administrator during normal pool operation." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1377 msgid "" "The next example shows this self-healing behavior by creating a mirrored " "pool of partitions [.filename]#/dev/ada0p1# and [.filename]#/dev/ada1p1#." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1385 #, no-wrap msgid "" "# zpool create healer mirror /dev/ada0p1 /dev/ada1p1\n" "# zpool status healer\n" " pool: healer\n" " state: ONLINE\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1391 #: documentation/content/en/books/handbook/zfs/_index.adoc:1545 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " healer ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 0\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1396 #, no-wrap msgid "" "errors: No known data errors\n" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "healer 960M 111K 960M - - 0% 0% 1.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1399 msgid "" "Copy some important data to the pool to protect from data errors using the " "self-healing feature and create a checksum of the pool for later comparison." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1409 #, no-wrap msgid "" "# cp /some/important/data /healer\n" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "healer 960M 67.7M 892M - - 0% 7% 1.00x ONLINE -\n" "# sha1 /healer > checksum.txt\n" "# cat checksum.txt\n" "SHA1 (/healer) = 2753eff56d77d9a536ece6694bf0a82740344d1f\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1413 msgid "" "Simulate data corruption by writing random data to the beginning of one of " "the disks in the mirror. To keep ZFS from healing the data when detected, " "export the pool before the corruption and import it again afterwards." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1421 msgid "" "This is a dangerous operation that can destroy vital data, shown here for " "demonstration alone. *Do not try* it during normal operation of a storage " "pool. Nor should this intentional corruption example run on any disk with a " "file system not using ZFS on another partition in it. Do not use any other " "disk device names other than the ones that are part of the pool. Ensure " "proper backups of the pool exist and test them before running the command!" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1431 #, no-wrap msgid "" "# zpool export healer\n" "# dd if=/dev/random of=/dev/ada1p1 bs=1m count=200\n" "200+0 records in\n" "200+0 records out\n" "209715200 bytes transferred in 62.992162 secs (3329227 bytes/sec)\n" "# zpool import healer\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1437 msgid "" "The pool status shows that one device has experienced an error. Note that " "applications reading data from the pool did not receive any incorrect data. " "ZFS provided data from the [.filename]#ada0p1# device with the correct " "checksums. To find the device with the wrong checksum, look for one whose " "`CKSUM` column contains a nonzero value." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1449 #, no-wrap msgid "" "# zpool status healer\n" " pool: healer\n" " state: ONLINE\n" "status: One or more devices has experienced an unrecoverable error. An\n" " attempt was made to correct the error. Applications are unaffected.\n" "action: Determine if the device needs to be replaced, and clear the errors\n" " using 'zpool clear' or replace the device with 'zpool replace'.\n" " see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-9P\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1455 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " healer ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1461 msgid "" "ZFS detected the error and handled it by using the redundancy present in the " "unaffected [.filename]#ada0p1# mirror device. A checksum comparison with " "the original one will reveal whether the pool is consistent again." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1468 #, no-wrap msgid "" "# sha1 /healer >> checksum.txt\n" "# cat checksum.txt\n" "SHA1 (/healer) = 2753eff56d77d9a536ece6694bf0a82740344d1f\n" "SHA1 (/healer) = 2753eff56d77d9a536ece6694bf0a82740344d1f\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1477 msgid "" "Generate checksums before and after the intentional tampering while the pool " "data still matches. This shows how ZFS is capable of detecting and " "correcting any errors automatically when the checksums differ. Note this is " "possible with enough redundancy present in the pool. A pool consisting of a " "single device has no self-healing capabilities. That is also the reason why " "checksums are so important in ZFS; do not disable them for any reason. ZFS " "requires no man:fsck[8] or similar file system consistency check program to " "detect and correct this, and keeps the pool available while there is a " "problem. A scrub operation is now required to overwrite the corrupted data " "on [.filename]#ada1p1#." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1493 #, no-wrap msgid "" "# zpool scrub healer\n" "# zpool status healer\n" " pool: healer\n" " state: ONLINE\n" "status: One or more devices has experienced an unrecoverable error. An\n" " attempt was made to correct the error. Applications are unaffected.\n" "action: Determine if the device needs to be replaced, and clear the errors\n" " using 'zpool clear' or replace the device with 'zpool replace'.\n" " see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-9P\n" " scan: scrub in progress since Sat Jul 11 10:34:02 2026\n" " 40.8M scanned at 20.4M/s, 24.9M issued at 12.4M/s, 67.0M total\n" " 9.63M repaired, 37.16% done, 00:00:03 to go\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1499 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " healer ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 627 (repairing)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1505 msgid "" "The scrub operation reads data from [.filename]#ada0p1# and rewrites any " "data with a wrong checksum on [.filename]#ada1p1#, shown by the " "`(repairing)` output from `zpool status`. After the operation is complete, " "the pool status changes to:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1518 #, no-wrap msgid "" "# zpool status healer\n" " pool: healer\n" " state: ONLINE\n" "status: One or more devices has experienced an unrecoverable error. An\n" " attempt was made to correct the error. Applications are unaffected.\n" "action: Determine if the device needs to be replaced, and clear the errors\n" " using 'zpool clear' or replace the device with 'zpool replace'.\n" " see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-9P\n" " scan: scrub repaired 66.5M in 00:00:06 with 0 errors on Sat Jul 11 10:34:08 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1524 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " healer ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 2.72K\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1530 msgid "" "After the scrubbing operation completes with all the data synchronized from " "[.filename]#ada0p1# to [.filename]#ada1p1#, crossref:zfs[zfs-zpool-" "clear,clear] the error messages from the pool status by running `zpool " "clear`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1539 #, no-wrap msgid "" "# zpool clear healer\n" "# zpool status healer\n" " pool: healer\n" " state: ONLINE\n" " scan: scrub repaired 66.5M in 00:00:06 with 0 errors on Sat Jul 11 10:34:08 2026\n" "config:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1550 msgid "" "The pool is now back to a fully working state, with all error counts now " "zero." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1552 #, no-wrap msgid "TRIM and Initialization" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1556 msgid "" "Solid state drives and thinly provisioned storage perform best when ZFS " "tells them which blocks are no longer in use. `zpool trim` passes that " "information to every device in the pool that supports the TRIM or UNMAP " "commands:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1560 #, no-wrap msgid "# zpool trim mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1565 msgid "" "Trim a single device by naming it after the pool, as in `zpool trim mypool " "nda0p3`. `zpool trim -w` waits until trimming completes, `-c` cancels a " "running trim, and `-s` suspends it; running `zpool trim` again resumes a " "suspended trim. On devices that support it, `zpool trim --secure` requests " "a secure TRIM, where the device guarantees erasing the data stored on the " "trimmed blocks." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1567 msgid "`zpool status -t` shows the trim progress for each device:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1575 #, no-wrap msgid "" "# zpool status -t mypool\n" " pool: mypool\n" " state: ONLINE\n" " scan: scrub repaired 0B in 00:12:33 with 0 errors on Sat Jul 11 03:31:11 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1581 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " nda0p3 ONLINE 0 0 0 (23% trimmed, started at Sat Jul 11 09:15:04 2026)\n" " nda1p3 ONLINE 0 0 0 (22% trimmed, started at Sat Jul 11 09:15:04 2026)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1586 msgid "" "Setting the `autotrim` pool property to `on` makes ZFS issue small TRIM " "commands continuously as the pool frees space:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1590 #, no-wrap msgid "# zpool set autotrim=on mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1595 msgid "" "Automatic trimming skips small freed regions and puts a constant extra load " "on the devices. For most systems, leaving `autotrim` off and running a full " "`zpool trim` on a schedule gives better results. On FreeBSD 14.1 and later, " "man:periodic[8] runs such a trim daily when [.filename]#/etc/periodic.conf# " "contains `daily_trim_zfs_enable=\"YES\"`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1598 msgid "" "`zpool initialize` is the counterpart of trimming: it writes a pattern to " "all unallocated space on the specified devices, or on every eligible device " "in the pool when given no device names. This forces the backing storage to " "allocate the space up front, avoiding first-write latency on thinly " "provisioned virtual disks, and exercises new devices before trusting them " "with data." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1602 #, no-wrap msgid "# zpool initialize mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1606 msgid "" "As with trimming, `-c` cancels an initialization, `-s` suspends it, and `-w` " "waits for it to finish; `-u` removes the initialization state from the " "devices. See man:zpool-trim[8] and man:zpool-initialize[8] for details." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1608 #, no-wrap msgid "Pool Checkpoints" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1612 msgid "" "`zpool checkpoint` saves the state of the entire pool, including every " "dataset and the pool configuration, so that a later rewind returns the pool " "to the exact state it had when creating the checkpoint. Create a checkpoint " "before risky administrative operations such as upgrading the operating " "system, enabling new pool features, or reorganizing datasets:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1616 #, no-wrap msgid "# zpool checkpoint mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1620 msgid "" "A pool holds at most one checkpoint at a time. The `CKPOINT` column of " "`zpool list` shows how much space the checkpoint consumes as the pool " "diverges from the saved state:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1626 #, no-wrap msgid "" "# zpool list mypool\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "mypool 4.50T 1.42T 3.08T 221M - 4% 31% 1.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1629 msgid "" "To rewind, export the pool and import it again with `--rewind-to-checkpoint`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1634 #, no-wrap msgid "" "# zpool export mypool\n" "# zpool import --rewind-to-checkpoint mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1638 msgid "" "Rewinding discards every change made to the pool after creating the " "checkpoint, including newer snapshots and property changes. Discard a " "checkpoint that is no longer needed to release the space it holds; `-w` " "waits until the discard completes:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1642 #, no-wrap msgid "# zpool checkpoint -d -w mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1646 msgid "" "While a checkpoint exists, ZFS refuses operations that change the pool " "structure: `zpool remove`, `zpool attach`, `zpool detach`, `zpool split`, " "and `zpool reguid`. Space freed after creating the checkpoint is not " "reclaimed until the checkpoint is discarded, so a long-lived checkpoint on a " "busy pool can fill it up." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1651 msgid "" "A checkpoint is not a replacement for crossref:zfs[zfs-zfs-" "snapshot,snapshots] or backups. It protects against administrative mistakes " "for a short period, lives on the same disks as the pool, and rewinding " "discards everything written after its creation." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1654 msgid "See man:zpool-checkpoint[8] for details." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1656 #, no-wrap msgid "Growing a Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1666 msgid "" "The smallest device in each vdev limits the usable size of a redundant " "pool. Replace the smallest device with a larger device. After completing a " "crossref:zfs[zfs-zpool-replace,replace] or crossref:zfs[zfs-term-" "resilver,resilver] operation, the pool can grow to use the capacity of the " "new device. For example, consider a mirror of a 1 TB drive and a 2 TB " "drive. The usable space is 1 TB. When replacing the 1 TB drive with " "another 2 TB drive, the resilvering process copies the existing data onto " "the new drive. As both of the devices now have 2 TB capacity, the mirror's " "available space grows to 2 TB." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1669 msgid "" "The pool does not use the new capacity automatically by default. Set the " "`autoexpand` pool property to `on` before replacing the devices and the pool " "grows as soon as the last smaller device leaves the vdev:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1673 #, no-wrap msgid "# zpool set autoexpand=on mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1677 msgid "" "Otherwise, start expansion by using `zpool online -e` on each device. After " "expanding all devices, the extra space becomes available to the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1679 msgid "" "To grow a RAID-Z vdev by adding a disk instead of replacing the existing " "ones, see crossref:zfs[zfs-zpool-raidz-expansion,RAID-Z Expansion]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1681 #, no-wrap msgid "Importing and Exporting Pools" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1689 msgid "" "_Export_ pools before moving them to another system. ZFS unmounts all " "datasets, marking each device as exported but still locked to prevent use by " "other disks. This allows pools to be _imported_ on other machines, other " "operating systems that support ZFS, and even different hardware " "architectures (with some caveats, see man:zpool[8]). When a dataset has " "open files, use `zpool export -f` to force exporting the pool. Use this " "with caution. The datasets are forcibly unmounted, potentially resulting in " "unexpected behavior by the applications which had open files on those " "datasets." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1691 msgid "Export a pool that is not in use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1695 #, no-wrap msgid "# zpool export mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1703 msgid "" "Importing a pool automatically mounts the datasets. If this is undesired " "behavior, use `zpool import -N` to prevent it. `zpool import -o` sets " "temporary properties for this specific import. `zpool import -o altroot=` " "allows importing a pool with a base mount point instead of the root of the " "file system. If the pool was last used on a different system and was not " "properly exported, force the import using `zpool import -f`. `zpool import " "-a` imports all pools that do not appear to be in use by another system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1709 msgid "" "man:zpool-import[8] also provides options for recovering damaged pools. " "`zpool import -F` attempts to rewind the pool to an earlier transaction " "group when the most recent ones are damaged, discarding the last few seconds " "of writes. `zpool import -m` allows importing a pool whose dedicated log " "device is missing. `zpool import -o readonly=on` imports the pool read-" "only, preventing all writes, which is useful for forensics or when rescuing " "data from a failing pool. `zpool import -R /mnt` combines `altroot=/mnt` " "with `cachefile=none`, keeping a rescue import from disturbing the mount " "paths and the pool cache of the running system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1711 msgid "List all available pools for import:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1720 #, no-wrap msgid "" "# zpool import\n" " pool: mypool\n" " id: 9930174748043525076\n" " state: ONLINE\n" " action: The pool can be imported using its name or numeric identifier.\n" " config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1723 #, no-wrap msgid "" " mypool ONLINE\n" " ada0p1 ONLINE\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1726 msgid "Import the pool with an alternative root directory:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1733 #, no-wrap msgid "" "# zpool import -o altroot=/mnt mypool\n" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 110K 47.0G 31K /mnt/mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1738 msgid "" "At boot, the ZFS startup scripts enabled by `zfs_enable=\"YES\"` in " "[.filename]#/etc/rc.conf# import every pool recorded in [.filename]#/etc/zfs/" "zpool.cache#. Importing a pool adds it to that cache file automatically; " "the `cachefile` pool property controls this behavior. Pools imported with " "`cachefile=none` do not come back automatically after a reboot." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:1740 #, no-wrap msgid "Importing a GELI-Encrypted Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1744 msgid "" "The `Encrypt Disks` option of the FreeBSD installer encrypts the pool's " "partitions with man:geli[8], described in crossref:disks[disks-encrypting-" "geli,\"Encrypting Disk Partitions\"], rather than with crossref:zfs[zfs-" "native-encryption,ZFS native encryption]. On the installed system the " "loader prompts for the passphrase and attaches the providers before mounting " "the root pool, but ZFS itself knows nothing about the encryption: when " "booting from rescue media or moving the disks to another host, `zpool " "import` does not find the pool until the GELI providers are attached." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1746 msgid "" "Attach the encrypted [.filename]#freebsd-zfs# partition of every disk in the " "pool, supplying the passphrase, then import the pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1752 #, no-wrap msgid "" "# geli attach ada0p4\n" "Enter passphrase:\n" "# zpool import -f -R /mnt zroot\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1756 msgid "" "Use `gpart show` to identify the [.filename]#freebsd-zfs# partitions; with " "the default installer layout the encrypted partition is [.filename]#p4#. " "Systems installed with the legacy layout, which keeps a separate unencrypted " "boot pool, additionally store a key file in [.filename]#/boot/" "encryption.key# on that pool; attach those providers with `geli attach -k /" "path/to/encryption.key`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1758 #, no-wrap msgid "Upgrading a Storage Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1764 msgid "" "After upgrading FreeBSD, or if importing a pool from a system using an older " "version, manually upgrade the pool to make new on-disk features available. " "Consider whether the pool may ever need importing on an older system before " "upgrading. Upgrading is a one-way process. Upgrading older pools is " "possible, but downgrading pools with newer features is not." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1770 msgid "" "Pools do not carry a single version number anymore. Instead, each on-disk " "format change is an individual _feature flag_, described in man:zpool-" "features[7]. A feature is _enabled_ when the pool allows its use and " "becomes _active_ once the pool stores data that depends on it. An enabled " "but inactive feature does not affect compatibility. Once a feature is " "active, software without support for it can no longer import the pool, " "although pools whose active features are all \"read-only compatible\" still " "allow read-only imports." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1772 msgid "" "`zpool status` reports when supported features are not enabled on a pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1785 #, no-wrap msgid "" "# zpool status mypool\n" " pool: mypool\n" " state: ONLINE\n" "status: Some supported and requested features are not enabled on the pool.\n" " The pool can still be used, but some features are unavailable.\n" "action: Enable all features using 'zpool upgrade'. Once this is done,\n" " the pool may no longer be accessible by software that does not support\n" " the features. See zpool-features(7) for details.\n" " scan: scrub repaired 0B in 00:11:03 with 0 errors on Sat Jul 11 03:15:41 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1791 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " mirror-0 ONLINE 0 0 0\n" " ada0p1 ONLINE 0 0 0\n" " ada1p1 ONLINE 0 0 0\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1796 msgid "" "Running `zpool upgrade` without arguments lists every pool with disabled " "features:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1801 #, no-wrap msgid "" "# zpool upgrade\n" "This system supports ZFS pool feature flags.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1805 #, no-wrap msgid "" "Some supported features are not enabled on the following pools. Once a\n" "feature is enabled the pool may become incompatible with software\n" "that does not support the feature. See zpool-features(7) for details.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1808 #, no-wrap msgid "" "Note that the pool 'compatibility' feature can be used to inhibit\n" "feature upgrades.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1817 #, no-wrap msgid "" "POOL FEATURE\n" "---------------\n" "mypool\n" " zilsaxattr\n" " head_errlog\n" " blake3\n" " block_cloning\n" " vdev_zaps_v2\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1821 msgid "" "Use `zpool upgrade -v` to list every feature the running system supports, " "together with the legacy version numbers. Enable all supported features on " "a pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1826 #, no-wrap msgid "" "# zpool upgrade mypool\n" "This system supports ZFS pool feature flags.\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1833 #, no-wrap msgid "" "Enabled the following features on 'mypool':\n" " zilsaxattr\n" " head_errlog\n" " blake3\n" " block_cloning\n" " vdev_zaps_v2\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1836 msgid "" "Pools that must stay importable on systems running older ZFS software can " "restrict which features `zpool create` and `zpool upgrade` enable through " "the `compatibility` pool property:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1840 #, no-wrap msgid "# zpool create -o compatibility=openzfs-2.1-freebsd mypool mirror /dev/ada0p1 /dev/ada1p1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1845 msgid "" "Setting the property on an existing pool with `zpool set` works as well. " "Each named feature set corresponds to a file in [.filename]#/usr/share/zfs/" "compatibility.d#, and the default value `off` allows every feature. Setting " "the property does not disable features that are already enabled." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1851 msgid "" "Update the boot code on systems that boot from a pool to support the new " "pool features. Use `gpart bootcode` on the partition that contains the boot " "code. Two types of bootcode are available, depending on the way the system " "boots: GPT (the most common option) and EFI (for more modern systems)." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1853 msgid "For legacy boot using GPT, use the following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1857 #, no-wrap msgid "# gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1860 msgid "For systems using EFI to boot, execute the following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1866 #, no-wrap msgid "" "# mount -t msdosfs /dev/ada1p1 /boot/efi\n" "# cp /boot/loader.efi /boot/efi/efi/boot/BOOTX64.efi\n" "# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1871 msgid "" "These instructions apply to amd64 systems. Depending on the architecture, " "the file has a different name. Refer to man:uefi[8] to find the names of " "the architecture-specific files." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1874 msgid "" "Apply the bootcode to all bootable disks in the pool. See man:gpart[8] for " "more information." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1877 #, no-wrap msgid "Displaying Recorded Pool History" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1883 msgid "" "ZFS records commands that change the pool, including creating datasets, " "changing properties, or replacing a disk. Reviewing history about a pool's " "creation is useful, as is checking which user performed a specific action " "and when. History is not kept in a log file, but is part of the pool " "itself. The command to review this history is aptly named `zpool history`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1892 #, no-wrap msgid "" "# zpool history\n" "History for 'tank':\n" "2026-07-11.10:24:05 zpool create tank mirror /dev/ada0p1 /dev/ada1p1\n" "2026-07-11.18:50:58 zfs set atime=off tank\n" "2026-07-11.18:51:09 zfs set checksum=fletcher4 tank\n" "2026-07-11.18:51:18 zfs create tank/backup\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1897 msgid "" "The output shows `zpool` and `zfs` commands altering the pool in some way " "along with a timestamp. Commands like `zfs list` are not included. When " "specifying no pool name, ZFS displays history of all pools." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1900 msgid "" "`zpool history` can show even more information when providing the options `-" "i` or `-l`. `-i` displays user-initiated events as well as internally " "logged ZFS events." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1912 #, no-wrap msgid "" "# zpool history -i\n" "History for 'tank':\n" "2026-07-11.10:24:05 [txg:5] create pool version 5000; software version zfs-2.2.7-FreeBSD_gd75f9ee8b; uts myzfsbox 14.3-RELEASE 1403000 amd64\n" "2026-07-11.18:50:53 [txg:50] set tank (21) atime=0\n" "2026-07-11.18:50:58 zfs set atime=off tank\n" "2026-07-11.18:51:04 [txg:53] set tank (21) checksum=7\n" "2026-07-11.18:51:09 zfs set checksum=fletcher4 tank\n" "2026-07-11.18:51:13 [txg:55] create tank/backup (39)\n" "2026-07-11.18:51:18 zfs create tank/backup\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1916 msgid "" "Show more details by adding `-l`. Showing history records in a long format, " "including information like the name of the user who issued the command and " "the hostname on which the change happened." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1925 #, no-wrap msgid "" "# zpool history -l\n" "History for 'tank':\n" "2026-07-11.10:24:05 zpool create tank mirror /dev/ada0p1 /dev/ada1p1 [user 0 (root) on myzfsbox:global]\n" "2026-07-11.18:50:58 zfs set atime=off tank [user 0 (root) on myzfsbox:global]\n" "2026-07-11.18:51:09 zfs set checksum=fletcher4 tank [user 0 (root) on myzfsbox:global]\n" "2026-07-11.18:51:18 zfs create tank/backup [user 0 (root) on myzfsbox:global]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1931 msgid "" "The output shows that the `root` user created the mirrored pool with disks " "[.filename]#/dev/ada0p1# and [.filename]#/dev/ada1p1#. The hostname " "`myzfsbox` is also shown with each command. The hostname display becomes " "important when exporting the pool from one system and importing on another. " "It's possible to distinguish the commands issued on the other system by the " "hostname recorded for each command." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1934 msgid "" "Combine both options to `zpool history` to give the most detailed " "information possible for any given pool. Pool history provides valuable " "information when tracking down the actions performed or when needing more " "detailed output for debugging." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:1936 #, no-wrap msgid "Performance Monitoring" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1943 msgid "" "A built-in monitoring system can display pool I/O statistics in real time. " "It shows the amount of free and used space on the pool, read and write " "operations performed per second, and I/O bandwidth used. By default, ZFS " "monitors and displays all pools in the system. Provide a pool name to limit " "monitoring to that pool. A basic example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1951 #, no-wrap msgid "" "# zpool iostat\n" " capacity operations bandwidth\n" "pool alloc free read write read write\n" "---------- ----- ----- ----- ----- ----- -----\n" "data 288G 1.53T 2 11 11.3K 57.1K\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1957 msgid "" "To continuously see I/O activity, specify a number as the last parameter, " "indicating an interval in seconds to wait between updates. The next " "statistic line prints after each interval. Press kbd:[Ctrl+C] to stop this " "continuous monitoring. Give a second number on the command line after the " "interval to specify the total number of statistics to display." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1962 msgid "" "Display even more detailed I/O statistics with `-v`. Each device in the " "pool appears with a statistics line. This is useful for seeing read and " "write operations performed on each device, and can help determine if any " "individual device is slowing down the pool. This example shows a mirrored " "pool with two devices:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1974 #, no-wrap msgid "" "# zpool iostat -v\n" " capacity operations bandwidth\n" "pool alloc free read write read write\n" "----------------------- ----- ----- ----- ----- ----- -----\n" "data 288G 1.53T 2 12 9.23K 61.5K\n" " mirror 288G 1.53T 2 12 9.23K 61.5K\n" " ada1p1 - - 0 4 5.61K 61.7K\n" " ada2p1 - - 1 4 5.04K 61.7K\n" "----------------------- ----- ----- ----- ----- ----- -----\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1980 msgid "" "`zpool iostat` offers several deeper views of the I/O pipeline. `-l` adds " "average latency columns, splitting the total wait time into disk time and " "time spent in the various I/O queues. `-q` shows the number of pending and " "active operations in each per-vdev queue. `-w` prints full latency " "histograms, and `-r` prints request size histograms for each leaf vdev." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1982 msgid "" "The latency columns of `-l` make it easy to spot a single slow disk dragging " "down a whole vdev:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:1994 #, no-wrap msgid "" "# zpool iostat -lv data\n" " capacity operations bandwidth total_wait disk_wait syncq_wait asyncq_wait scrub trim rebuild\n" "pool alloc free read write read write read write read write read write read write wait wait wait\n" "---------- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -------\n" "data 288G 1.53T 156 212 19.4M 26.6M 14ms 186ms 5ms 184ms 1us 2us 8ms 2ms - - -\n" " mirror-0 288G 1.53T 156 212 19.4M 26.6M 14ms 186ms 5ms 184ms 1us 2us 8ms 2ms - - -\n" " ada1p1 - - 79 106 9.7M 13.3M 3ms 5ms 3ms 4ms 1us 2us 1ms 1ms - - -\n" " ada2p1 - - 77 106 9.7M 13.3M 212ms 187ms 208ms 183ms 1us 2us 15ms 3ms - - -\n" "---------- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -------\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:1999 msgid "" "In this example, [.filename]#ada2p1# needs hundreds of milliseconds of disk " "time for I/O that its mirror partner [.filename]#ada1p1# completes in single-" "digit milliseconds, while both handle a similar number of operations. A " "write to the mirror only completes when the slowest member finishes, so the " "write latency of the whole vdev tracks [.filename]#ada2p1#. High latency at " "normal operation counts, without read, write, or checksum errors in `zpool " "status`, often indicates a disk that retries internally and is a candidate " "for replacement." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2001 msgid "" "Scripts that must wait for background pool activity to finish can block on " "`zpool wait`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2005 #, no-wrap msgid "# zpool wait -t scrub,resilver mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2009 msgid "" "The command returns once none of the named activities, such as `scrub`, " "`resilver`, `trim`, or `remove`, are in progress. See man:zpool-wait[8] for " "the full list of activities." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2014 msgid "" "`zpool status`, `zpool list`, `zpool get`, and `zfs list` accept `-j` to " "produce JSON output, which is more robust for scripts to parse than the " "human-readable tables. JSON output requires OpenZFS 2.3 or later, first " "available in FreeBSD 15.0." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2017 #, no-wrap msgid "Splitting a Storage Pool" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2024 msgid "" "ZFS can split a pool consisting of one or more mirror vdevs into two pools. " "Unless otherwise specified, ZFS detaches the last member of each mirror and " "creates a new pool containing the same data. Be sure to make a dry run of " "the operation with `-n` first. This displays the details of the requested " "operation without actually performing it. This helps confirm that the " "operation will do what the user intends." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:2026 #, no-wrap msgid "`zfs` Administration" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2030 msgid "" "The `zfs` utility can create, destroy, and manage all existing ZFS datasets " "within a pool. To manage the pool itself, use crossref:zfs[zfs-" "zpool,`zpool`]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2032 #, no-wrap msgid "Creating and Destroying Datasets" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2043 msgid "" "Unlike traditional disks and volume managers, space in ZFS is _not_ " "preallocated. With traditional file systems, after partitioning and " "assigning the space, there is no way to add a new file system without adding " "a new disk. With ZFS, creating new file systems is possible at any time. " "Each crossref:zfs[zfs-term-dataset,_dataset_] has properties including " "features like compression, deduplication, caching, and quotas, as well as " "other useful properties like readonly, case sensitivity, network file " "sharing, and a mount point. Nesting datasets within each other is possible " "and child datasets will inherit properties from their ancestors. " "crossref:zfs[zfs-zfs-allow,Delegate], crossref:zfs[zfs-zfs-send,replicate], " "crossref:zfs[zfs-zfs-snapshot,snapshot], crossref:zfs[zfs-zfs-jail,jail] " "allows administering and destroying each dataset as a unit. Creating a " "separate dataset for each different type or set of files has advantages. " "The drawbacks to having a large number of datasets are that some commands " "like `zfs list` will be slower, and that mounting of hundreds or even " "thousands of datasets will slow the FreeBSD boot process." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2045 msgid "" "Create a new dataset and enable crossref:zfs[zfs-term-compression-lz4,LZ4 " "compression] on it:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2080 #, no-wrap msgid "" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 781M 93.2G 144K none\n" "mypool/ROOT 777M 93.2G 144K none\n" "mypool/ROOT/default 777M 93.2G 777M /\n" "mypool/tmp 176K 93.2G 176K /tmp\n" "mypool/usr 616K 93.2G 144K /usr\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/ports 144K 93.2G 144K /usr/ports\n" "mypool/usr/src 144K 93.2G 144K /usr/src\n" "mypool/var 1.20M 93.2G 608K /var\n" "mypool/var/crash 148K 93.2G 148K /var/crash\n" "mypool/var/log 178K 93.2G 178K /var/log\n" "mypool/var/mail 144K 93.2G 144K /var/mail\n" "mypool/var/tmp 152K 93.2G 152K /var/tmp\n" "# zfs create -o compress=lz4 mypool/usr/mydataset\n" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 781M 93.2G 144K none\n" "mypool/ROOT 777M 93.2G 144K none\n" "mypool/ROOT/default 777M 93.2G 777M /\n" "mypool/tmp 176K 93.2G 176K /tmp\n" "mypool/usr 704K 93.2G 144K /usr\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/mydataset 87.5K 93.2G 87.5K /usr/mydataset\n" "mypool/usr/ports 144K 93.2G 144K /usr/ports\n" "mypool/usr/src 144K 93.2G 144K /usr/src\n" "mypool/var 1.20M 93.2G 610K /var\n" "mypool/var/crash 148K 93.2G 148K /var/crash\n" "mypool/var/log 178K 93.2G 178K /var/log\n" "mypool/var/mail 144K 93.2G 144K /var/mail\n" "mypool/var/tmp 152K 93.2G 152K /var/tmp\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2083 msgid "" "Destroying a dataset is much quicker than deleting the files on the dataset, " "as it does not involve scanning the files and updating the corresponding " "metadata." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2085 msgid "Destroy the created dataset:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2120 #, no-wrap msgid "" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 880M 93.1G 144K none\n" "mypool/ROOT 777M 93.1G 144K none\n" "mypool/ROOT/default 777M 93.1G 777M /\n" "mypool/tmp 176K 93.1G 176K /tmp\n" "mypool/usr 101M 93.1G 144K /usr\n" "mypool/usr/home 184K 93.1G 184K /usr/home\n" "mypool/usr/mydataset 100M 93.1G 100M /usr/mydataset\n" "mypool/usr/ports 144K 93.1G 144K /usr/ports\n" "mypool/usr/src 144K 93.1G 144K /usr/src\n" "mypool/var 1.20M 93.1G 610K /var\n" "mypool/var/crash 148K 93.1G 148K /var/crash\n" "mypool/var/log 178K 93.1G 178K /var/log\n" "mypool/var/mail 144K 93.1G 144K /var/mail\n" "mypool/var/tmp 152K 93.1G 152K /var/tmp\n" "# zfs destroy mypool/usr/mydataset\n" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 781M 93.2G 144K none\n" "mypool/ROOT 777M 93.2G 144K none\n" "mypool/ROOT/default 777M 93.2G 777M /\n" "mypool/tmp 176K 93.2G 176K /tmp\n" "mypool/usr 616K 93.2G 144K /usr\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/ports 144K 93.2G 144K /usr/ports\n" "mypool/usr/src 144K 93.2G 144K /usr/src\n" "mypool/var 1.21M 93.2G 612K /var\n" "mypool/var/crash 148K 93.2G 148K /var/crash\n" "mypool/var/log 178K 93.2G 178K /var/log\n" "mypool/var/mail 144K 93.2G 144K /var/mail\n" "mypool/var/tmp 152K 93.2G 152K /var/tmp\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2129 msgid "" "In modern versions of ZFS, `zfs destroy` is asynchronous, and the free space " "might take minutes to appear in the pool. Use `zpool get freeing " "_poolname_` to see the `freeing` property, which shows how much space " "remains to reclaim in the background. Use `zpool wait -t free _poolname_` " "to wait until the background freeing completes. If there are child " "datasets, like crossref:zfs[zfs-term-snapshot,snapshots] or other datasets, " "destroying the parent is impossible. To destroy a dataset and its children, " "use `-r` to recursively destroy the dataset and its children. Use `-n -v` " "to list datasets and snapshots destroyed by this operation, without actually " "destroying anything. Space reclaimed by destroying snapshots is also shown." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2131 #, no-wrap msgid "Creating and Destroying Volumes" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2136 msgid "" "A volume is a special dataset type. Rather than mounting as a file system, " "expose it as a block device under [.filename]#/dev/zvol/poolname/dataset#. " "This allows using the volume for other file systems, to back the disks of a " "virtual machine, or to make it available to other network hosts using " "protocols like iSCSI or HAST." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2141 msgid "" "Format a volume with any file system or without a file system to store raw " "data. To the user, a volume appears to be a regular disk. Putting ordinary " "file systems on these _zvols_ provides features that ordinary disks or file " "systems do not have. For example, using the compression property on a 250 " "MB volume allows creation of a compressed FAT file system." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2155 #, no-wrap msgid "" "# zfs create -V 250m -o compression=on tank/fat32\n" "# zfs list tank\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "tank 258M 670M 31K /tank\n" "# newfs_msdos -F32 /dev/zvol/tank/fat32\n" "# mount -t msdosfs /dev/zvol/tank/fat32 /mnt\n" "# df -h /mnt | grep fat32\n" "Filesystem Size Used Avail Capacity Mounted on\n" "/dev/zvol/tank/fat32 249M 24k 249M 0% /mnt\n" "# mount | grep fat32\n" "/dev/zvol/tank/fat32 on /mnt (msdosfs, local)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2159 msgid "" "Creating a volume reserves enough space in the pool to hold the full volume " "size. To skip that reservation, create a _sparse volume_, also known as a " "thin provisioned volume, with `-s`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2163 #, no-wrap msgid "# zfs create -s -V 250g tank/bigdisk\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2167 msgid "" "Sparse volumes allow committing more space than the pool actually has. " "Writes to a sparse volume can fail with `ENOSPC` when the pool runs low on " "space, so use sparse volumes only where the consumer of the volume tolerates " "write errors." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2173 msgid "" "The `volmode` property controls how ZFS exposes a volume to the operating " "system. Setting it to `full` exposes the volume as a GEOM provider with " "maximal functionality, and `geom` is an alias for `full`. Setting it to " "`dev` exposes the volume as a plain device node, hiding any partitions it " "contains. Volumes with `volmode` set to `none` are not exposed outside ZFS " "at all, but still support snapshots, clones, and replication, making them " "useful as replication targets. The property defaults to `default`, which " "defers to the system-wide `zvol_volmode` tunable described in man:zfs[4]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2175 msgid "" "Volumes work well as virtual disks for man:bhyve[8] virtual machines and as " "backing storage for iSCSI extents: declare the volume device as a LUN in " "man:ctl.conf[5] and serve it with man:ctld[8]." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2182 msgid "" "Do not place swap space on ZFS volumes. When the system is low on memory, " "ZFS itself needs memory to complete the write that would release memory, and " "the system can deadlock. See the upstream OpenZFS issue link:https://" "github.com/openzfs/zfs/issues/7734[openzfs/zfs#7734] for details. Use a " "dedicated swap partition instead." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2186 msgid "" "Destroying a volume is much the same as destroying a regular file system " "dataset. The operation is nearly instantaneous, but it may take minutes to " "reclaim the free space in the background." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2188 #, no-wrap msgid "Renaming a Dataset" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2195 msgid "" "To change the name of a dataset, use `zfs rename`. To change the parent of " "a dataset, use this command as well. Renaming a dataset to have a different " "parent dataset will change the value of those properties inherited from the " "parent dataset. Renaming a dataset unmounts then remounts it in the new " "location (inherited from the new parent dataset). To prevent this behavior, " "use `-u`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2197 msgid "Rename a dataset and move it to be under a different parent dataset:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2233 #, no-wrap msgid "" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 780M 93.2G 144K none\n" "mypool/ROOT 777M 93.2G 144K none\n" "mypool/ROOT/default 777M 93.2G 777M /\n" "mypool/tmp 176K 93.2G 176K /tmp\n" "mypool/usr 704K 93.2G 144K /usr\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/mydataset 87.5K 93.2G 87.5K /usr/mydataset\n" "mypool/usr/ports 144K 93.2G 144K /usr/ports\n" "mypool/usr/src 144K 93.2G 144K /usr/src\n" "mypool/var 1.21M 93.2G 614K /var\n" "mypool/var/crash 148K 93.2G 148K /var/crash\n" "mypool/var/log 178K 93.2G 178K /var/log\n" "mypool/var/mail 144K 93.2G 144K /var/mail\n" "mypool/var/tmp 152K 93.2G 152K /var/tmp\n" "# zfs rename mypool/usr/mydataset mypool/var/newname\n" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 780M 93.2G 144K none\n" "mypool/ROOT 777M 93.2G 144K none\n" "mypool/ROOT/default 777M 93.2G 777M /\n" "mypool/tmp 176K 93.2G 176K /tmp\n" "mypool/usr 616K 93.2G 144K /usr\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/ports 144K 93.2G 144K /usr/ports\n" "mypool/usr/src 144K 93.2G 144K /usr/src\n" "mypool/var 1.29M 93.2G 614K /var\n" "mypool/var/crash 148K 93.2G 148K /var/crash\n" "mypool/var/log 178K 93.2G 178K /var/log\n" "mypool/var/mail 144K 93.2G 144K /var/mail\n" "mypool/var/newname 87.5K 93.2G 87.5K /var/newname\n" "mypool/var/tmp 152K 93.2G 152K /var/tmp\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2238 msgid "" "Renaming snapshots uses the same command. Due to the nature of snapshots, " "rename cannot change their parent dataset. To rename a recursive snapshot, " "specify `-r`; this will also rename all snapshots with the same name in " "child datasets." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2248 #, no-wrap msgid "" "# zfs list -t snapshot\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/newname@first_snapshot 0 - 87.5K -\n" "# zfs rename mypool/var/newname@first_snapshot new_snapshot_name\n" "# zfs list -t snapshot\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/newname@new_snapshot_name 0 - 87.5K -\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2251 #, no-wrap msgid "Setting Dataset Properties" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2261 msgid "" "Each ZFS dataset has properties that control its behavior. Most properties " "are automatically inherited from the parent dataset, but can be overridden " "locally. Set a property on a dataset with `zfs set _property=value " "dataset_`. Most properties have a limited set of valid values, `zfs get` " "will display each possible property and valid values. Using `zfs inherit` " "reverts most properties to their inherited values. User-defined properties " "are also possible. They become part of the dataset configuration and " "provide further information about the dataset or its contents. To " "distinguish these custom properties from the ones supplied as part of ZFS, " "use a colon (`:`) to create a custom namespace for the property." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2268 #, no-wrap msgid "" "# zfs set custom:costcenter=1234 tank\n" "# zfs get custom:costcenter tank\n" "NAME PROPERTY VALUE SOURCE\n" "tank custom:costcenter 1234 local\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2272 msgid "" "To remove a custom property, use `zfs inherit` with `-r`. If the custom " "property is not defined in any of the parent datasets, this option removes " "it (but the pool's history still records the change)." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2281 #, no-wrap msgid "" "# zfs inherit -r custom:costcenter tank\n" "# zfs get custom:costcenter tank\n" "NAME PROPERTY VALUE SOURCE\n" "tank custom:costcenter - -\n" "# zfs get all tank | grep custom:costcenter\n" "#\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2284 #, no-wrap msgid "Getting and Setting Share Properties" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2291 msgid "" "Two commonly used and useful dataset properties are the NFS and SMB share " "options. Setting these defines if and how ZFS shares datasets on the " "network. On FreeBSD, ZFS integrates with the NFS server in the base system: " "setting the `sharenfs` property exports the dataset through man:mountd[8]. " "ZFS writes the export entry to [.filename]#/etc/zfs/exports#, which " "man:mountd[8] reads in addition to [.filename]#/etc/exports#. Sharing " "datasets requires the NFS server enabled in [.filename]#/etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2296 #, no-wrap msgid "" "zfs_enable=\"YES\"\n" "nfs_server_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2299 msgid "" "The value of `sharenfs` is either `on`, `off`, or a list of man:exports[5] " "options to apply to the export." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2301 msgid "To get the current status of a share, enter:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2307 #, no-wrap msgid "" "# zfs get sharenfs mypool/usr/home\n" "NAME PROPERTY VALUE SOURCE\n" "mypool/usr/home sharenfs on local\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2310 msgid "To enable sharing of a dataset, enter:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2314 #, no-wrap msgid "# zfs set sharenfs=on mypool/usr/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2318 msgid "" "Set other options for sharing datasets through NFS, such as `-alldirs`, `-" "maproot` and `-network`. To set options on a dataset shared through NFS, " "enter:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2322 #, no-wrap msgid "# zfs set sharenfs=\"-alldirs,-maproot=root,-network=192.168.1.0/24\" mypool/usr/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2326 msgid "" "The `sharesmb` property is not functional on FreeBSD, as the sharing library " "implements NFS only. To serve a dataset over SMB, install a package such as " "package:net/samba422[] and export the path of the mounted dataset in its " "configuration." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2328 #, no-wrap msgid "NFSv4 ACLs" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2333 msgid "" "ZFS on FreeBSD stores NFSv4-style ACLs natively; the `acltype` dataset " "property defaults to `nfsv4`. Every file and directory can carry an access " "control list alongside the traditional permission bits, giving finer-grained " "control than the owner/group/other model. Display and edit these lists with " "man:getfacl[1] and man:setfacl[1]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2335 msgid "Display the ACL of a file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2345 #, no-wrap msgid "" "% getfacl /usr/home/alice/notes.txt\n" "# file: /usr/home/alice/notes.txt\n" "# owner: alice\n" "# group: alice\n" " owner@:rw-p--aARWcCos:-------:allow\n" " group@:r-----a-R-c--s:-------:allow\n" " everyone@:r-----a-R-c--s:-------:allow\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2348 msgid "Grant an additional user write access by adding an `allow` entry:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2352 #, no-wrap msgid "% setfacl -m u:bob:rwp::allow /usr/home/alice/notes.txt\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2359 msgid "" "Two dataset properties control how ACLs interact with traditional permission " "handling. The `aclmode` property (`discard`, `groupmask`, `passthrough`, or " "`restricted`) governs what happens to the ACL when man:chmod[1] changes the " "permission bits of a file. With the default, `discard`, chmod removes all " "ACL entries that do not represent the new file mode. The `aclinherit` " "property (`discard`, `noallow`, `restricted`, `passthrough`, or `passthrough-" "x`) governs which ACL entries new files and directories inherit from their " "parent directory. With the default, `restricted`, inherited entries lose " "the `write_acl` and `write_owner` permissions." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2361 msgid "" "See man:setfacl[1] and man:zfsprops[7] for the full entry syntax and " "property descriptions." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2363 #, no-wrap msgid "Managing Snapshots" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2377 msgid "" "crossref:zfs[zfs-term-snapshot,Snapshots] are one of the most powerful " "features of ZFS. A snapshot provides a read-only, point-in-time copy of the " "dataset. With Copy-On-Write (COW), ZFS creates snapshots fast by preserving " "older versions of the data on disk. If no snapshots exist, ZFS reclaims " "space for future use when data is rewritten or deleted. Snapshots preserve " "disk space by recording just the differences between the current dataset and " "a previous version. Allowing snapshots on whole datasets, not on individual " "files or directories. A snapshot from a dataset duplicates everything " "contained in it. This includes the file system properties, files, " "directories, permissions, and so on. Snapshots use no extra space when " "first created, but consume space as the blocks they reference change. " "Recursive snapshots taken with `-r` create snapshots with the same name on " "the dataset and its children, providing a consistent moment-in-time snapshot " "of the file systems. This can be important when an application has files on " "related datasets or that depend upon each other. Without snapshots, a " "backup would have copies of the files from different points in time." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2386 msgid "" "Snapshots in ZFS provide a variety of features that even other file systems " "with snapshot functionality lack. A typical example of snapshot use is as a " "quick way of backing up the current state of the file system when performing " "a risky action like a software installation or a system upgrade. If the " "action fails, rolling back to the snapshot returns the system to the same " "state when creating the snapshot. If the upgrade was successful, delete the " "snapshot to free up space. Without snapshots, a failed upgrade often " "requires restoring backups, which is tedious, time consuming, and may " "require downtime during which the system is unusable. Rolling back to " "snapshots is fast, even while the system is running in normal operation, " "with little or no downtime. The time savings are enormous with multi-" "terabyte storage systems considering the time required to copy the data from " "backup. Snapshots are not a replacement for a complete backup of a pool, " "but offer a quick and easy way to store a dataset copy at a specific time." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2388 #, no-wrap msgid "Creating Snapshots" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2392 msgid "" "To create snapshots, use `zfs snapshot _dataset_@_snapshotname_`. Adding `-" "r` creates a snapshot recursively, with the same name on all child datasets." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2394 msgid "Create a recursive snapshot of the entire pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2432 #, no-wrap msgid "" "# zfs list -t all\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool 780M 93.2G 144K none\n" "mypool/ROOT 777M 93.2G 144K none\n" "mypool/ROOT/default 777M 93.2G 777M /\n" "mypool/tmp 176K 93.2G 176K /tmp\n" "mypool/usr 616K 93.2G 144K /usr\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/ports 144K 93.2G 144K /usr/ports\n" "mypool/usr/src 144K 93.2G 144K /usr/src\n" "mypool/var 1.29M 93.2G 616K /var\n" "mypool/var/crash 148K 93.2G 148K /var/crash\n" "mypool/var/log 178K 93.2G 178K /var/log\n" "mypool/var/mail 144K 93.2G 144K /var/mail\n" "mypool/var/newname 87.5K 93.2G 87.5K /var/newname\n" "mypool/var/newname@new_snapshot_name 0 - 87.5K -\n" "mypool/var/tmp 152K 93.2G 152K /var/tmp\n" "# zfs snapshot -r mypool@my_recursive_snapshot\n" "# zfs list -t snapshot\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool@my_recursive_snapshot 0 - 144K -\n" "mypool/ROOT@my_recursive_snapshot 0 - 144K -\n" "mypool/ROOT/default@my_recursive_snapshot 0 - 777M -\n" "mypool/tmp@my_recursive_snapshot 0 - 176K -\n" "mypool/usr@my_recursive_snapshot 0 - 144K -\n" "mypool/usr/home@my_recursive_snapshot 0 - 184K -\n" "mypool/usr/ports@my_recursive_snapshot 0 - 144K -\n" "mypool/usr/src@my_recursive_snapshot 0 - 144K -\n" "mypool/var@my_recursive_snapshot 0 - 616K -\n" "mypool/var/crash@my_recursive_snapshot 0 - 148K -\n" "mypool/var/log@my_recursive_snapshot 0 - 178K -\n" "mypool/var/mail@my_recursive_snapshot 0 - 144K -\n" "mypool/var/newname@new_snapshot_name 0 - 87.5K -\n" "mypool/var/newname@my_recursive_snapshot 0 - 87.5K -\n" "mypool/var/tmp@my_recursive_snapshot 0 - 152K -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2437 msgid "" "Snapshots are not shown by a normal `zfs list` operation. To list " "snapshots, append `-t snapshot` to `zfs list`. `-t all` displays both file " "systems and snapshots." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2441 msgid "" "Snapshots are not mounted directly, showing no path in the `MOUNTPOINT` " "column. ZFS does not mention available disk space in the `AVAIL` column, as " "snapshots are read-only after their creation. Compare the snapshot to the " "original dataset:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2448 #, no-wrap msgid "" "# zfs list -rt all mypool/usr/home\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/usr/home 184K 93.2G 184K /usr/home\n" "mypool/usr/home@my_recursive_snapshot 0 - 184K -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2454 msgid "" "Displaying both the dataset and the snapshot together reveals how snapshots " "work in crossref:zfs[zfs-term-cow,COW] fashion. They save the changes " "(_delta_) made and not the complete file system contents all over again. " "This means that snapshots take little space when making changes. Observe " "space usage even more by copying a file to the dataset, then creating a " "second snapshot:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2464 #, no-wrap msgid "" "# cp /etc/passwd /var/tmp\n" "# zfs snapshot mypool/var/tmp@after_cp\n" "# zfs list -rt all mypool/var/tmp\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/tmp 206K 93.2G 118K /var/tmp\n" "mypool/var/tmp@my_recursive_snapshot 88K - 152K -\n" "mypool/var/tmp@after_cp 0 - 118K -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2469 msgid "" "The second snapshot contains the changes to the dataset after the copy " "operation. This yields enormous space savings. Notice that the size of the " "snapshot `_mypool/var/tmp@my_recursive_snapshot_` also changed in the `USED` " "column to show the changes between itself and the snapshot taken afterwards." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2471 #, no-wrap msgid "Comparing Snapshots" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2477 msgid "" "ZFS provides a built-in command to compare the differences in content " "between two snapshots. This is helpful with a lot of snapshots taken over " "time when the user wants to see how the file system has changed over time. " "For example, `zfs diff` lets a user find the latest snapshot that still " "contains a file deleted by accident. Doing this for the two snapshots " "created in the previous section yields this output:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2488 #, no-wrap msgid "" "# zfs list -rt all mypool/var/tmp\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/tmp 206K 93.2G 118K /var/tmp\n" "mypool/var/tmp@my_recursive_snapshot 88K - 152K -\n" "mypool/var/tmp@after_cp 0 - 118K -\n" "# zfs diff mypool/var/tmp@my_recursive_snapshot\n" "M /var/tmp/\n" "+ /var/tmp/passwd\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2492 msgid "" "The command lists the changes between the specified snapshot (in this case " "`_mypool/var/tmp@my_recursive_snapshot_`) and the live file system. The " "first column shows the change type:" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2498 #, no-wrap msgid "+" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2500 #, no-wrap msgid "Adding the path or file." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2501 #, no-wrap msgid "-" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2503 #, no-wrap msgid "Deleting the path or file." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2504 #, no-wrap msgid "M" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2506 #, no-wrap msgid "Modifying the path or file." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2507 #, no-wrap msgid "R" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:2508 #, no-wrap msgid "Renaming the path or file." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2512 msgid "" "Comparing the output with the table, it becomes clear that ZFS added " "[.filename]#passwd# after creating the snapshot `_mypool/var/" "tmp@my_recursive_snapshot_`. This also resulted in a modification to the " "parent directory mounted at `_/var/tmp_`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2514 msgid "" "Comparing two snapshots is helpful when using the ZFS replication feature to " "transfer a dataset to a different host for backup purposes." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2516 msgid "" "Compare two snapshots by providing the full dataset name and snapshot name " "of both datasets:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2528 #, no-wrap msgid "" "# cp /var/tmp/passwd /var/tmp/passwd.copy\n" "# zfs snapshot mypool/var/tmp@diff_snapshot\n" "# zfs diff mypool/var/tmp@my_recursive_snapshot mypool/var/tmp@diff_snapshot\n" "M /var/tmp/\n" "+ /var/tmp/passwd\n" "+ /var/tmp/passwd.copy\n" "# zfs diff mypool/var/tmp@my_recursive_snapshot mypool/var/tmp@after_cp\n" "M /var/tmp/\n" "+ /var/tmp/passwd\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2532 msgid "" "A backup administrator can compare two snapshots received from the sending " "host and determine the actual changes in the dataset. See the " "crossref:zfs[zfs-zfs-send,Replication] section for more information." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2534 #, no-wrap msgid "Snapshot Rollback" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2547 msgid "" "When at least one snapshot is available, roll back to it at any time. Most " "often this is the case when the current state of the dataset is no longer " "valid or an older version is preferred. Scenarios such as local development " "tests gone wrong, botched system updates hampering the system functionality, " "or the need to restore deleted files or directories are all too common " "occurrences. To roll back a snapshot, use `zfs rollback _snapshotname_`. " "If a lot of changes are present, the operation will take a long time. " "During that time, the dataset always remains in a consistent state, much " "like a database that conforms to ACID principles is performing a rollback. " "This is happening while the dataset is live and accessible without requiring " "a downtime. Once the snapshot rolled back, the dataset has the same state " "as it had when the snapshot was originally taken. Rolling back to a " "snapshot discards all other data in that dataset not part of the snapshot. " "Taking a snapshot of the current state of the dataset before rolling back to " "a previous one is a good idea when requiring some data later. This way, the " "user can roll back and forth between snapshots without losing data that is " "still valuable." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2549 msgid "" "In the first example, roll back a snapshot because a careless `rm` operation " "removed more data than intended." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2563 #, no-wrap msgid "" "# zfs list -rt all mypool/var/tmp\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/tmp 262K 93.2G 120K /var/tmp\n" "mypool/var/tmp@my_recursive_snapshot 88K - 152K -\n" "mypool/var/tmp@after_cp 53.5K - 118K -\n" "mypool/var/tmp@diff_snapshot 0 - 120K -\n" "# ls /var/tmp\n" "passwd passwd.copy vi.recover\n" "# rm /var/tmp/passwd*\n" "# ls /var/tmp\n" "vi.recover\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2568 msgid "" "At this point, the user notices the removal of extra files and wants them " "back. ZFS provides an easy way to get them back using rollbacks, when " "performing snapshots of important data on a regular basis. To get the files " "back and start over from the last snapshot, issue the command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2574 #, no-wrap msgid "" "# zfs rollback mypool/var/tmp@diff_snapshot\n" "# ls /var/tmp\n" "passwd passwd.copy vi.recover\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2579 msgid "" "The rollback operation restored the dataset to the state of the last " "snapshot. Rolling back to a snapshot taken much earlier with other " "snapshots taken afterwards is also possible. When trying to do this, ZFS " "will issue this warning:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2592 #, no-wrap msgid "" "# zfs list -rt snapshot mypool/var/tmp\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/tmp@my_recursive_snapshot 88K - 152K -\n" "mypool/var/tmp@after_cp 53.5K - 118K -\n" "mypool/var/tmp@diff_snapshot 0 - 120K -\n" "# zfs rollback mypool/var/tmp@my_recursive_snapshot\n" "cannot rollback to 'mypool/var/tmp@my_recursive_snapshot': more recent snapshots exist\n" "use '-r' to force deletion of the following snapshots:\n" "mypool/var/tmp@after_cp\n" "mypool/var/tmp@diff_snapshot\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2599 msgid "" "This warning means that snapshots exist between the current state of the " "dataset and the snapshot to which the user wants to roll back. To complete " "the rollback delete these snapshots. ZFS cannot track all the changes " "between different states of the dataset, because snapshots are read-only. " "ZFS will not delete the affected snapshots unless the user specifies `-r` to " "confirm that this is the desired action. If that is the intention, and " "understanding the consequences of losing all intermediate snapshots, issue " "the command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2608 #, no-wrap msgid "" "# zfs rollback -r mypool/var/tmp@my_recursive_snapshot\n" "# zfs list -rt snapshot mypool/var/tmp\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/var/tmp@my_recursive_snapshot 8K - 152K -\n" "# ls /var/tmp\n" "vi.recover\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2611 msgid "" "The output from `zfs list -t snapshot` confirms the removal of the " "intermediate snapshots as a result of `zfs rollback -r`." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2613 #, no-wrap msgid "Restoring Individual Files from Snapshots" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2620 msgid "" "Snapshots live in a hidden directory under the parent dataset: " "[.filename]#.zfs/snapshot/snapshotname#. By default, these directories will " "not show even when executing a standard `ls -a` . Although the directory " "doesn't show, access it like any normal directory. The property named " "`snapdir` controls whether these hidden directories show up in a directory " "listing. Setting the property to `visible` allows them to appear in the " "output of `ls` and other commands that deal with directory contents." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2631 #, no-wrap msgid "" "# zfs get snapdir mypool/var/tmp\n" "NAME PROPERTY VALUE SOURCE\n" "mypool/var/tmp snapdir hidden default\n" "# ls -a /var/tmp\n" ". .. passwd vi.recover\n" "# zfs set snapdir=visible mypool/var/tmp\n" "# ls -a /var/tmp\n" ". .. .zfs passwd vi.recover\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2636 msgid "" "Restore individual files to a previous state by copying them from the " "snapshot back to the parent dataset. The directory structure below " "[.filename]#.zfs/snapshot# has a directory named like the snapshots taken " "earlier to make it easier to identify them. The next example shows how to " "restore a file from the hidden [.filename]#.zfs# directory by copying it " "from the snapshot containing the latest version of the file:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2647 #, no-wrap msgid "" "# rm /var/tmp/passwd\n" "# ls -a /var/tmp\n" ". .. .zfs vi.recover\n" "# ls /var/tmp/.zfs/snapshot\n" "after_cp my_recursive_snapshot\n" "# ls /var/tmp/.zfs/snapshot/after_cp\n" "passwd vi.recover\n" "# cp /var/tmp/.zfs/snapshot/after_cp/passwd /var/tmp\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2654 msgid "" "Even if the `snapdir` property is set to hidden, running `ls .zfs/snapshot` " "will still list the contents of that directory. The administrator decides " "whether to display these directories. This is a per-dataset setting. " "Copying files or directories from this hidden [.filename]#.zfs/snapshot# is " "simple enough. Trying it the other way around results in this error:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2659 #, no-wrap msgid "" "# cp /etc/rc.conf /var/tmp/.zfs/snapshot/after_cp/\n" "cp: /var/tmp/.zfs/snapshot/after_cp/rc.conf: Read-only file system\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2663 msgid "" "The error reminds the user that snapshots are read-only and cannot change " "after creation. Copying files into and removing them from snapshot " "directories are both disallowed because that would change the state of the " "dataset they represent." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2666 msgid "" "Snapshots consume space based on how much the parent file system has changed " "since the time of the snapshot. The `used` property of a snapshot tracks " "the space the snapshot uses; its `written` property shows how much data was " "written between the previous snapshot and this one." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2670 msgid "" "To destroy snapshots and reclaim the space, use `zfs destroy " "_dataset_@_snapshot_`. Adding `-r` recursively removes all snapshots with " "the same name under the parent dataset. Adding `-n -v` to the command " "displays a list of the snapshots to be deleted and an estimate of the space " "it would reclaim without performing the actual destroy operation." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2672 #, no-wrap msgid "Snapshot Holds" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2679 msgid "" "A crossref:zfs[zfs-term-hold,hold] places a user-defined tag on a snapshot " "and prevents its destruction. Attempts to destroy a held snapshot with `zfs " "destroy` fail with `EBUSY`. A snapshot can carry any number of holds, each " "identified by a unique tag name. Holds protect snapshots that other " "processes still depend on, such as the most recent snapshot shared by both " "sides of a replication chain (see crossref:zfs[zfs-zfs-send,Replication]). " "Destroying that common snapshot by accident forces the next replication to " "start over with a full stream." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2682 msgid "" "Place a hold with `zfs hold _tag_ _snapshot_`. Adding `-r` also holds the " "snapshots with the same name on all child datasets." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2688 #, no-wrap msgid "" "# zfs hold keepme mypool/var/tmp@my_recursive_snapshot\n" "# zfs destroy mypool/var/tmp@my_recursive_snapshot\n" "cannot destroy snapshot mypool/var/tmp@my_recursive_snapshot: dataset is busy\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2691 msgid "" "`zfs holds` lists the holds on a snapshot, showing the tag name and the time " "of placing each hold:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2697 #, no-wrap msgid "" "# zfs holds mypool/var/tmp@my_recursive_snapshot\n" "NAME TAG TIMESTAMP\n" "mypool/var/tmp@my_recursive_snapshot keepme Sat Jul 11 09:41 2026\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2701 msgid "" "Remove a hold with `zfs release`. Destroying the snapshot becomes possible " "again once the last hold on it is released:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2706 #, no-wrap msgid "" "# zfs release keepme mypool/var/tmp@my_recursive_snapshot\n" "# zfs destroy mypool/var/tmp@my_recursive_snapshot\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2709 msgid "See man:zfs-hold[8] for more information." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2711 #, no-wrap msgid "Bookmarks" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2719 msgid "" "A crossref:zfs[zfs-term-bookmark,bookmark] records the point in time at " "which a snapshot was created, without keeping any of the snapshot data. " "Bookmarks consume almost no space, no matter how much the dataset changes " "afterwards. Like a snapshot, a bookmark can serve as the source of an " "incremental `zfs send`. Unlike a snapshot, it does not prevent ZFS from " "freeing the old data. This combination makes bookmarks useful for " "incremental replication: after sending a snapshot to another pool, bookmark " "it and destroy it on the sending side, reclaiming the space while the " "receiving side keeps its copy of the snapshot. See crossref:zfs[zfs-send-" "incremental,Incremental Backups] for the replication workflow itself." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2722 msgid "" "Create a bookmark from a snapshot with `zfs bookmark`. Bookmark names use " "`#` as the separator between the dataset name and the bookmark name, in the " "same way snapshot names use `@`." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2729 #, no-wrap msgid "" "# zfs snapshot mypool/data@snap1\n" "# zfs send mypool/data@snap1 | zfs receive backup/data\n" "# zfs bookmark mypool/data@snap1 mypool/data#snap1bm\n" "# zfs destroy mypool/data@snap1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2732 msgid "List bookmarks with `zfs list -t bookmark`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2738 #, no-wrap msgid "" "# zfs list -t bookmark mypool/data\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool/data#snap1bm - - 184K -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2741 msgid "" "When the time comes for the next incremental backup, take a new snapshot and " "use the bookmark as the incremental source:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2746 #, no-wrap msgid "" "# zfs snapshot mypool/data@snap2\n" "# zfs send -i mypool/data#snap1bm mypool/data@snap2 | zfs receive backup/data\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2752 msgid "" "This works because the receiving pool still has the snapshot _backup/" "data@snap1_ matching the bookmark. Bookmarks serve as incremental sources " "only. Mounting a bookmark, rolling back to it, or restoring files from it " "is impossible, as it contains no data. See man:zfs-bookmark[8] for more " "information." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2754 #, no-wrap msgid "Managing Clones" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2763 msgid "" "A clone is a copy of a snapshot treated more like a regular dataset. Unlike " "a snapshot, a clone is writeable and mountable, and has its own properties. " "After creating a clone using `zfs clone`, destroying the originating " "snapshot is impossible. To reverse the child/parent relationship between " "the clone and the snapshot use `zfs promote`. Promoting a clone makes the " "snapshot become a child of the clone, rather than of the original parent " "dataset. This will change how ZFS accounts for the space, but not actually " "change the amount of space consumed. Mounting the clone anywhere within the " "ZFS file system hierarchy is possible, not only below the original location " "of the snapshot." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2765 msgid "To show the clone feature use this example dataset:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2773 #, no-wrap msgid "" "# zfs list -rt all camino/home/joe\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "camino/home/joe 108K 1.3G 87K /usr/home/joe\n" "camino/home/joe@plans 21K - 85.5K -\n" "camino/home/joe@backup 0K - 87K -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2779 msgid "" "A typical use for clones is to experiment with a specific dataset while " "keeping the snapshot around to fall back to in case something goes wrong. " "Since snapshots cannot change, create a read/write clone of a snapshot. " "After achieving the desired result in the clone, promote the clone to a " "dataset and remove the old file system. Removing the parent dataset is not " "strictly necessary, as the clone and dataset can coexist without problems." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2786 #, no-wrap msgid "" "# zfs clone camino/home/joe@backup camino/home/joenew\n" "# ls /usr/home/joe*\n" "/usr/home/joe:\n" "backup.txz plans.txt\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2793 #, no-wrap msgid "" "/usr/home/joenew:\n" "backup.txz plans.txt\n" "# df -h /usr/home\n" "Filesystem Size Used Avail Capacity Mounted on\n" "usr/home/joe 1.3G 31k 1.3G 0% /usr/home/joe\n" "usr/home/joenew 1.3G 31k 1.3G 0% /usr/home/joenew\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2802 msgid "" "Creating a clone makes it an exact copy of the state the dataset was in when " "taking the snapshot. Changing the clone independently from its originating " "dataset is possible now. The connection between the two is the snapshot. " "ZFS records this connection in the property `origin`. Promoting the clone " "with `zfs promote` makes the clone an independent dataset. This removes the " "value of the `origin` property and disconnects the newly independent dataset " "from the snapshot. This example shows it:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2812 #, no-wrap msgid "" "# zfs get origin camino/home/joenew\n" "NAME PROPERTY VALUE SOURCE\n" "camino/home/joenew origin camino/home/joe@backup -\n" "# zfs promote camino/home/joenew\n" "# zfs get origin camino/home/joenew\n" "NAME PROPERTY VALUE SOURCE\n" "camino/home/joenew origin - -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2817 msgid "" "After making some changes like copying [.filename]#loader.conf# to the " "promoted clone, for example, the old directory becomes obsolete in this " "case. Instead, the promoted clone can replace it. To do this, `zfs " "destroy` the old dataset first and then `zfs rename` the clone to the old " "dataset name (or to an entirely different name)." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2828 #, no-wrap msgid "" "# cp /boot/defaults/loader.conf /usr/home/joenew\n" "# zfs destroy -f camino/home/joe\n" "# zfs rename camino/home/joenew camino/home/joe\n" "# ls /usr/home/joe\n" "backup.txz loader.conf plans.txt\n" "# df -h /usr/home\n" "Filesystem Size Used Avail Capacity Mounted on\n" "usr/home/joe 1.3G 128k 1.3G 0% /usr/home/joe\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2837 msgid "" "The cloned snapshot is now an ordinary dataset. It contains all the data " "from the original snapshot plus the files added to it like " "[.filename]#loader.conf#. Clones provide useful features to ZFS users in " "different scenarios. For example, provide jails as snapshots containing " "different sets of installed applications. Users can clone these snapshots " "and add their own applications as they see fit. Once satisfied with the " "changes, promote the clones to full datasets and provide them to end users " "to work with like they would with a real dataset. This saves time and " "administrative overhead when providing these jails." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2839 #, no-wrap msgid "Block Cloning" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2845 msgid "" "crossref:zfs[zfs-term-block-cloning,Block cloning] brings copy-on-write to " "individual file copies. When enabled, copying a file with man:cp[1] does " "not duplicate the file data. Instead, the new file refers to the same " "blocks as the original, and ZFS writes new blocks only when either file " "changes afterwards. man:cp[1] performs copies with man:copy_file_range[2], " "which ZFS turns into block clone operations, making copies within a pool " "almost instantaneous and consuming no additional space at first." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2849 msgid "" "Unlike crossref:zfs[zfs-zfs-deduplication,deduplication], block cloning " "keeps no memory-hungry table of checksums. Sharing happens at the moment of " "the copy only, and writing identical data in separate operations still " "stores it twice. Unlike crossref:zfs[zfs-zfs-clones,clones], block cloning " "requires no snapshot, works on individual files rather than whole datasets, " "and leaves no `origin` relationship behind." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2855 msgid "" "Block cloning requires the `block_cloning` pool feature from OpenZFS 2.2, " "first shipped in FreeBSD 14.0 (see man:zpool-features[7]). The " "man:sysctl[8] `vfs.zfs.bclone_enabled` controls whether ZFS actually creates " "block clones. It defaults to 0 on FreeBSD 14.x and to 1 on FreeBSD 15.0. " "While the sysctl is 0, `copy_file_range()` falls back to an ordinary copy. " "To enable block cloning on FreeBSD 14.x:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2860 #, no-wrap msgid "" "# sysctl vfs.zfs.bclone_enabled=1\n" "vfs.zfs.bclone_enabled: 0 -> 1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2863 msgid "" "To keep the setting across reboots, add this line to [.filename]#/etc/" "sysctl.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2867 #, no-wrap msgid "vfs.zfs.bclone_enabled=1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2870 msgid "" "The pool properties `bcloneused`, `bclonesaved`, and `bcloneratio` show the " "space used by cloned blocks, the space saved by cloning, and the resulting " "savings ratio:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2877 #, no-wrap msgid "" "# cp /var/tmp/database.dump /var/tmp/database.copy\n" "# zpool list -o name,bcloneused,bclonesaved,bcloneratio mypool\n" "NAME BCLONE_USED BCLONE_SAVED BCLONE_RATIO\n" "mypool 1.7G 1.7G 2.00x\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:2880 #, no-wrap msgid "Replication" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2889 msgid "" "Keeping data on a single pool in one location exposes it to risks like theft " "and natural or human disasters. Making regular backups of the entire pool " "is vital. ZFS provides a built-in serialization feature that can send a " "stream representation of the data to standard output. Using this feature, " "storing this data on another pool connected to the local system is possible, " "as is sending it over a network to another system. Snapshots are the basis " "for this replication (see the section on crossref:zfs[zfs-zfs-snapshot,ZFS " "snapshots]). The commands used for replicating data are `zfs send` and `zfs " "receive`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2891 msgid "These examples show ZFS replication with these two pools:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2898 #, no-wrap msgid "" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "backup 960M 77K 896M - - 0% 0% 1.00x ONLINE -\n" "mypool 984M 43.7M 940M - - 0% 4% 1.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2906 msgid "" "The pool named _mypool_ is the primary pool where writing and reading data " "happens on a regular basis. Using a second standby pool _backup_ in case " "the primary pool becomes unavailable. Note that this fail-over is not done " "automatically by ZFS, but must be manually done by a system administrator " "when needed. Use a snapshot to provide a consistent file system version to " "replicate. After creating a snapshot of _mypool_, copy it to the _backup_ " "pool by replicating snapshots. This does not include changes made since the " "most recent snapshot." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2913 #, no-wrap msgid "" "# zfs snapshot mypool@backup1\n" "# zfs list -t snapshot\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool@backup1 0 - 43.6M -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2918 msgid "" "Now that a snapshot exists, use `zfs send` to create a stream representing " "the contents of the snapshot. Store this stream as a file or receive it on " "another pool. Write the stream to standard output, but redirect to a file " "or pipe or an error appears:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2924 #, no-wrap msgid "" "# zfs send mypool@backup1\n" "Error: Stream can not be written to a terminal.\n" "You must redirect standard output.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2928 msgid "" "To back up a dataset with `zfs send`, redirect to a file located on the " "mounted backup pool. Ensure that the pool has enough free space to " "accommodate the size of the sent snapshot, which means the data contained in " "the snapshot, not the changes from the previous snapshot." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2936 #, no-wrap msgid "" "# zfs send mypool@backup1 > /backup/backup1\n" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "backup 960M 63.7M 896M - - 0% 6% 1.00x ONLINE -\n" "mypool 984M 43.7M 940M - - 0% 4% 1.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2940 msgid "" "The `zfs send` transferred all the data in the snapshot called _backup1_ to " "the pool named _backup_. To create and send these snapshots automatically, " "use a man:cron[8] job." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2946 msgid "" "Instead of storing the backups as archive files, ZFS can receive them as a " "live file system, allowing direct access to the backed up data. To get to " "the actual data contained in those streams, use `zfs receive` to transform " "the streams back into files and directories. The example below combines " "`zfs send` and `zfs receive` using a pipe to copy the data from one pool to " "another. Use the data directly on the receiving pool after the transfer is " "complete. It is only possible to replicate a dataset to an empty dataset." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2956 #, no-wrap msgid "" "# zfs snapshot mypool@replica1\n" "# zfs send -v mypool@replica1 | zfs receive backup/mypool\n" "full send of mypool@replica1 estimated size is 50.1M\n" "total estimated size is 50.1M\n" "TIME SENT SNAPSHOT mypool@replica1\n" "10:22:01 9.75M mypool@replica1\n" "10:22:02 25.4M mypool@replica1\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2961 #, no-wrap msgid "" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "backup 960M 63.7M 896M - - 0% 6% 1.00x ONLINE -\n" "mypool 984M 43.7M 940M - - 0% 4% 1.00x ONLINE -\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:2964 #, no-wrap msgid "Incremental Backups" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2969 msgid "" "`zfs send` can also determine the difference between two snapshots and send " "individual differences between the two. This saves disk space and transfer " "time. For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2981 #, no-wrap msgid "" "# zfs snapshot mypool@replica2\n" "# zfs list -t snapshot\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "mypool@replica1 5.72M - 43.6M -\n" "mypool@replica2 0 - 44.1M -\n" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "backup 960M 61.7M 898M - - 0% 6% 1.00x ONLINE -\n" "mypool 960M 50.2M 910M - - 0% 5% 1.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:2987 msgid "" "Create a second snapshot called _replica2_. This second snapshot contains " "changes made to the file system between now and the previous snapshot, " "_replica1_. Using `zfs send -i` and indicating the pair of snapshots " "generates an incremental replica stream containing the changed data. This " "succeeds if the initial snapshot already exists on the receiving side." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2994 #, no-wrap msgid "" "# zfs send -v -i mypool@replica1 mypool@replica2 | zfs receive backup/mypool\n" "send from @replica1 to mypool@replica2 estimated size is 5.02M\n" "total estimated size is 5.02M\n" "TIME SENT SNAPSHOT mypool@replica2\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:2999 #, no-wrap msgid "" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "backup 960M 80.8M 879M - - 0% 8% 1.00x ONLINE -\n" "mypool 960M 50.2M 910M - - 0% 5% 1.00x ONLINE -\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3005 #, no-wrap msgid "" "# zfs list\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "backup 55.4M 240G 152K /backup\n" "backup/mypool 55.3M 240G 55.2M /backup/mypool\n" "mypool 55.6M 11.6G 55.0M /mypool\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3012 #, no-wrap msgid "" "# zfs list -t snapshot\n" "NAME USED AVAIL REFER MOUNTPOINT\n" "backup/mypool@replica1 104K - 50.2M -\n" "backup/mypool@replica2 0 - 55.2M -\n" "mypool@replica1 29.9K - 50.0M -\n" "mypool@replica2 0 - 55.0M -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3017 msgid "" "The incremental stream replicated the changed data rather than the entirety " "of _replica1_. Sending the differences alone took much less time to " "transfer and saved disk space by not copying the whole pool each time. This " "is useful when replicating over a slow network or one charging per " "transferred byte." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3023 msgid "" "A new file system, _backup/mypool_, is available with the files and data " "from the pool _mypool_. Specifying `-p` copies the dataset properties " "including compression settings, quotas, and mount points. Specifying `-R` " "copies all child datasets of the dataset along with their properties. " "Automate sending and receiving to create regular backups on the second " "pool. The crossref:zfs[zfs-send-options,Send Stream Options] section " "describes these and other useful options in more detail." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:3025 #, no-wrap msgid "Send Stream Options" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3032 msgid "" "`zfs send` provides options that control what a stream includes and how " "compact it is. Specifying `-p` includes the dataset properties, such as " "compression settings, quotas, and mount points, in the stream. Specifying `-" "R` generates a replication stream package, which includes the dataset, all " "child datasets, snapshots, clones, and properties up to the named snapshot, " "and implies `-p`. The example in crossref:zfs[zfs-send-ssh,Sending " "Encrypted Backups over SSH] uses `-R` to replicate a complete dataset tree. " "Specifying `-v` prints information about the generated stream, including a " "per-second progress report." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3034 msgid "Other options change the format of the data blocks in the stream:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3036 msgid "" "`-L` permits blocks larger than 128 KB in the stream, preserving the on-disk " "block size of datasets with a `recordsize` above 128 KB instead of splitting " "those blocks." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3037 msgid "" "`-e` generates a more compact stream by using `WRITE_EMBEDDED` records for " "tiny blocks that the `embedded_data` pool feature stores directly in the " "block pointer." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3038 msgid "" "`-c` sends blocks that are compressed on disk in their compressed form " "rather than decompressing them first, saving CPU time on both systems and " "reducing the amount of data transferred for compressed datasets." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3039 msgid "" "`-w` sends an encrypted dataset in raw form, exactly as stored on disk and " "without loading its encryption key, as described in crossref:zfs[zfs-" "encrypted-send,Sending Encrypted Datasets]. For unencrypted datasets, `-w` " "is equivalent to `-Lec`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3043 msgid "" "Combining these options as `zfs send -Lec` is a good default on modern " "pools. The receiving pool must support every feature the stream uses, and " "`zfs receive` rejects a stream that requires a feature the pool lacks. See " "man:zfs-send[8] and man:zpool-features[7] for the full list of options and " "the pool features they depend on." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:3045 #, no-wrap msgid "Resumable Transfers" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3049 msgid "" "A dropped network connection or a reboot during a large transfer normally " "means starting over from the beginning. Using `zfs receive -s` keeps the " "partially received state on the receiving dataset instead of deleting it " "when the stream ends prematurely." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3058 #, no-wrap msgid "" "# zfs send -v mypool@replica1 | zfs receive -s backup/mypool\n" "full send of mypool@replica1 estimated size is 50.1M\n" "total estimated size is 50.1M\n" "TIME SENT SNAPSHOT mypool@replica1\n" "10:31:01 9.75M mypool@replica1\n" "^C\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3063 msgid "" "After the interruption, the receiving dataset stores an opaque resume token " "in its `receive_resume_token` property. The token records which snapshot " "the interrupted stream contained and how much of it arrived. Passing the " "token to `zfs send -t` generates a new stream that continues where the " "transfer stopped:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3069 #, no-wrap msgid "" "# zfs get -H -o value receive_resume_token backup/mypool\n" "1-1211c4f4a-f8-789c636064000310a501c49c50360710a715e5e7a69766a63040c1eabb735735ce8f8d5420c0e5c9e8d4d3d28a5388e4d3d200\n" "# zfs send -t $(zfs get -H -o value receive_resume_token backup/mypool) | zfs receive -s backup/mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3074 msgid "" "The resumed transfer completes normally and removes the saved partial " "state. Until resumed or aborted, the partial state consumes space on the " "receiving pool and blocks other receives into the same dataset. To abandon " "an interrupted transfer instead of resuming it, use `zfs receive -A` to " "delete the saved partial state:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3078 #, no-wrap msgid "# zfs receive -A backup/mypool\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:3081 #, no-wrap msgid "Sending Encrypted Backups over SSH" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3089 msgid "" "Sending streams over the network is a good way to keep a remote backup, but " "it does come with a drawback. Data sent over the network link is not " "encrypted, allowing anyone to intercept and transform the streams back into " "data without the knowledge of the sending user. This is undesirable when " "sending the streams over the internet to a remote host. Use SSH to securely " "encrypt data sent over a network connection. Since ZFS requires redirecting " "the stream from standard output, piping it through SSH is easy. To keep the " "contents of the file system encrypted on the remote system as well, use " "crossref:zfs[zfs-native-encryption,native encryption] and send the dataset " "as a raw stream, as described in crossref:zfs[zfs-encrypted-send,Sending " "Encrypted Datasets]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3092 msgid "" "Change some settings and take security precautions first. This describes " "the necessary steps required for the `zfs send` operation; for more " "information on SSH, see crossref:security[openssh,\"OpenSSH\"]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3094 msgid "Change the configuration as follows:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3096 msgid "" "Passwordless SSH access between sending and receiving host using SSH keys" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3097 msgid "" "ZFS requires the privileges of the `root` user to send and receive streams. " "This requires logging in to the receiving system as `root`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3098 msgid "Security reasons prevent `root` from logging in by default." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3100 msgid "" "Use the crossref:zfs[zfs-zfs-allow,ZFS Delegation] system to allow a non-" "`root` user on each system to perform the respective send and receive " "operations. On the sending system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3104 #, no-wrap msgid "# zfs allow -u someuser send,snapshot mypool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3107 msgid "" "To mount the pool, the unprivileged user must own the directory, and regular " "users need permission to mount file systems." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3109 msgid "On the receiving system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3118 #, no-wrap msgid "" "# sysctl vfs.usermount=1\n" "vfs.usermount: 0 -> 1\n" "# echo vfs.usermount=1 >> /etc/sysctl.conf\n" "# zfs create recvpool/backup\n" "# zfs allow -u someuser create,mount,receive recvpool/backup\n" "# chown someuser /recvpool/backup\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3121 msgid "" "The unprivileged user can receive and mount datasets now, and replicates the " "_home_ dataset to the remote system:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3126 #, no-wrap msgid "" "% zfs snapshot -r mypool/home@monday\n" "% zfs send -R mypool/home@monday | ssh someuser@backuphost zfs recv -dvu recvpool/backup\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3136 msgid "" "Create a recursive snapshot called _monday_ of the file system dataset " "_home_ on the pool _mypool_. Then `zfs send -R` includes the dataset, all " "child datasets, snapshots, clones, and settings in the stream. Pipe the " "output through SSH to the waiting `zfs receive` on the remote host " "_backuphost_. Using an IP address or fully qualified domain name is good " "practice. The receiving machine writes the data to the _backup_ dataset on " "the _recvpool_ pool. Adding `-d` to `zfs recv` discards the first element " "of the sent snapshot's path, usually the pool name, and grafts the remaining " "path onto the receiving dataset, creating any required intermediate file " "systems. `-u` causes the file systems to not mount on the receiving side. " "Using `-v` shows more details about the transfer, including the elapsed time " "and the amount of data transferred." msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:3138 #, no-wrap msgid "Corrective Receive" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3143 msgid "" "A scrub detects corrupted data, but on a pool without enough redundancy it " "cannot repair the damage and reports permanent errors instead. When an " "intact copy of the affected snapshot exists on another pool, a corrective " "receive with `zfs receive -c` heals the damaged blocks in place, using the " "send stream as a source of healthy data. The dataset stays where it is, " "without any rollback or rename." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3147 msgid "Corrective receive requires OpenZFS 2.2, first shipped in FreeBSD 14.0." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3150 msgid "" "In this example, a scrub of the single-disk pool _mypool_ found " "unrecoverable damage:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3163 #, no-wrap msgid "" "# zpool status -v mypool\n" " pool: mypool\n" " state: ONLINE\n" "status: One or more devices has experienced an error resulting in data\n" " corruption. Applications may be affected.\n" "action: Restore the file in question if possible. Otherwise restore the\n" " entire pool from backup.\n" " see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-8A\n" " scan: scrub repaired 0B in 00:01:22 with 1 errors on Sat Jul 11 09:14:37 2026\n" "config:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3167 #, no-wrap msgid "" " NAME STATE READ WRITE CKSUM\n" " mypool ONLINE 0 0 0\n" " ada0 ONLINE 0 0 2\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3169 #, no-wrap msgid "errors: Permanent errors have been detected in the following files:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3171 #, no-wrap msgid " /mypool/reports/summary-2026.db\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3175 msgid "" "The snapshot _replica2_ still references the damaged blocks, and the " "_backup_ pool holds an intact copy of that snapshot. Send the snapshot from " "the backup pool and receive it correctively into the matching snapshot on " "the damaged pool, then scrub to confirm the repair:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3182 #, no-wrap msgid "" "# zfs send backup/mypool@replica2 | zfs receive -c mypool@replica2\n" "# zpool scrub -w mypool\n" "# zpool status mypool | grep errors:\n" "errors: No known data errors\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3187 msgid "" "The stream must contain the same snapshot that exists on the damaged " "dataset. Corrective receive heals only the data blocks present in the " "stream; it cannot repair metadata or data written after the snapshot was " "taken. Always run a crossref:zfs[zfs-zpool-scrub,scrub] afterwards to " "verify that the pool no longer contains damaged data." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3189 #, no-wrap msgid "Dataset, User, and Group Quotas" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3195 msgid "" "Use crossref:zfs[zfs-term-quota,Dataset quotas] to restrict the amount of " "space consumed by a particular dataset. crossref:zfs[zfs-term-" "refquota,Reference Quotas] work in much the same way, but count the space " "used by the dataset itself, excluding snapshots and child datasets. " "Similarly, use crossref:zfs[zfs-term-userquota,user] and crossref:zfs[zfs-" "term-groupquota,group] quotas to prevent users or groups from using up all " "the space in the pool or dataset. Project quotas, described below, restrict " "the space consumed by an arbitrary directory tree instead." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3200 msgid "" "The following examples assume that the users already exist in the system. " "Before adding a user to the system, make sure to create their home dataset " "first and set the `mountpoint` to `/home/_bob_`. Then, create the user and " "make the home directory point to the dataset's `mountpoint` location. This " "will properly set owner and group permissions without shadowing any pre-" "existing home directory paths that might exist." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3202 msgid "To enforce a dataset quota of 10 GB for [.filename]#storage/home/bob#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3206 #, no-wrap msgid "# zfs set quota=10G storage/home/bob\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3209 msgid "" "To enforce a reference quota of 10 GB for [.filename]#storage/home/bob#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3213 #, no-wrap msgid "# zfs set refquota=10G storage/home/bob\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3216 msgid "To remove a quota of 10 GB for [.filename]#storage/home/bob#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3220 #, no-wrap msgid "# zfs set quota=none storage/home/bob\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3223 msgid "" "The general format is `userquota@_user_=_size_`, and the user's name must be " "in one of these formats:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3225 msgid "POSIX compatible name such as _joe_." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3226 msgid "POSIX numeric ID such as _789_." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3227 msgid "SID name such as _joe.bloggs@example.com_." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3228 msgid "SID numeric ID such as _S-1-123-456-789_." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3230 msgid "For example, to enforce a user quota of 50 GB for the user named _joe_:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3234 #, no-wrap msgid "# zfs set userquota@joe=50G storage/home/joe\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3237 msgid "To remove any quota:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3241 #, no-wrap msgid "# zfs set userquota@joe=none storage/home/joe\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3248 msgid "" "User quota properties are not displayed by `zfs get all`. Non-`root` users " "can't see other's quotas unless granted the `userquota` privilege. Users " "with this privilege are able to view and set everyone's quota." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3251 msgid "" "The general format for setting a group quota is: `groupquota@_group_=_size_`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3253 msgid "To set the quota for the group _firstgroup_ to 50 GB, use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3257 #, no-wrap msgid "# zfs set groupquota@firstgroup=50G storage/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3260 msgid "" "To remove the quota for the group _firstgroup_, or to make sure that one is " "not set, instead use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3264 #, no-wrap msgid "# zfs set groupquota@firstgroup=none storage/home\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3268 msgid "" "As with the user quota property, non-`root` users can see the quotas " "associated with the groups to which they belong. A user with the " "`groupquota` privilege or `root` can view and set all quotas for all groups." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3272 msgid "" "To display the amount of space used by each user on a file system or " "snapshot along with any quotas, use `zfs userspace`. For group information, " "use `zfs groupspace`. For more information about supported options or how " "to display specific options alone, refer to man:zfs-userspace[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3274 msgid "" "Privileged users and `root` can list the quota for [.filename]#storage/home/" "bob# using:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3278 #, no-wrap msgid "# zfs get quota storage/home/bob\n" msgstr "" #. type: Title ==== #: documentation/content/en/books/handbook/zfs/_index.adoc:3281 #, no-wrap msgid "Project Quotas" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3286 msgid "" "Dataset and user quotas do not fit every layout. When several directory " "trees belonging to different projects share a single dataset, project quotas " "restrict the space consumed by each tree instead. A project is an arbitrary " "numeric identifier tagged onto files and directories." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3290 msgid "" "`zfs project` manages the project ID of files and directories. Setting the " "project inherit flag on a directory makes new files and subdirectories " "created inside it inherit its project ID. To assign project ID _42_ to an " "existing tree, set the flag and the ID recursively:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3294 #, no-wrap msgid "# zfs project -s -p 42 -r /storage/proj\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3297 msgid "" "Enforce a limit of 100 GB on all files belonging to project _42_ with the " "`projectquota` property:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3301 #, no-wrap msgid "# zfs set projectquota@42=100G storage\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3304 msgid "" "`zfs projectspace` displays the space consumed by each project on a dataset " "along with any quotas:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3310 #, no-wrap msgid "" "# zfs projectspace -o name,used,quota storage\n" "NAME USED QUOTA\n" "42 1.95G 100G\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3315 msgid "" "The `projectobjquota` property limits the number of objects a project may " "own in the same way. Display or clear the project ID of a directory with " "`zfs project -d` and `zfs project -C`. Refer to man:zfs-project[8] and " "man:zfsprops[7] for details." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3317 #, no-wrap msgid "Reservations" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3322 msgid "" "crossref:zfs[zfs-term-reservation,Reservations] guarantee an always-" "available amount of space on a dataset. The reserved space will not be " "available to any other dataset. This useful feature ensures that free space " "is available for an important dataset or log files." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3324 msgid "" "The general format of the `reservation` property is `reservation=_size_`, so " "to set a reservation of 10 GB on [.filename]#storage/home/bob#, use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3328 #, no-wrap msgid "# zfs set reservation=10G storage/home/bob\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3331 msgid "To clear any reservation:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3335 #, no-wrap msgid "# zfs set reservation=none storage/home/bob\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3338 msgid "" "The same principle applies to the `refreservation` property for setting a " "crossref:zfs[zfs-term-refreservation,Reference Reservation], with the " "general format `refreservation=_size_`." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3340 msgid "" "This command shows any reservations or refreservations that exist on " "[.filename]#storage/home/bob#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3345 #, no-wrap msgid "" "# zfs get reservation storage/home/bob\n" "# zfs get refreservation storage/home/bob\n" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3348 #, no-wrap msgid "Compression" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3354 msgid "" "ZFS provides transparent compression. Compressing data written at the block " "level saves space and also increases disk throughput. If data compresses by " "25% the compressed data writes to the disk at the same rate as the " "uncompressed version, resulting in an effective write speed of 125%. " "Compression can also be a great alternative to crossref:zfs[zfs-zfs-" "deduplication,Deduplication] because it does not require extra memory." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3362 msgid "" "ZFS offers different compression algorithms, each with different trade-" "offs. On OpenZFS 2.2 and later, newly created pools and datasets default to " "`compression=on`, which selects LZ4. LZ4 compresses the entire pool without " "the large performance trade-off of other algorithms. The biggest advantage " "to LZ4 is the _early abort_ feature. If LZ4 does not achieve at least 12.5% " "compression in the header part of the data, ZFS writes the block " "uncompressed to avoid wasting CPU cycles trying to compress data that is " "either already compressed or uncompressible. Changing the `compression` " "property affects new writes only; existing data keeps its old encoding until " "rewritten (see crossref:zfs[zfs-zfs-rewrite,Rewriting Existing Data]). For " "details about the different compression algorithms available in ZFS, see the " "crossref:zfs[zfs-term-compression,Compression] entry in the terminology " "section." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3364 msgid "" "The administrator can see the effectiveness of compression using dataset " "properties." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3373 #, no-wrap msgid "" "# zfs get used,compressratio,compression,logicalused mypool/compressed_dataset\n" "NAME PROPERTY VALUE SOURCE\n" "mypool/compressed_dataset used 449G -\n" "mypool/compressed_dataset compressratio 1.11x -\n" "mypool/compressed_dataset compression lz4 local\n" "mypool/compressed_dataset logicalused 496G -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3378 msgid "" "The dataset is using 449 GB of space (the used property). Without " "compression, it would have taken 496 GB of space (the `logicalused` " "property). This results in a 1.11:1 compression ratio." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3384 msgid "" "Compression can have an unexpected side effect when combined with " "crossref:zfs[zfs-term-userquota,User Quotas]. User quotas restrict how much " "actual space a user consumes on a dataset _after compression_. If a user " "has a quota of 10 GB, and writes 10 GB of compressible data, they will still " "be able to store more data. If they later update a file, say a database, " "with more or less compressible data, the amount of space available to them " "will change. This can result in the odd situation where a user did not " "increase the actual amount of data (the `logicalused` property), but the " "change in compression caused them to reach their quota limit." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3388 msgid "" "Compression can have a similar unexpected interaction with backups. Quotas " "are often used to limit data storage to ensure there is enough backup space " "available. Since quotas do not consider compression ZFS may write more data " "than would fit with uncompressed backups." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3390 #, no-wrap msgid "Zstandard Compression" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3394 msgid "" "OpenZFS 2.0 added the Zstandard (Zstd) compression algorithm. Zstd offers " "higher compression ratios than the default LZ4 while offering much greater " "speeds than the alternative, gzip." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3398 msgid "" "Zstd provides a large selection of compression levels, providing fine-" "grained control over performance versus compression ratio. One of the main " "advantages of Zstd is that the decompression speed is independent of the " "compression level. For data written once but read often, Zstd allows the " "use of the highest compression levels without a read performance penalty." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3403 msgid "" "Even with frequent data updates, enabling compression often provides higher " "performance. One of the biggest advantages comes from the compressed ARC " "feature. ZFS's Adaptive Replacement Cache (ARC) caches the compressed " "version of the data in RAM, decompressing it each time. This allows the " "same amount of RAM to store more data and metadata, increasing the cache hit " "ratio." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3409 msgid "" "ZFS offers 19 levels of Zstd compression, each offering incrementally more " "space savings in exchange for slower compression. The default level is " "`zstd-3` and offers greater compression than LZ4 without being much slower. " "Levels above 10 require large amounts of memory to compress each block and " "systems with less than 16 GB of RAM should not use them. ZFS uses a " "selection of the Zstd _fast_ levels also, which get correspondingly faster " "but support lower compression ratios. ZFS supports `zstd-fast-1` through " "`zstd-fast-10`, `zstd-fast-20` through `zstd-fast-100` in increments of 10, " "and `zstd-fast-500` and `zstd-fast-1000` which provide minimal compression, " "but offer high performance." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3413 msgid "" "If ZFS is not able to get the required memory to compress a block with Zstd, " "it will fall back to storing the block uncompressed. This is unlikely to " "happen except at the highest levels of Zstd on memory constrained systems. " "ZFS counts how often this has occurred since loading the ZFS module with " "`kstat.zfs.misc.zstd.compress_alloc_fail`." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3415 #, no-wrap msgid "Rewriting Existing Data" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3420 msgid "`zfs rewrite` requires OpenZFS 2.4, first shipped in FreeBSD 15.0." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3425 msgid "" "Properties like `compression`, `checksum`, `dedup`, and `copies` affect " "newly written data only. Changing them leaves existing blocks stored as " "they were, and applying the new values traditionally required a send/receive " "cycle or copying every file back and forth. `zfs rewrite` instead rewrites " "the blocks of existing files in place, as if they were atomically read and " "written back, so the current property values take effect without those " "workarounds." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3428 msgid "" "The command operates on files and directories rather than dataset names. To " "apply a newly chosen compression algorithm to a whole dataset, recurse from " "its mount point:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3433 #, no-wrap msgid "" "# zfs set compression=zstd mypool/archive\n" "# zfs rewrite -r /mypool/archive\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3438 msgid "" "Adding `-v` prints the name of every rewritten file. `-x` keeps the " "recursion from crossing mount points into child datasets, and `-o` and `-l` " "restrict the rewrite to a byte range within a file. Property changes that " "would alter the logical block size, such as `recordsize`, have no effect on " "rewritten files." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3442 msgid "" "Rewritten blocks are new blocks: snapshots taken before the rewrite keep " "referencing the old copies, so space usage can grow until those snapshots " "are destroyed. `zfs rewrite` does not work through snapshots for the same " "reason. Refer to man:zfs-rewrite[8] for details." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3444 #, no-wrap msgid "Deduplication" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3450 msgid "" "When enabled, crossref:zfs[zfs-term-deduplication,deduplication] uses the " "checksum of each block to detect duplicate blocks. When a new block is a " "duplicate of an existing block, ZFS writes a new reference to the existing " "data instead of the whole duplicate block. Tremendous space savings are " "possible if the data contains a lot of duplicated files or repeated " "information. Warning: deduplication requires a large amount of memory, and " "enabling compression instead provides most of the space savings without the " "extra cost." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3453 msgid "" "`dedup` is a dataset property, not a pool property. To activate " "deduplication, set it on a dataset:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3457 #, no-wrap msgid "# zfs set dedup=on pool\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3461 msgid "" "This example sets the property on the root dataset of the pool _pool_, so " "every dataset in the pool inherits it. Limiting deduplication to the " "datasets that actually store duplicate-heavy data keeps the deduplication " "table smaller." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3466 msgid "" "Deduplicating only affects new data written to the dataset. Merely " "activating this option will not deduplicate data already written. On " "FreeBSD 15.0, crossref:zfs[zfs-zfs-rewrite,`zfs rewrite`] can rewrite " "existing data so that it passes through deduplication. A pool with a " "freshly activated deduplication property will look like this example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3472 #, no-wrap msgid "" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "pool 2.84G 2.19M 2.83G - - 0% 0% 1.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3477 msgid "" "The `DEDUP` column shows the actual rate of deduplication for the pool. A " "value of `1.00x` shows that data has not deduplicated yet. The next example " "copies some system binaries three times into different directories on the " "deduplicated pool created above." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3483 #, no-wrap msgid "" "# for d in dir1 dir2 dir3; do\n" "> mkdir $d && cp -R /usr/bin $d &\n" "> done\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3486 msgid "To observe deduplicating of redundant data, use:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3492 #, no-wrap msgid "" "# zpool list\n" "NAME SIZE ALLOC FREE CKPOINT EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT\n" "pool 2.84G 20.9M 2.82G - - 0% 0% 3.00x ONLINE -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3500 msgid "" "The `DEDUP` column shows a factor of `3.00x`. Detecting and deduplicating " "copies of the data uses a third of the space. The potential for space " "savings can be enormous, but comes at the cost of having enough memory to " "keep track of the deduplicated blocks. ZFS stores an entry for every " "deduplicated block in the deduplication table (crossref:zfs[zfs-term-" "deduplication,DDT]). A general rule of thumb is 5-6 GB of RAM per 1 TB of " "deduplicated data. When the table no longer fits in memory, every write " "forces reads of table entries from disk, and performance degrades " "drastically." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3503 msgid "" "Deduplication is not always beneficial when the data in a pool is not " "redundant. ZFS can show potential space savings by simulating deduplication " "on an existing pool:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3508 #, no-wrap msgid "" "# zdb -S pool\n" "Simulated DDT histogram:\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3524 #, no-wrap msgid "" "bucket allocated referenced\n" "______ ______________________________ ______________________________\n" "refcnt blocks LSIZE PSIZE DSIZE blocks LSIZE PSIZE DSIZE\n" "------ ------ ----- ----- ----- ------ ----- ----- -----\n" " 1 2.58M 289G 264G 264G 2.58M 289G 264G 264G\n" " 2 206K 12.6G 10.4G 10.4G 430K 26.4G 21.6G 21.6G\n" " 4 37.6K 692M 276M 276M 170K 3.04G 1.26G 1.26G\n" " 8 2.18K 45.2M 19.4M 19.4M 20.0K 425M 176M 176M\n" " 16 174 2.83M 1.20M 1.20M 3.33K 48.4M 20.4M 20.4M\n" " 32 40 2.17M 222K 222K 1.70K 97.2M 9.91M 9.91M\n" " 64 9 56K 10.5K 10.5K 865 4.96M 948K 948K\n" " 128 2 9.50K 2K 2K 419 2.11M 438K 438K\n" " 256 5 61.5K 12K 12K 1.90K 23.0M 4.47M 4.47M\n" " 1K 2 1K 1K 1K 2.98K 1.49M 1.49M 1.49M\n" " Total 2.82M 303G 275G 275G 3.20M 319G 287G 287G\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3526 #, no-wrap msgid "dedup = 1.05, compress = 1.11, copies = 1.00, dedup * compress / copies = 1.16\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3533 msgid "" "After `zdb -S` finishes analyzing the pool, it shows the space reduction " "ratio that activating deduplication would achieve. In this case, `1.16` is " "a poor space saving ratio mainly provided by compression. Activating " "deduplication on this pool would not save any amount of space, and is not " "worth the amount of memory required to enable deduplication. Using the " "formula _ratio = dedup * compress / copies_, system administrators can plan " "the storage allocation, deciding whether the workload will contain enough " "duplicate blocks to justify the memory requirements. If the data is " "reasonably compressible, the space savings may be good." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3541 msgid "" "Fast dedup, a reworked implementation that lowers these costs, requires " "OpenZFS 2.3 or later, first available in FreeBSD 15.0. Fast dedup batches " "deduplication table updates in an on-disk log and flushes them to the table " "in the background, reducing the random I/O that made classic deduplication " "slow. The `dedup_table_quota` pool property sets a limit on the on-disk " "size of the table; ZFS stops adding new entries once the pool reaches the " "limit, and with the default value of `auto` the size of a dedicated dedup " "vdev serves as the quota. The read-only `dedup_table_size` pool property " "reports the current size of the table. `zpool ddtprune -p 30 pool` removes " "the oldest 30% of the table entries that provide no savings because only a " "single block references them; `-d _days_` instead prunes single-reference " "entries older than the given number of days. `zpool status -DD pool` " "displays deduplication table statistics, including a histogram of blocks by " "reference count. Storing the table on a dedicated crossref:zfs[zfs-zpool-" "special,dedup vdev] made of fast devices keeps lookups quick even when the " "table outgrows RAM." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3544 msgid "" "Good practice is to enable compression first as compression also provides " "greatly increased performance. Enable deduplication in cases where savings " "are considerable and with enough available memory for the crossref:zfs[zfs-" "term-deduplication,DDT]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3546 #, no-wrap msgid "ZFS and Jails" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3552 msgid "" "Use `zfs jail` and the corresponding `jailed` property to delegate a ZFS " "dataset to a crossref:jails[jails,Jail]. `zfs jail _jailid_` attaches a " "dataset to the specified jail, and `zfs unjail` detaches it. To control the " "dataset from within a jail, set the `jailed` property. ZFS forbids mounting " "a jailed dataset on the host because it may have mount points that would " "compromise the security of the host." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3556 msgid "" "A delegated dataset hands control of a whole subtree to the jail " "administrator, who can mount it, create child datasets, take snapshots, and " "change properties, all confined to that subtree. For this to work, the jail " "needs the `allow.mount` and `allow.mount.zfs` parameters enabled and the " "`enforce_statfs` parameter set to a value lower than 2. Refer to " "man:jail[8] for details on these parameters." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3558 msgid "" "This example creates a dataset, marks it as jailed, and attaches it to the " "running jail _myjail_:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3564 #, no-wrap msgid "" "# zfs create mypool/jaildata\n" "# zfs set jailed=on mypool/jaildata\n" "# zfs jail myjail mypool/jaildata\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3569 msgid "" "The dataset then appears in `zfs list` inside the jail and is manageable " "there. `zfs unjail myjail mypool/jaildata` returns control to the host. " "See man:zfs-jail[8] for more information." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3574 msgid "" "Starting with FreeBSD 15.0, man:jail[8] automates the attachment. List the " "datasets to delegate in the `zfs.dataset` jail parameter, and man:jail[8] " "attaches them when the jail starts. The datasets must already have " "`jailed=on` set, and the parameter requires `allow.mount.zfs`. An " "[.filename]#/etc/jail.conf# entry using it looks like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3587 #, no-wrap msgid "" "myjail {\n" " path = \"/usr/local/jails/myjail\";\n" " host.hostname = \"myjail.example.org\";\n" " exec.start = \"/bin/sh /etc/rc\";\n" " exec.stop = \"/bin/sh /etc/rc.shutdown\";\n" " allow.mount;\n" " allow.mount.zfs;\n" " enforce_statfs = 1;\n" " zfs.dataset = \"mypool/jaildata\";\n" "}\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3590 msgid "" "Setting the `zfs.mount_snapshot` jail parameter to 1 additionally lets users " "inside the jail access the contents of ZFS snapshots under the " "[.filename]#.zfs# directory of the delegated file systems." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:3592 #, no-wrap msgid "Delegated Administration" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3600 msgid "" "A comprehensive permission delegation system allows unprivileged users to " "perform ZFS administration functions. For example, if each user's home " "directory is a dataset, users need permission to create and destroy " "snapshots of their home directories. A user performing backups can get " "permission to use replication features. ZFS allows a usage statistics " "script to run with access to only the space usage data for all users. " "Delegating the ability to delegate permissions is also possible. Permission " "delegation is possible for each subcommand and most properties." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3602 #, no-wrap msgid "Delegating Dataset Creation" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3608 msgid "" "`zfs allow _someuser_ create _mydataset_` gives the specified user " "permission to create child datasets under the selected parent dataset. A " "caveat: creating a new dataset involves mounting it. That requires setting " "the FreeBSD `vfs.usermount` man:sysctl[8] to `1` to allow non-root users to " "mount a file system. Another restriction aimed at preventing abuse: non-" "`root` users must own the mountpoint where the file system is to be mounted." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3610 #, no-wrap msgid "Delegating Permission Delegation" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3614 msgid "" "`zfs allow _someuser_ allow _mydataset_` gives the specified user the " "ability to assign any permission they have on the target dataset, or its " "children, to other users. If a user has the `snapshot` permission and the " "`allow` permission, that user can then grant the `snapshot` permission to " "other users." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:3616 #, no-wrap msgid "ZFS Native Encryption" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3622 msgid "" "ZFS supports native encryption of datasets and the data stored within them. " "This was not always the case, as previous solutions relied on FreeBSD's GELI-" "based encryption. While this approach is secure, it was not as easily " "portable to non-FreeBSD systems that lacked GELI support. With ZFS native " "encryption, encrypted datasets can be used on other systems that support " "this pool feature without relying on third-party components or operating " "system-native encryption." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3625 msgid "" "Another benefit of ZFS native encryption is that datasets do not need to be " "decrypted for administrative tasks such as snapshots, replication, or scrub " "operations. ZFS data integrity checks work just as well with natively " "encrypted datasets, and compression also works on encrypted datasets." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3632 msgid "" "Different datasets on the same pool can use separate keys independently. " "Consider a central file server where different users store their data in " "encrypted home datasets. User A has a different key than User B. Both " "users can work side by side and choose to unencrypt their datasets as needed " "without knowing each other's decryption keys. The decryption method can " "also differ completely between users without affecting one another. This " "allows sensitive data from different users to be stored on the same pool " "while remaining protected by separate keys." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3634 msgid "Before using ZFS native encryption, be aware of the following:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3636 msgid "Encryption is applied at the dataset level, not the pool level." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3637 msgid "" "Booting from encrypted ZFS datasets is not yet supported in FreeBSD's loader." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3638 msgid "" "Encryption can only be enabled when a dataset is created, not afterward." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3639 msgid "" "The block cipher, key length, and encryption mode cannot be changed after " "they have been set." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3640 msgid "ZFS does not encrypt metadata." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3644 msgid "" "The last point may seem like a drawback compared to full-disk encryption. " "However, it provides greater flexibility by allowing different keys to " "protect datasets within the same pool instead of requiring a single key or " "passphrase to unlock the entire pool. Specifically, ZFS encrypts the " "following:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3646 msgid "file and zvol data," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3647 msgid "file attributes," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3648 msgid "ACLs," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3649 msgid "permission bits," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3650 msgid "directory listings," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3651 msgid "FUID mappings," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3652 msgid "userused/groupused data, and" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3653 msgid "deduplicated data" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3655 msgid "" "Some ZFS metadata and information remains unencrypted, including the " "following:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3657 msgid "pool structure and name," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3658 msgid "dataset and snapshot names," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3659 msgid "dataset hierarchy," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3660 msgid "properties," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3661 msgid "file size," msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3662 msgid "file holes, and" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3663 msgid "deduplication tables" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3666 msgid "" "This unencrypted metadata allows ZFS to perform routine maintenance " "operations, such as `zpool scrub`, without first decrypting the data. As a " "result, ZFS can detect and repair corrupted encrypted data without accessing " "the unencrypted file contents." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3673 msgid "" "To encrypt existing unencrypted data, copy it to a dataset with encryption " "enabled. This allows data to be migrated to a secure location within the " "pool, provided the passphrase is supplied to authorize access. Typically, " "this is done by loading the encryption key into memory after confirming " "knowledge of a secret such as a passphrase. Once the key has been loaded, " "the dataset contents become accessible for reading and writing. To re-" "secure the dataset, unload the key from memory. ZFS then makes the dataset " "inaccessible until the key is loaded again." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3678 msgid "" "When encryption is enabled, some ZFS operations behave differently. ZFS " "applies compression before encryption to preserve compression ratios. While " "ZFS normally uses 256-bit checksums, encryption replaces them with a 128-bit " "checksum and a 128-bit Message Authentication Code (MAC) provided by the " "encryption suite. This provides additional protection against malicious " "data modification." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3683 msgid "" "When deduplication is used together with encryption, ZFS performs " "deduplication only within the encrypted dataset, its snapshots, and its " "clones. This prevents information from leaking between encrypted datasets. " "The tradeoff is lower deduplication efficiency because ZFS cannot compare " "checksums across the entire pool. Even so, deduplication combined with " "encryption still reveals which blocks are identical and incurs additional " "CPU overhead for each block written." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3687 msgid "" "Other limitations apply when using ZFS encryption. The `embedded_data` " "feature cannot be used with encryption. Datasets with encryption enabled " "also cannot have the `copies` property set to 3, because the implementation " "stores encrypted metadata in the location where the third copy would " "normally reside." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3689 #, no-wrap msgid "Creating an Encrypted Dataset" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3694 msgid "" "ZFS encryption is enabled by setting the `encryption=on` property when " "creating a dataset. Setting this property outside of a `zfs create` command " "does not enable encryption retroactively, as it only takes effect during " "dataset creation. In the following example, a passphrase is used when " "mounting the encrypted dataset after it has been created." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3700 #, no-wrap msgid "" "# zfs create -o encryption=on -o keyformat=passphrase -o keylocation=prompt zroot/secretdata\n" "Enter passphrase:\n" "Re-enter passphrase:\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3704 msgid "" "If the passphrase is shorter than eight characters, ZFS rejects it and does " "not create the dataset. After the passphrase has been entered correctly " "twice, ZFS creates and mounts the dataset in the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3708 msgid "" "Any data stored in the encrypted dataset remains encrypted while it resides " "there. Copying data from an encrypted dataset to an unencrypted location " "decrypts the data during the copy operation. The newly created dataset can " "then be mounted at a different location if necessary." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3715 #, no-wrap msgid "" "# zfs set mountpoint=/secretdata zroot/secretdata\n" "# echo \"Hello FreeBSD!\" > /secretdata/message\n" "# cat /secretdata/message\n" "Hello FreeBSD!\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3718 msgid "" "As expected, the data is currently available for reading and writing by " "anyone who has access to the dataset." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3720 #, no-wrap msgid "Properties of Encrypted Datasets" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3723 msgid "" "Listing the ZFS native encryption properties for a dataset is done with the " "following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3731 #, no-wrap msgid "" "# zfs get encryption,keylocation,keyformat zroot/secretdata\n" "NAME PROPERTY VALUE SOURCE\n" "zroot/secretdata encryption aes-256-gcm -\n" "zroot/secretdata keylocation prompt local\n" "zroot/secretdata keyformat passphrase -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3737 msgid "" "The `encryption` property shows `aes-256-gcm`, which is currently the " "default encryption method used by ZFS. As indicated by the `SOURCE` column, " "neither this property nor the `keyformat` property can be changed using `zfs " "set` after the dataset has been created. See the crossref:zfs[zfs-change-" "encryption-key,changing the encryption key] section for information on how " "to modify some of these properties. The following table lists the " "encryption-related properties used by ZFS:" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3743 #, no-wrap msgid "[[zfs-term-encryptionroot]]encryptionroot" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3746 #, no-wrap msgid "" "The dataset from which the current dataset inherits its encryption key.\n" "Dataset clones share the encryption key of their originating dataset." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3747 #, no-wrap msgid "[[zfs-term-keyformat]]keyformat" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3748 #, no-wrap msgid "The format of the encryption key. Possible values are: `raw`, `hex`, and `passphrase`. Both `raw` and `hex` keys must be 32 bytes long and contain random values." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3749 #, no-wrap msgid "[[zfs-term-encryption]]encryption" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3762 #, no-wrap msgid "" "The cipher used for encryption, consisting of the block cipher, key length, and encryption mode. Both the `encryption` and `keyformat` properties must be specified when the dataset is created. Possible values for the `encryption` property are:\n" "\n" " * `off` (default),\n" " * `on`,\n" " * `aes-128-ccm`,\n" " * `aes-192-ccm`,\n" " * `aes-256-ccm`,\n" " * `aes-128-gcm`,\n" " * `aes-192-gcm`, and\n" " * `aes-256-gcm` (current standard when `on` is set).\n" "\n" "This property cannot be changed once it has been set." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3763 #, no-wrap msgid "[[zfs-term-keystatus]]keystatus" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3765 #, no-wrap msgid "Indicates whether an encryption key has been successfully loaded. Possible values are `none`, `available`, and `unavailable`." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3766 #, no-wrap msgid "[[zfs-term-keylocation]]keylocation" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3773 #, no-wrap msgid "" "Specifies the location from which to load the encryption key. Possible values are:\n" "\n" "* `prompt`,\n" "* `file://path/to/file`,\n" "* `http://some.address`, and\n" "* `https://other.address`" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3774 #, no-wrap msgid "[[zfs-term-pbkdf2iters]]pbkdf2iters" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:3775 #, no-wrap msgid "The number of iterations used when deriving an encryption key from a passphrase. This forces an attacker to perform a large number of computationally expensive hash operations. As computing power increases, this value should also be increased from its current default of 350000." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3778 #, no-wrap msgid "Unloading the Encryption Key" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3786 msgid "" "Protecting the data stored in an encrypted dataset requires two steps: first " "unmount the dataset, then unload the encryption key from memory. This " "distinction is important. An unmounted dataset is not protected if its " "encryption key remains loaded in memory. Always run `zfs unload-key` to " "protect the data. To access the dataset again, load the key and provide the " "passphrase as described in the crossref:zfs[zfs-load-encryption-key,loading " "the encryption key] section. ZFS prevents `zfs unload-key` from running " "while the dataset is still mounted." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3791 #, no-wrap msgid "" "# zfs unmount zroot/secretdata\n" "# zfs unload-key zroot/secretdata\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3794 msgid "" "Running `zfs unload-key` multiple times results in an error indicating that " "the key has already been unloaded." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3796 #, no-wrap msgid "Loading the Encryption Key" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3800 msgid "" "Before an encrypted dataset can be used like any other dataset, its " "encryption key must be loaded and the passphrase provided. At this point, " "the `keystatus` property is still set to `unavailable`, and mounting the " "dataset fails because the key has not yet been loaded:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3808 #, no-wrap msgid "" "# zfs get keystatus zroot/secretdata\n" "NAME PROPERTY VALUE SOURCE\n" "zroot/secretdata keystatus unavailable -\n" "# zfs mount zroot/secretdata\n" "cannot mount 'zroot/secretdata': encryption key not loaded\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3812 msgid "" "This indicates that the dataset is encrypted and requires an encryption " "key. To mount the dataset, run `zfs load-key` and provide the passphrase " "when prompted:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3820 #, no-wrap msgid "" "# zfs load-key zroot/secretdata\n" "Enter passphrase for 'zroot/secretdata':\n" "# zfs get keystatus zroot/secretdata\n" "NAME PROPERTY VALUE SOURCE\n" "zroot/secretdata keystatus available -\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3823 msgid "" "Next, mount the dataset to make it accessible through the filesystem " "hierarchy:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3829 #, no-wrap msgid "" "# zfs mount zroot/secretdata\n" "# mount|grep secretdata\n" "zroot/secretdata on /secretdata (zfs, local, noatime, nfsv4acls)\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3833 msgid "" "To load multiple encryption keys recursively, specify the `-r` option with " "`zfs load-key`. If a key has already been loaded, ZFS reports this with an " "error message." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3838 #, no-wrap msgid "" "# zfs load-key zroot/secretdata\n" "Key load error: Key already loaded for 'zroot/secretdata'.\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3842 msgid "" "The `keystatus` property also confirms that the key has been loaded by " "reporting the value `available`. To verify whether a passphrase is correct " "without loading the key, use the `-n` option to perform a dry run." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3844 #, no-wrap msgid "Changing the Encryption Key" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3849 msgid "" "ZFS also supports changing encryption keys, such as replacing a passphrase. " "This operation does not require re-encrypting the dataset. Run the " "following command to change the encryption passphrase:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3855 #, no-wrap msgid "" "# zfs change-key zroot/secretdata\n" "Enter new passphrase for 'zroot/secretdata':\n" "Re-enter new passphrase for 'zroot/secretdata':\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3859 msgid "" "Running `zfs change-key` requires the current key to be loaded. If it is " "not, ZFS still prompts for the new key but then displays a warning that the " "current key has not been loaded." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3863 msgid "" "The `zfs change-key` command can also modify the `keylocation`, `keyformat`, " "and `pbkdf2iters` properties by specifying them with the `-o` option. " "Running `zfs change-key` on an encrypted child dataset makes it an " "encryption root if it is not one already. To prevent this behavior and " "continue inheriting the parent's key, specify the `-i` option." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3868 msgid "" "Be aware that changing the encryption key of a parent dataset also changes " "the key for child datasets that inherit it. Consequently, those child " "datasets continue to use the parent's encryption key. If a child dataset " "should use a different key, either specify a different `keyformat` when " "creating it or run `zfs change-key` on the child dataset. Doing so creates " "a new encryption root for the child and breaks its encryption inheritance " "from the parent." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3873 msgid "" "ZFS clones of an encrypted dataset always use the encryption key of their " "origin dataset. As a result, the `keystatus`, `keyformat`, `keylocation`, " "and `pbkdf2iters` properties are not inherited like other dataset " "properties. Instead, they use the values defined by the encryption root. " "To determine the encryption root, use the read-only `encryptionroot` " "property." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3878 msgid "" "If an attacker compromises an encryption key, changing the passphrase with " "`zfs change-key` does not necessarily protect existing or newly written " "data. New data continues to be encrypted with the same master key as the " "existing data. If an attacker obtains both a user key and its corresponding " "wrapped master key, running `zfs change-key` does not overwrite the previous " "master key on disk. As a result, the old master key may remain available " "for forensic analysis for an indeterminate period." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3883 msgid "" "If a master key has been compromised, the preferred solution is to securely " "erase the underlying storage devices and create a new pool. Afterwards, " "restore the data from a backup to the new pool. Alternatively, create a new " "encrypted dataset, migrate the data using `zfs send` and `zfs receive`, and " "then run `zpool trim --secure` to erase the freed space. If the underlying " "hardware does not support secure TRIM, use `zpool initialize` instead." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3885 #, no-wrap msgid "Sending Encrypted Datasets" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3889 msgid "" "ZFS replication is based on sending dataset snapshots, which can also be " "created from encrypted datasets. The resulting snapshots remain encrypted." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3893 #, no-wrap msgid "# zfs snapshot zroot/secretdata@snap1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3897 msgid "" "In addition to crossref:zfs[zfs-send-ssh,sending encrypted backups over " "SSH], using the `-w` (raw) option with `zfs send` transfers the encrypted " "data blocks to the target pool. A raw send provides several advantages:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3899 msgid "the receiving system never sees plaintext data." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3900 msgid "" "the receiving system does not require the passphrase since no decryption " "takes place." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3901 msgid "Backups can be sent without first loading the encryption key." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3902 msgid "" "an untrusted system can receive the encrypted data but cannot decrypt or " "modify it without the encryption key." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3904 msgid "" "To send the snapshot created above as a raw stream to the dataset `secret` " "in the pool `backup`, enter the following command:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3908 #, no-wrap msgid "# zfs send -w zroot/secretdata@snap1 | zfs recv backup/secret\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3913 msgid "" "Without the `-w` option, `zfs send` transmits the data in unencrypted form. " "The receiving system may then re-encrypt the data using a different key. " "However, doing so prevents future incremental raw sends to that destination." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:3915 #, no-wrap msgid "Loading Encryption Keys at Boot" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3920 msgid "" "The `zfskeys` man:rc[8] script loads encryption keys at boot for encrypted " "datasets whose `keylocation` property points to a key file with a `file://` " "URL. The script runs after pool import and before mounting the file " "systems, so datasets handled this way mount automatically during the normal " "ZFS startup. The script does not handle datasets with `keylocation=prompt`; " "load their keys manually with `zfs load-key` after the system has booted." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3922 msgid "" "To switch the dataset created earlier from a passphrase to a key file, " "generate 32 bytes of random data as the new key, restrict access to the key " "file, and change the encryption key of the dataset:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3928 #, no-wrap msgid "" "# dd if=/dev/random of=/root/secretdata.key bs=32 count=1\n" "# chmod 600 /root/secretdata.key\n" "# zfs change-key -o keyformat=raw -o keylocation=file:///root/secretdata.key zroot/secretdata\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3931 msgid "Enable the script in [.filename]#/etc/rc.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3935 #, no-wrap msgid "# sysrc zfskeys_enable=\"YES\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3939 msgid "" "By default, the script loads the keys of all encrypted datasets with a " "`file://` key location. To restrict key loading to specific datasets, list " "them in `zfskeys_datasets`, separated by spaces:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3943 #, no-wrap msgid "# sysrc zfskeys_datasets=\"zroot/secretdata\"\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3949 msgid "" "Anyone able to read the key file can decrypt the dataset. Keep the key file " "owned by `root` with mode `600`, and store it on storage that is itself " "protected, such as an encrypted root file system or removable media that is " "only connected during boot." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:3952 #, no-wrap msgid "Boot Environments" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3957 msgid "" "A boot environment is a bootable crossref:zfs[zfs-term-clone,clone] of the " "dataset tree that contains the operating system. On systems installed with " "the Root-on-ZFS layout, these datasets live under `zroot/ROOT`, with the " "running system in `zroot/ROOT/default`. Creating a boot environment " "snapshots and clones the root datasets, which completes in seconds and " "consumes almost no space until the environments start to diverge." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3960 msgid "" "Manage boot environments with man:bectl[8]. Create a new environment before " "a major change, such as an operating system or large package upgrade:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3968 #, no-wrap msgid "" "# bectl create beforeupgrade\n" "# bectl list\n" "BE Active Mountpoint Space Created\n" "default NR / 2.43G 2026-07-11 11:26\n" "beforeupgrade - - 328K 2026-07-11 11:31\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3971 msgid "" "In the `Active` column, `N` marks the environment in use now, and `R` marks " "the one that becomes active on reboot." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3977 msgid "" "Perform the upgrade with man:freebsd-update[8] or man:pkg[8] as usual. The " "upgrade modifies the active environment, while `beforeupgrade` preserves the " "system as it was. If the upgraded system fails to boot or misbehaves, " "reboot and select `beforeupgrade` from the `Boot Environments` menu of the " "FreeBSD loader. Selecting an environment in the loader menu affects the " "current boot only. To make the rollback permanent, activate the environment:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3981 #, no-wrap msgid "# bectl activate beforeupgrade\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3984 msgid "" "Running `bectl activate -t _beName_` instead activates an environment for " "the next boot only, which is useful when testing changes on a remote system." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3986 msgid "" "To inspect or repair the contents of an inactive environment without booting " "it, mount it at a temporary location:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3992 #, no-wrap msgid "" "# bectl mount beforeupgrade\n" "/tmp/be_mount.c1Xk\n" "# bectl umount beforeupgrade\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:3995 msgid "" "Destroy an environment that is no longer needed to reclaim the space it uses:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:3999 #, no-wrap msgid "# bectl destroy beforeupgrade\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4004 msgid "" "Creating a boot environment before every man:freebsd-update[8] upgrade or " "large man:pkg[8] operation provides an instant way back to a known-good " "system without restoring from backups." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:4007 #, no-wrap msgid "Boot Environments and Applications" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4012 msgid "" "A boot environment contains only the datasets under `zroot/ROOT`. On the " "default Root-on-ZFS layout that includes the whole root file system with " "[.filename]#/usr/local# and [.filename]#/var/db#, so installed packages and " "their metadata roll back together with the operating system. Datasets " "outside `zroot/ROOT`, such as `zroot/home`, `zroot/var/log`, and `zroot/var/" "mail`, are shared: every environment sees the same files, and activating an " "older environment does not return them to an earlier state." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4015 msgid "" "Plan the dataset layout around this split before relying on boot " "environments. Data that must survive a rollback, such as the databases of " "an application installed from packages, belongs on its own dataset outside " "`zroot/ROOT`:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4019 #, no-wrap msgid "# zfs create -o mountpoint=/var/db/postgres zroot/pgdata\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4023 msgid "" "With this layout, rolling back to an older environment returns the database " "server binaries to their previous version while the database contents remain " "untouched. The reverse also holds: files written to shared datasets while " "testing a new environment persist after switching back, so boot environments " "do not replace crossref:zfs[zfs-zfs-snapshot,snapshots] of those datasets." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:4025 #, no-wrap msgid "Advanced Topics" msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:4028 #, no-wrap msgid "Tuning" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4033 msgid "" "Adjust tunables to make ZFS perform best for different workloads. FreeBSD " "exposes the ZFS kernel tunables as man:sysctl[8] variables under `vfs.zfs`; " "man:zfs[4] documents every tunable and its default value. Set values that " "must apply from boot in [.filename]#/boot/loader.conf#; adjust runtime-" "changeable values with man:sysctl[8] and make them permanent in [.filename]#/" "etc/sysctl.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4038 msgid "" "`_vfs.zfs.arc.max_` - Upper size of the crossref:zfs[zfs-term-arc,ARC]. The " "default of `0` lets ZFS size the ARC automatically based on the amount of " "installed memory. Use a lower value if the system runs any other daemons or " "processes that may require memory; see crossref:zfs[zfs-advanced-arc,ARC " "Sizing and Monitoring] for guidance. Adjust this value at runtime with " "man:sysctl[8] and set it in [.filename]#/boot/loader.conf# or [.filename]#/" "etc/sysctl.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4042 msgid "" "`_vfs.zfs.arc.min_` - Lower size of the crossref:zfs[zfs-term-arc,ARC]. The " "default of `0` lets ZFS choose a small minimum automatically. Increase this " "value to prevent other applications from pressuring out the entire ARC. " "Adjust this value at runtime with man:sysctl[8] and set it in [.filename]#/" "boot/loader.conf# or [.filename]#/etc/sysctl.conf#." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4046 msgid "" "`_vfs.zfs.arc.meta_balance_` - Balance between caching metadata and file " "data in the crossref:zfs[zfs-term-arc,ARC]; values above `100` increasingly " "favor metadata, and the default is `500`. Increase this value if the " "workload involves operations on a large number of files and directories, or " "frequent metadata operations, at the cost of less file data fitting in the " "ARC. This tunable replaces `vfs.zfs.arc.meta_limit`, which OpenZFS 2.2 " "removed. Adjust this value at any time with man:sysctl[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4050 msgid "" "`_vfs.zfs.vdev.min_auto_ashift_` - Lower `ashift` (sector size) used " "automatically at pool creation time. The value is a power of two. The " "default value of `9` represents `2^9 = 512`, a sector size of 512 bytes. To " "avoid _write amplification_ and get the best performance, set this value to " "the largest sector size used by a device in the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4052 msgid "" "See crossref:zfs[zfs-zpool-create,Creating and Destroying Storage Pools] for " "why pools on 4 KB-sector drives should use an `ashift` of 12." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4058 msgid "" "`_vfs.zfs.prefetch.disable_` - Disable prefetch. A value of `0` enables and " "`1` disables it. The default is `0`. Prefetch works by reading larger " "blocks than requested into the crossref:zfs[zfs-term-arc,ARC] in hopes to " "soon need the data. If the workload has a large number of random reads, " "disabling prefetch may actually improve performance by reducing unnecessary " "reads. Adjust this value at any time with man:sysctl[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4064 msgid "" "`_vfs.zfs.txg.timeout_` - Upper number of seconds between crossref:zfs[zfs-" "term-txg,transaction group]s. The current transaction group writes to the " "pool and a fresh transaction group starts if this amount of time elapses " "since the previous transaction group. A transaction group may trigger " "earlier if writing enough data. The default value is 5 seconds. A larger " "value may improve read performance by delaying asynchronous writes, but this " "may cause uneven performance when writing the transaction group. Adjust " "this value at any time with man:sysctl[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4067 msgid "" "`_vfs.zfs.l2arc.write_max_` - Limit the amount of data written to the " "crossref:zfs[zfs-term-l2arc,L2ARC] per second. This tunable extends the " "longevity of SSDs by limiting the amount of data written to the device. " "Adjust this value at any time with man:sysctl[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4070 msgid "" "`_vfs.zfs.l2arc.write_boost_` - Adds the value of this tunable to " "`vfs.zfs.l2arc.write_max` and increases the write speed to the SSD until " "evicting the first block from the crossref:zfs[zfs-term-l2arc,L2ARC]. This " "\"Turbo Warmup Phase\" reduces the performance loss from an empty L2ARC " "after a reboot. Adjust this value at any time with man:sysctl[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4073 msgid "" "`_vfs.zfs.l2arc.rebuild_enabled_` - Make the contents of the " "crossref:zfs[zfs-term-l2arc,L2ARC] persist across reboots. With the default " "of `1`, ZFS rebuilds the L2ARC from the log blocks stored on the cache " "device when importing a pool, avoiding the long warm-up period an empty " "cache would otherwise need. Set this value to `0` to always start with an " "empty L2ARC." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4077 msgid "" "`_vfs.zfs.vdev.max_active_` - Upper number of I/O requests active on each " "device in the pool. A higher value keeps the device command queues full and " "may give higher throughput. A lower value reduces latency. Adjust this " "value at any time with man:sysctl[8]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4080 msgid "" "`_vfs.zfs.vdev.*_min_active_` and `_vfs.zfs.vdev.*_max_active_` - Lower and " "upper number of concurrent I/O requests the scheduler issues to each device " "for every I/O class: `sync_read`, `sync_write`, `async_read`, `async_write`, " "`scrub`, and others. These per-class limits replace the delay-based " "crossref:zfs[zfs-term-scrub,scrub] and crossref:zfs[zfs-term-" "resilver,resilver] throttling found in older versions of ZFS. For example, " "increasing `vfs.zfs.vdev.scrub_max_active` lets a scrub use a larger share " "of each device's queue, finishing sooner at the cost of foreground I/O " "latency." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4083 msgid "" "`_vfs.zfs.resilver_min_time_ms_` - Lower amount of time, in milliseconds, " "that a crossref:zfs[zfs-term-resilver,resilver] spends working between " "transaction group flushes; the default is `3000` (3 seconds). Increase this " "value to complete a resilver sooner when a degraded pool is at risk of " "losing another device, at the cost of slowing down normal pool operation. " "Adjust this value at any time with man:sysctl[8]." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:4085 #, no-wrap msgid "ARC Sizing and Monitoring" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4091 msgid "" "ZFS keeps recently and frequently used data and metadata in RAM in the " "crossref:zfs[zfs-term-arc,ARC]. The ARC grows on demand up to " "`vfs.zfs.arc.max` and shrinks again when other programs need memory, so on a " "dedicated storage server it is normal for most of the RAM to be in use. The " "ARC stores blocks in their compressed on-disk form and decompresses them on " "access. This _compressed ARC_ lets the same amount of RAM cache more data, " "increasing the effective hit rate." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4094 msgid "" "man:top[1] shows the current ARC size in its memory summary line. The " "`kstat.zfs.misc.arcstats` man:sysctl[8] tree exposes detailed statistics, " "including the current size, the target maximum, and hit and miss counters:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4102 #, no-wrap msgid "" "% sysctl kstat.zfs.misc.arcstats.size kstat.zfs.misc.arcstats.c_max kstat.zfs.misc.arcstats.hits kstat.zfs.misc.arcstats.misses\n" "kstat.zfs.misc.arcstats.size: 8963041280\n" "kstat.zfs.misc.arcstats.c_max: 15843122176\n" "kstat.zfs.misc.arcstats.hits: 954912441\n" "kstat.zfs.misc.arcstats.misses: 21356847\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4105 msgid "" "package:filesystems/zfs-stats[] summarizes these statistics in a human-" "readable report." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4109 msgid "" "The ARC yields memory under pressure, but on systems that share RAM between " "ZFS and other large consumers such as databases, virtual machines, or jails, " "the competition can cause uneven performance on both sides. Capping the ARC " "leaves a predictable amount of memory for the other workloads. For example, " "to limit the ARC to 8 GB, add this line to [.filename]#/boot/loader.conf#:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4113 #, no-wrap msgid "vfs.zfs.arc.max=\"8G\"\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4116 msgid "" "Changing `vfs.zfs.arc.max` with man:sysctl[8] takes effect immediately, " "although shrinking a warm ARC frees memory gradually." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:4118 #, no-wrap msgid "Synchronous Writes, the ZIL, and SLOG" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4124 msgid "" "Every pool has a crossref:zfs[zfs-term-zil,ZIL]. Applications that request " "synchronous semantics with man:fsync[2] or the `O_SYNC` flag do not get an " "acknowledgment until ZFS commits the corresponding intent log record to " "stable storage. By default the ZIL lives on the pool's regular vdevs, so " "every synchronous write competes with normal pool I/O. Asynchronous writes " "bypass the ZIL and are written with the next crossref:zfs[zfs-term-" "txg,transaction group]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4126 msgid "" "A dedicated crossref:zfs[zfs-term-vdev-log,log] vdev, often called a _SLOG_ " "(separate log), moves the ZIL to a fast device:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4130 #, no-wrap msgid "# zpool add mypool log mirror nda0 nda1\n" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4134 msgid "" "A SLOG helps only workloads that generate a lot of synchronous writes, such " "as NFS servers and databases. It makes no difference for purely " "asynchronous workloads." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4138 msgid "" "A few gigabytes of SLOG capacity is plenty: the ZIL holds at most a few " "seconds of incoming writes, roughly one transaction group's worth, before " "ZFS writes the data to its final location in the pool. Choose SSDs with " "power-loss protection and low sustained write latency, and mirror the log " "devices. ZFS reads the ZIL only after a crash, so losing an unmirrored SLOG " "together with a system crash loses the writes that were acknowledged but not " "yet committed to the pool." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4140 msgid "The `sync` dataset property controls synchronous write behavior:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4142 msgid "" "`sync=standard` (the default) commits synchronous writes to the ZIL and " "asynchronous writes with the next transaction group." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4143 msgid "" "`sync=always` treats every write as synchronous, trading performance for " "safety that helps only applications which fail to request synchronous writes " "when they should." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4144 msgid "`sync=disabled` treats every write as asynchronous." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4150 msgid "" "With `sync=disabled`, ZFS acknowledges synchronous writes before they reach " "stable storage. The pool itself stays consistent, but after a crash or " "power failure, applications and NFS clients silently lose up to a few " "seconds of data they believed was safely written. Do not use " "`sync=disabled` for databases, NFS exports, or any other data that matters." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4154 msgid "" "The `logbias` property tunes how ZFS uses the log: `logbias=latency` (the " "default) favors the SLOG to minimize commit latency, while " "`logbias=throughput` writes synchronous data directly to the main pool, " "reserving SLOG capacity for latency-sensitive datasets. See man:zfsprops[7] " "for details." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:4156 #, no-wrap msgid "Direct I/O" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/handbook/zfs/_index.adoc:4161 msgid "" "Direct I/O requires OpenZFS 2.3 or later, first available in FreeBSD 15.0." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4164 msgid "" "The `direct` dataset property controls how ZFS handles requests made with " "the `O_DIRECT` flag:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4166 msgid "" "`direct=standard` (the default) honors `O_DIRECT`: properly aligned reads " "and writes bypass the crossref:zfs[zfs-term-arc,ARC]." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4167 msgid "" "`direct=always` treats every properly aligned read or write as a direct " "request." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4168 msgid "" "`direct=disabled` silently ignores `O_DIRECT` and handles every request " "through the ARC." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4172 msgid "" "Direct I/O avoids the memory copies and caching overhead of the ARC. On " "pools of very fast NVMe devices this overhead can dominate the cost of the I/" "O itself, and applications that maintain their own caches, such as " "databases, waste RAM by caching the same data twice. For such workloads, " "direct I/O can increase throughput and reduce memory use." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4176 msgid "" "ZFS still verifies checksums for direct reads and writes, so data integrity " "protection is unchanged. Direct writes must be aligned to the dataset " "`recordsize`; ZFS silently redirects the unaligned portion of a request " "through the ARC. See man:zfsprops[7] for the full alignment rules and " "restrictions." msgstr "" #. type: Title === #: documentation/content/en/books/handbook/zfs/_index.adoc:4178 #, no-wrap msgid "`recordsize` and `volblocksize`" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4182 msgid "" "The `recordsize` property sets the largest block ZFS uses to store a file in " "a dataset, 128 KB by default. Matching the block size to the workload's I/O " "pattern avoids reading and writing more data than the application asked for." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4186 msgid "" "For databases that perform small random reads and writes, set `recordsize` " "to the database page size, typically 8 KB or 16 KB, before creating the " "database files. For datasets storing large media files or backup streams " "that are read and written sequentially, `recordsize=1M` reduces metadata " "overhead and improves compression. Volumes use the `volblocksize` property " "instead, which defaults to 16 KB and cannot change after creating the volume." msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4189 msgid "" "Changing `recordsize` affects newly written files only; existing files keep " "their original block size. Not even crossref:zfs[zfs-zfs-rewrite,`zfs " "rewrite`] applies a new `recordsize` to existing files, as property changes " "that affect the logical block size have no effect on rewritten blocks; copy " "the files anew to store them with the new value." msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:4191 #, no-wrap msgid "Further Resources" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4194 msgid "" "https://openzfs.github.io/openzfs-docs/[OpenZFS Documentation], including " "the Performance and Tuning guides" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4195 msgid "https://openzfs.org/[OpenZFS]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4196 msgid "" "man:zfs[4] describes every kernel tunable, man:zpoolconcepts[7] describes " "vdev types and pool layout, and man:zfsprops[7] describes every dataset " "property" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4197 msgid "Snapshot and replication automation tools from the Ports Collection:" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4198 msgid "" "package:filesystems/zrepl[] - a replication daemon supporting push and pull " "setups, automatic snapshot management, and resumable transfers" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4199 msgid "" "package:sysutils/sanoid[] - policy-driven snapshot management, with the " "bundled `syncoid` handling replication over SSH" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4200 msgid "" "package:filesystems/zfstools[] - automatic snapshot rotation in the style of " "the OpenSolaris auto-snapshot service, run from man:cron[8]" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4201 msgid "" "package:filesystems/zap[] - simple snapshot maintenance and remote " "replication, configured through ZFS properties instead of a configuration " "file" msgstr "" #. type: Title == #: documentation/content/en/books/handbook/zfs/_index.adoc:4203 #, no-wrap msgid "ZFS Features and Terminology" msgstr "" #. type: Plain text #: documentation/content/en/books/handbook/zfs/_index.adoc:4212 msgid "" "ZFS is fundamentally different from traditional file systems. ZFS combines " "the roles of file system and volume manager, enabling the addition of new " "storage devices to a live system and making the new space available on the " "existing file systems in that pool at once. By combining the traditionally " "separate roles, ZFS overcomes previous limitations that prevented RAID " "groups from growing. A _vdev_ is a top level device in a pool and can be a " "simple disk or a RAID transformation such as a mirror or RAID-Z array. ZFS " "file systems (called _datasets_) each have access to the combined free space " "of the entire pool. Used blocks from the pool decrease the space available " "to each file system. This approach avoids the common pitfall with extensive " "partitioning where free space becomes fragmented across the partitions." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4218 #, no-wrap msgid "[[zfs-term-pool]]pool" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4221 #, no-wrap msgid "" "A storage _pool_ is the most basic building block of ZFS. A pool consists of one or more vdevs, the underlying devices that store the data. A pool is then used to create one or more file systems (datasets) or block devices (volumes).\n" "These datasets and volumes share the pool of remaining free space. Each pool is uniquely identified by a name and a GUID. Pools created by modern OpenZFS are at pool version 5000; from that version on, individual capabilities are managed by _feature flags_ rather than the version number. See man:zpool-features[7] and crossref:zfs[zfs-zpool-upgrade,Upgrading a Storage Pool] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4222 #, no-wrap msgid "[[zfs-term-vdev]]vdev Types" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4256 #, no-wrap msgid "" "A pool consists of one or more vdevs, which themselves are a single disk or a group of disks, transformed to a RAID. When using a lot of vdevs, ZFS spreads data across the vdevs to increase performance and maximize usable space. All vdevs must be at least 64 MB in size.\n" "\n" "* [[zfs-term-vdev-disk]] _Disk_ - The most basic vdev type is a standard block device. This can be an entire disk (such as [.filename]#/dev/ada0#) or a partition ([.filename]#/dev/ada0p3#). On FreeBSD, there is no performance penalty for using a partition rather than the entire disk. This differs from recommendations made by the Solaris documentation.\n" "+\n" "[CAUTION]\n" "====\n" "Using an entire disk as part of a bootable pool is strongly discouraged, as this may render the pool unbootable.\n" "Likewise, you should not use an entire disk as part of a mirror or RAID-Z vdev.\n" "Reliably determining the size of an unpartitioned disk at boot time is impossible and there's no place to put in boot code.\n" "====\n" "\n" "* [[zfs-term-vdev-file]] _File_ - Regular files may make up ZFS pools, which is useful for testing and experimentation. Use the full path to the file as the device path in `zpool create`.\n" "* [[zfs-term-vdev-mirror]] _Mirror_ - When creating a mirror, specify the `mirror` keyword followed by the list of member devices for the mirror. A mirror consists of two or more devices, writing all data to all member devices. A mirror vdev will hold as much data as its smallest member. A mirror vdev can withstand the failure of all but one of its members without losing any data.\n" "+\n" "[NOTE]\n" "====\n" "To upgrade a regular single disk vdev to a mirror vdev at any time, use `zpool crossref:zfs[zfs-zpool-attach,attach]`.\n" "====\n" "\n" "* [[zfs-term-vdev-raidz]] _RAID-Z_ - ZFS uses RAID-Z, a variation on standard RAID-5 that offers better distribution of parity and eliminates the \"RAID-5 write hole\" in which the data and parity information become inconsistent after an unexpected restart. ZFS supports three levels of RAID-Z which provide varying levels of redundancy in exchange for decreasing levels of usable storage. ZFS uses RAID-Z1 through RAID-Z3 based on the number of parity devices in the array and the number of disks which can fail before the pool stops being operational.\n" "+\n" "In a RAID-Z1 configuration with four disks, each 1 TB, usable storage is 3 TB and the pool will still be able to operate in degraded mode with one faulted disk. If another disk goes offline before replacing and resilvering the faulted disk would result in losing all pool data.\n" "+\n" "In a RAID-Z3 configuration with eight disks of 1 TB, the volume will provide 5 TB of usable space and still be able to operate with three faulted disks. The traditional recommendation is no more than nine disks in a single vdev. If more disks make up the configuration, the recommendation is to divide them into separate vdevs and stripe the pool data across them.\n" "+\n" "A configuration of two RAID-Z2 vdevs consisting of 8 disks each would create something like a RAID-60 array. A RAID-Z group's storage capacity is about the size of the smallest disk multiplied by the number of non-parity disks. Four 1 TB disks in RAID-Z1 has an effective size of about 3 TB, and an array of eight 1 TB disks in RAID-Z3 will yield 5 TB of usable space.\n" "+\n" "Growing a raidz vdev one disk at a time is possible with crossref:zfs[zfs-zpool-raidz-expansion,RAID-Z expansion], which requires OpenZFS 2.3 or later, first available in FreeBSD 15.0.\n" "* [[zfs-term-vdev-draid]] _dRAID_ - A variant of RAID-Z that distributes data, parity, and spare capacity across all member disks using fixed-width stripes. Instead of dedicated hot spare disks, dRAID provides _distributed spares_: spare capacity spread over every member disk, allowing a failed disk to rebuild sequentially onto all remaining disks at once and restoring redundancy much faster than a traditional resilver onto a single spare. Specify a dRAID vdev as `draid[parity][:datad][:childrenc][:sparess]`, as described in man:zpoolconcepts[7]. See crossref:zfs[zfs-zpool-draid,dRAID Pools] for details.\n" "* [[zfs-term-vdev-spare]] _Spare_ - ZFS has a special pseudo-vdev type for keeping track of available hot spares. When man:zfsd[8] is enabled, ZFS deploys installed hot spares automatically to replace failed devices; otherwise, configure them manually to replace the failed device using `zpool replace`. See crossref:zfs[zfs-zpool-spares,Hot Spares and Automatic Replacement with zfsd] for details.\n" "* [[zfs-term-vdev-log]] _Log_ - Every pool has a ZFS Intent Log (crossref:zfs[zfs-term-zil,ZIL]), stored on the regular pool devices by default. A dedicated log vdev, often called a SLOG, moves the intent log to a separate device, typically an SSD. Having a dedicated log device improves the performance of applications with a high volume of synchronous writes like databases. Mirroring of log devices is possible, but RAID-Z is not supported. If using a lot of log devices, writes will be load-balanced across them. See crossref:zfs[zfs-advanced-zil-slog,\"Synchronous Writes, the ZIL, and SLOG\"] for details.\n" "* [[zfs-term-vdev-cache]] _Cache_ - Adding a cache vdev to a pool will add the storage of the cache to the crossref:zfs[zfs-term-l2arc,L2ARC]. Mirroring cache devices is impossible. Since a cache device stores only new copies of existing data, there is no risk of data loss.\n" "* [[zfs-term-vdev-special]] _Special/Dedup_ - Allocation class vdevs that store pool metadata, optionally small file blocks (controlled by the `special_small_blocks` dataset property), and deduplication tables on fast devices such as SSDs, speeding up a pool of slower disks. These vdevs are pool-critical: losing a special or dedup vdev loses the pool, so give them the same level of redundancy as the data vdevs. See crossref:zfs[zfs-zpool-special,Special Allocation Classes] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4257 #, no-wrap msgid "[[zfs-term-txg]] Transaction Group (TXG)" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4278 #, no-wrap msgid "" "Transaction Groups are the way ZFS groups blocks changes together and writes them to the pool. Transaction groups are the atomic unit that ZFS uses to ensure consistency. ZFS assigns each transaction group a unique 64-bit consecutive identifier. There can be up to three active transaction groups at a time, one in each of these three states:\n" "\n" "* _Open_ - A new transaction group begins in the open state and accepts new\n" " writes. There is always a transaction group in the open state, but the\n" " transaction group may refuse new writes if it has reached a limit. Once the\n" " open transaction group has reached a limit, or reaching the\n" " crossref:zfs[zfs-advanced-tuning,`vfs.zfs.txg.timeout`], the transaction group advances to the next state.\n" "* _Quiescing_ - A short state that allows any pending operations to finish without blocking the creation of a new open transaction group. Once all the transactions in the group have completed, the transaction group advances to the final state.\n" "* _Syncing_ - Write all the data in the transaction group to stable storage.\n" " This process will in turn change other data, such as metadata and space maps,\n" " that ZFS will also write to stable storage. The process of syncing involves\n" " several passes. On the first and biggest, all the changed data blocks; next\n" " come the metadata, which may take several passes to complete. Since allocating\n" " space for the data blocks generates new metadata, the syncing state cannot\n" " finish until a pass completes that does not use any new space. The syncing\n" " state is also where _synctasks_ complete. Synctasks are administrative\n" " operations such as creating or destroying snapshots and datasets that complete\n" " the uberblock change. Once the sync state completes the transaction group in\n" " the quiescing state advances to the syncing state. All administrative\n" " functions, such as crossref:zfs[zfs-term-snapshot,`snapshot`] write as part of the transaction group. ZFS adds a created synctask to the open transaction group, and that group advances as fast as possible to the syncing state to reduce the latency of administrative commands." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4279 #, no-wrap msgid "[[zfs-term-arc]]Adaptive Replacement Cache (ARC)" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4281 #, no-wrap msgid "ZFS uses an Adaptive Replacement Cache (ARC), rather than a more traditional Least Recently Used (LRU) cache. An LRU cache is a simple list of items in the cache, sorted by how recently object was used, adding new items to the head of the list. When the cache is full, evicting items from the tail of the list makes room for more active objects. An ARC consists of four lists; the Most Recently Used (MRU) and Most Frequently Used (MFU) objects, plus a ghost list for each. These ghost lists track evicted objects to prevent adding them back to the cache. This increases the cache hit ratio by avoiding objects that have a history of occasional use. Another advantage of using both an MRU and MFU is that scanning an entire file system would evict all data from an MRU or LRU cache in favor of this freshly accessed content. With ZFS, there is also an MFU that tracks the most frequently used objects, and the cache of the most commonly accessed blocks remains." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4282 #, no-wrap msgid "[[zfs-term-l2arc]]L2ARC" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4298 #, no-wrap msgid "" "L2ARC is the second level of the ZFS caching system. RAM stores the primary\n" "ARC. Since the amount of available RAM is often limited, ZFS can also use\n" "crossref:zfs[zfs-term-vdev-cache,cache vdevs]. Solid State Disks (SSDs) are\n" "often used as these cache devices due to their higher speed and lower latency\n" "compared to traditional spinning disks. L2ARC is entirely optional, but having\n" "one will increase read speeds for cached files on the SSD instead of having to\n" "read from the regular disks. L2ARC can also speed up\n" "crossref:zfs[zfs-term-deduplication,deduplication] because a deduplication table\n" "(DDT) that does not fit in RAM but does fit in the L2ARC will be much faster\n" "than a DDT that must read from disk.\n" "Since OpenZFS 2.0, the L2ARC is persistent: after a reboot, ZFS rebuilds the cache contents from the headers stored on the cache device instead of starting with an empty cache.\n" "Limits on the data rate added to the cache devices prevent prematurely wearing out SSDs with extra writes.\n" "Until the cache is full (the first block evicted to make room), writes to the L2ARC limit to the sum of the write limit and the boost limit, and afterwards limit to the write limit.\n" "A pair of man:sysctl[8] values control these rate limits: `vfs.zfs.l2arc.write_max` controls the number of bytes written to the cache per second, while `vfs.zfs.l2arc.write_boost` adds to this limit until the first eviction from the cache.\n" "See crossref:zfs[zfs-advanced-tuning,Tuning] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4299 #, no-wrap msgid "[[zfs-term-zil]]ZIL" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4301 #, no-wrap msgid "The ZFS Intent Log (ZIL) is the on-disk record that ZFS uses to replay synchronous writes after a crash. Every pool has a ZIL; by default it occupies a small amount of space on the regular pool devices. When an application requests a synchronous write (a guarantee that the data is stored to disk rather than merely cached for later writes), ZFS commits the data to the ZIL first and flushes it out to the regular storage with the next transaction group. Moving the ZIL to a dedicated crossref:zfs[zfs-term-vdev-log,log vdev] (SLOG) on a device faster than the main storage, such as an SSD, greatly reduces latency and improves performance. Synchronous workloads like databases will profit from a fast ZIL alone. Regular asynchronous writes such as copying files will not use the ZIL at all. See crossref:zfs[zfs-advanced-zil-slog,\"Synchronous Writes, the ZIL, and SLOG\"] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4302 #, no-wrap msgid "[[zfs-term-cow]]Copy-On-Write" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4304 #, no-wrap msgid "Unlike a traditional file system, ZFS writes a different block rather than overwriting the old data in place. When completing this write the metadata updates to point to the new location. When a shorn write (a system crash or power loss in the middle of writing a file) occurs, the entire original contents of the file are still available and ZFS discards the incomplete write. This also means that ZFS does not require a man:fsck[8] after an unexpected shutdown." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4305 #, no-wrap msgid "[[zfs-term-dataset]]Dataset" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4315 #, no-wrap msgid "" "_Dataset_ is the generic term for a ZFS file system, volume, snapshot or clone.\n" "Each dataset has a unique name in the format _poolname/path@snapshot_. The root\n" "of the pool is a dataset as well. Child datasets have hierarchical names like\n" "directories. For example, _mypool/home_, the home dataset, is a child of\n" "_mypool_ and inherits properties from it. Expand this further by creating\n" "_mypool/home/user_. This grandchild dataset will inherit properties from the\n" "parent and grandparent. Set properties on a child to override the defaults\n" "inherited from the parent and grandparent. Administration of datasets and their\n" "children can be crossref:zfs[zfs-zfs-allow,delegated]." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4316 #, no-wrap msgid "[[zfs-term-filesystem]]File system" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4318 #, no-wrap msgid "A ZFS dataset is most often used as a file system. Like most other file systems, a ZFS file system mounts somewhere in the systems directory hierarchy and contains files and directories of its own with permissions, flags, and other metadata." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4319 #, no-wrap msgid "[[zfs-term-volume]]Volume" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4321 #, no-wrap msgid "ZFS can also create volumes, which appear as disk devices. Volumes have a lot of the same features as datasets, including copy-on-write, snapshots, clones, and checksumming. Volumes can be useful for running other file system formats on top of ZFS, such as UFS virtualization, or exporting iSCSI extents." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4322 #, no-wrap msgid "[[zfs-term-snapshot]]Snapshot" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4342 #, no-wrap msgid "" "The crossref:zfs[zfs-term-cow,copy-on-write] (COW) design of ZFS allows for\n" "nearly instantaneous, consistent snapshots with arbitrary names. After taking a\n" "snapshot of a dataset, or a recursive snapshot of a parent dataset that will\n" "include all child datasets, new data goes to new blocks, but without reclaiming\n" "the old blocks as free space. The snapshot contains the original file system\n" "version and the live file system contains any changes made since taking the\n" "snapshot using no other space. New data written to the live file system uses new\n" "blocks to store this data. The snapshot will grow as the blocks are no longer\n" "used in the live file system, but in the snapshot alone. Mounting these snapshots\n" "read-only allows recovering previous file versions. A\n" "crossref:zfs[zfs-zfs-snapshot-rollback,rollback] of a live file system to a specific\n" "snapshot is possible, undoing any changes that took place after taking the\n" "snapshot. Each block in the pool has a reference counter which keeps track of\n" "the snapshots, clones, datasets, or volumes use that block. As files and\n" "snapshots get deleted, the reference count decreases, reclaiming the free space\n" "when no longer referencing a block. Marking snapshots with a\n" "crossref:zfs[zfs-zfs-snapshot-hold,hold] means any attempt to destroy it\n" "returns an `EBUSY` error. Each snapshot can have holds with a unique name each.\n" "The crossref:zfs[zfs-zfs-snapshot-hold,release] command removes the hold so the snapshot can be deleted. Snapshots, cloning, and rolling back works on volumes, but independently mounting does not." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4343 #, no-wrap msgid "[[zfs-term-clone]]Clone" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4345 #, no-wrap msgid "Cloning a snapshot is also possible. A clone is a writable version of a snapshot, allowing the file system to fork as a new dataset. As with a snapshot, a clone initially consumes no new space. As new data written to a clone uses new blocks, the size of the clone grows. When blocks are overwritten in the cloned file system or volume, the reference count on the previous block decreases. Removing the snapshot upon which a clone bases is impossible because the clone depends on it. The snapshot is the parent, and the clone is the child. Clones can be _promoted_, reversing this dependency and making the clone the parent and the previous parent the child. This operation requires no new space. Since the amount of space used by the parent and child reverses, it may affect existing quotas and reservations." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4346 #, no-wrap msgid "[[zfs-term-bookmark]]Bookmark" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4351 #, no-wrap msgid "" "A bookmark records the point in time at which a snapshot was taken, without keeping any of the snapshot data.\n" "Bookmarks serve as the source of incremental crossref:zfs[zfs-zfs-send,`zfs send`] streams, making it possible to destroy the snapshot on the sending side while retaining the ability to send further increments.\n" "Create a bookmark from an existing snapshot with `zfs bookmark`.\n" "See crossref:zfs[zfs-zfs-bookmark,Bookmarks] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4352 #, no-wrap msgid "[[zfs-term-hold]]Hold" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4357 #, no-wrap msgid "" "A hold is a named tag placed on a snapshot that prevents its destruction.\n" "Attempts to destroy a held snapshot fail with an `EBUSY` error until releasing every hold with `zfs release`.\n" "Holds protect snapshots that backup and replication tools still depend on.\n" "See crossref:zfs[zfs-zfs-snapshot-hold,Snapshot Holds] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4358 #, no-wrap msgid "[[zfs-term-checksum]]Checksum" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4377 #, no-wrap msgid "" "Every block is also checksummed. The checksum algorithm used is a per-dataset\n" "property, see crossref:zfs[zfs-zfs-set,`set`]. The checksum of each block is\n" "transparently validated when read, allowing ZFS to detect silent corruption. If\n" "the data read does not match the expected checksum, ZFS will attempt to recover\n" "the data from any available redundancy, like mirrors or RAID-Z. Trigger a\n" "validation of all checksums with crossref:zfs[zfs-term-scrub,`scrub`]. Checksum algorithms include:\n" "\n" "* `fletcher2`\n" "* `fletcher4`\n" "* `sha256`\n" "* `sha512`\n" "* `skein`\n" "* `edonr`\n" "* `blake3` (since FreeBSD 14.0)\n" "\n" "The `fletcher` algorithms are faster, but the cryptographic hashes (`sha256`, `sha512`, `skein`, `edonr`, and `blake3`) have a much lower chance of collisions at the cost of some performance.\n" "The default value of `on` currently selects `fletcher4`; crossref:zfs[zfs-term-deduplication,deduplication] requires a cryptographic hash such as `sha256`.\n" "Deactivating checksums is possible, but strongly discouraged." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4378 #, no-wrap msgid "[[zfs-term-compression]]Compression" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4395 #, no-wrap msgid "" "Each dataset has a compression property. Since OpenZFS 2.2, new datasets have compression enabled by default (`compression=on`, which selects LZ4). This causes compression of all new data written to the dataset. Beyond a reduction in space used, read and write throughput often increases because fewer blocks need reading or writing.\n" "\n" "[[zfs-term-compression-lz4]]\n" "* _LZ4_ - Added in ZFS pool version 5000 (feature flags), LZ4 is the algorithm that `compression=on` selects and the recommended general-purpose choice. LZ4 works about 50% faster than LZJB when operating on compressible data, and is over three times faster when operating on uncompressible data. LZ4 also decompresses about 80% faster than LZJB. On modern CPUs, LZ4 can often compress at over 500 MB/s, and decompress at over 1.5 GB/s (per single CPU core).\n" "\n" "[[zfs-term-compression-zstd]]\n" "* _ZSTD_ - Zstandard offers higher compression ratios than LZ4 with a configurable trade-off between speed and compression, ranging from the fast `zstd-fast` variants to `zstd-19` for maximum space savings. See crossref:zfs[zfs-zfs-compression-zstd,Zstandard Compression] for details.\n" "\n" "[[zfs-term-compression-lzjb]]\n" "* _LZJB_ - A legacy compression algorithm, created by Jeff Bonwick (one of the original creators of ZFS). LZJB offers good compression with less CPU overhead compared to GZIP. LZ4 has replaced it as the default algorithm; prefer LZ4 or ZSTD for new datasets.\n" "\n" "[[zfs-term-compression-gzip]]\n" "* _GZIP_ - A popular stream compression algorithm available in ZFS. One of the main advantages of using GZIP is its configurable level of compression. When setting the `compress` property, the administrator can choose the level of compression, ranging from `gzip1`, the lowest level of compression, to `gzip9`, the highest level of compression. This gives the administrator control over how much CPU time to trade for saved disk space.\n" "\n" "[[zfs-term-compression-zle]]\n" "* _ZLE_ - Zero Length Encoding is a special compression algorithm that compresses continuous runs of zeros alone. This compression algorithm is useful when the dataset contains large blocks of zeros." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4396 #, no-wrap msgid "[[zfs-term-copies]]Copies" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4400 #, no-wrap msgid "" "When set to a value greater than 1, the `copies` property instructs ZFS to\n" "maintain copies of each block in the crossref:zfs[zfs-term-filesystem,file\n" "system] or crossref:zfs[zfs-term-volume,volume]. Setting this property on important datasets provides added redundancy from which to recover a block that does not match its checksum. In pools without redundancy, the copies feature is the single form of redundancy. The copies feature can recover from a single bad sector or other forms of minor corruption, but it does not protect the pool from the loss of an entire disk." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4401 #, no-wrap msgid "[[zfs-term-deduplication]]Deduplication" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4405 #, no-wrap msgid "" "Checksums make it possible to detect duplicate blocks when writing data. With deduplication, the reference count of an existing, identical block increases, saving storage space. ZFS keeps a deduplication table (DDT) in memory to detect duplicate blocks. The table contains a list of unique checksums, the location of those blocks, and a reference count. When writing new data, ZFS calculates checksums and compares them to the list. When finding a match it uses the existing block. Using the SHA256 checksum algorithm with deduplication provides a secure cryptographic hash. Deduplication is tunable. If `dedup` is `on`, then a matching checksum means that the data is identical. Setting `dedup` to `verify`, ZFS performs a byte-for-byte check on the data ensuring they are actually identical. If the data is not identical, ZFS will note the hash collision and store the two blocks separately. As the DDT must store the hash of each unique block, it consumes a large amount of memory. A general rule of thumb is 5-6 GB of RAM per 1 TB of deduplicated data. In situations not practical to have enough RAM to keep the entire DDT in memory, performance will suffer greatly as the DDT must read from disk before writing each new block. Deduplication can use L2ARC to store the DDT, providing a middle ground between fast system memory and slower disks. Consider using compression instead, which often provides nearly as much space savings without the increased memory.\n" "_Fast dedup_ batches DDT updates in a log, allows pruning stale entries with `zpool ddtprune`, and caps the table size with the `dedup_table_quota` pool property; it requires OpenZFS 2.3 or later, first available in FreeBSD 15.0.\n" "See crossref:zfs[zfs-zfs-deduplication,Deduplication] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4406 #, no-wrap msgid "[[zfs-term-block-cloning]]Block Cloning" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4411 #, no-wrap msgid "" "Block cloning allows a file copy to reference the existing on-disk blocks of the source file instead of duplicating them, so the copy completes almost instantly and consumes no extra space until either file changes.\n" "On FreeBSD, man:cp[1] uses man:copy_file_range[2], so ordinary file copies become block clones when the feature is enabled (the default on FreeBSD 15.0).\n" "The `bcloneused`, `bclonesaved`, and `bcloneratio` pool properties report the resulting space savings.\n" "See crossref:zfs[zfs-zfs-block-cloning,Block Cloning] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4412 #, no-wrap msgid "[[zfs-term-scrub]]Scrub" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4423 #, no-wrap msgid "" "Instead of a consistency check like man:fsck[8], ZFS has `scrub`. `scrub` reads\n" "all data blocks stored on the pool and verifies their checksums against the\n" "known good checksums stored in the metadata. A periodic check of all the data\n" "stored on the pool ensures the recovery of any corrupted blocks before needing\n" "them. A scrub is not required after an unclean shutdown, but good practice is at\n" "least once every month. ZFS verifies the checksum of each block during\n" "normal use, but a scrub makes certain to check even infrequently used blocks for\n" "silent corruption. ZFS improves data security in archival storage situations.\n" "Pause a running scrub with `zpool scrub -p` and resume it later by running `zpool scrub` again.\n" "See crossref:zfs[zfs-zpool-scrub,Scrubbing a Pool] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4424 #, no-wrap msgid "[[zfs-term-checkpoint]]Checkpoint" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4429 #, no-wrap msgid "" "A checkpoint preserves the entire state of a pool at a single point in time, including pool-wide configuration changes that snapshots cannot capture.\n" "Rewinding to a checkpoint with `zpool import --rewind-to-checkpoint` undoes everything that happened after taking it, such as enabling pool features, adding or removing vdevs, or destroying datasets.\n" "A pool has at most one checkpoint at a time.\n" "See crossref:zfs[zfs-zpool-checkpoint,Pool Checkpoints] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4430 #, no-wrap msgid "[[zfs-term-trim]]TRIM" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4434 #, no-wrap msgid "" "TRIM notifies SSDs and other flash-based storage which blocks the pool no longer uses, allowing the device to erase them in advance and sustain write performance.\n" "Run `zpool trim` manually, or set the `autotrim` pool property to `on` to trim freed space continuously.\n" "See crossref:zfs[zfs-zpool-trim,TRIM and Initialization] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4435 #, no-wrap msgid "[[zfs-term-quota]]Dataset Quota" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4449 #, no-wrap msgid "" "ZFS provides fast and accurate dataset, user, and group space accounting as well as quotas and space reservations. This gives the administrator fine grained control over space allocation and allows reserving space for critical file systems.\n" "\n" "ZFS supports different types of quotas: the dataset quota, the\n" "crossref:zfs[zfs-term-refquota,reference quota (refquota)], the\n" "crossref:zfs[zfs-term-userquota,user quota], and the\n" "crossref:zfs[zfs-term-groupquota,group quota].\n" "\n" "Quotas limit the total size of a dataset and its descendants, including snapshots of the dataset, child datasets, and the snapshots of those datasets.\n" "\n" "[NOTE]\n" "====\n" "Volumes do not support quotas, as the `volsize` property acts as an implicit quota.\n" "====" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4450 #, no-wrap msgid "[[zfs-term-refquota]]Reference Quota" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4452 #, no-wrap msgid "A reference quota limits the amount of space a dataset can consume by enforcing a hard limit. This hard limit includes space referenced by the dataset alone and does not include space used by descendants, such as file systems or snapshots." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4453 #, no-wrap msgid "[[zfs-term-userquota]]User Quota" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4455 #, no-wrap msgid "User quotas are useful to limit the amount of space used by the specified user." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4456 #, no-wrap msgid "[[zfs-term-groupquota]]Group Quota" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4458 #, no-wrap msgid "The group quota limits the amount of space that a specified group can consume." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4459 #, no-wrap msgid "[[zfs-term-reservation]]Dataset Reservation" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4467 #, no-wrap msgid "" "The `reservation` property makes it possible to guarantee an amount of space\n" "for a specific dataset and its descendants. This means that setting a 10 GB\n" "reservation on [.filename]#storage/home/bob# prevents other datasets from using\n" "up all free space, reserving at least 10 GB of space for this dataset. Unlike a\n" "regular crossref:zfs[zfs-term-refreservation,`refreservation`], space used by snapshots and descendant datasets does count against the reservation.\n" "\n" "Reservations of any sort are useful in situations such as planning and testing the suitability of disk space allocation in a new system, or ensuring that enough space is available on file systems for audio logs or system recovery procedures and files." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4468 #, no-wrap msgid "[[zfs-term-refreservation]]Reference Reservation" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4474 #, no-wrap msgid "" "The `refreservation` property makes it possible to guarantee an amount of space\n" "for the use of a specific dataset _excluding_ its descendants. This means that\n" "setting a 10 GB reservation on [.filename]#storage/home/bob#, and another\n" "dataset tries to use the free space, reserving at least 10 GB of space for this\n" "dataset. In contrast to a regular crossref:zfs[zfs-term-reservation,reservation], space used by snapshots and descendant datasets is not counted against the reservation. For example, if taking a snapshot of [.filename]#storage/home/bob#, enough disk space other than the `refreservation` amount must exist for the operation to succeed. Descendants of the main data set are not counted in the `refreservation` amount and so do not encroach on the space set." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4475 #, no-wrap msgid "[[zfs-term-boot-environment]]Boot Environment" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4479 #, no-wrap msgid "" "A boot environment is a bootable clone of the datasets that hold the FreeBSD system, managed with man:bectl[8].\n" "Creating a boot environment before a system upgrade makes it possible to boot the previous, known-good system from the loader menu if the upgrade causes problems.\n" "See crossref:zfs[zfs-boot-environments,Boot Environments] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4480 #, no-wrap msgid "[[zfs-term-resilver]]Resilver" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4486 #, no-wrap msgid "" "When replacing a failed disk, ZFS must fill the new disk with the lost data.\n" "_Resilvering_ is the process of writing that data to the replacement device: mirrors resilver by copying the data from the surviving members, while RAID-Z reconstructs it from the parity information distributed across the remaining drives.\n" "Unlike a traditional RAID rebuild, resilvering copies allocated data alone rather than every sector of the device.\n" "A _sequential resilver_ (`zpool attach -s` or `zpool replace -s`) rebuilds mirror and dRAID vdevs even faster by copying blocks in disk order, skipping checksum verification and deferring it to an automatically scheduled scrub.\n" "See crossref:zfs[zfs-zpool-resilver,Dealing with Failed Devices] for details." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4487 #, no-wrap msgid "[[zfs-term-online]]Online" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4489 #, no-wrap msgid "A pool or vdev in the `Online` state has its member devices connected and fully operational. Individual devices in the `Online` state are functioning." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4490 #, no-wrap msgid "[[zfs-term-offline]]Offline" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4494 #, no-wrap msgid "" "The administrator puts individual devices in an `Offline` state if enough\n" "redundancy exists to avoid putting the pool or vdev into a\n" "crossref:zfs[zfs-term-faulted,Faulted] state. An administrator may choose to offline a disk in preparation for replacing it, or to make it easier to identify." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4495 #, no-wrap msgid "[[zfs-term-degraded]]Degraded" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4502 #, no-wrap msgid "" "A pool or vdev in the `Degraded` state has one or more disks that disappeared\n" "or failed. The pool is still usable, but if other devices fail, the pool may\n" "become unrecoverable. Reconnecting the missing devices or replacing the failed\n" "disks will return the pool to an crossref:zfs[zfs-term-online,Online] state\n" "after the reconnected or new device has completed the\n" "crossref:zfs[zfs-term-resilver,Resilver] process." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4503 #, no-wrap msgid "[[zfs-term-faulted]]Faulted" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4509 #, no-wrap msgid "" "A pool or vdev in the `Faulted` state is no longer operational. Accessing the\n" "data is no longer possible. A pool or vdev enters the `Faulted` state when the\n" "number of missing or failed devices exceeds the level of redundancy in the vdev.\n" "If reconnecting missing devices the pool will return to an\n" "crossref:zfs[zfs-term-online,Online] state. Insufficient redundancy to compensate for the number of failed disks loses the pool contents and requires restoring from backups." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4510 #, no-wrap msgid "[[zfs-term-unavail]]Unavail" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4514 #, no-wrap msgid "" "A device in the `Unavail` state cannot be opened, because it is missing or inaccessible.\n" "The pool continues operating if enough redundancy exists to compensate, running in a crossref:zfs[zfs-term-degraded,Degraded] state.\n" "If a top-level vdev is `Unavail`, accessing the pool contents is impossible." msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4515 #, no-wrap msgid "[[zfs-term-removed]]Removed" msgstr "" #. type: Table #: documentation/content/en/books/handbook/zfs/_index.adoc:4518 #, no-wrap msgid "" "A device in the `Removed` state was physically detached while the system was running.\n" "Device removal detection is hardware-dependent and unsupported on some platforms.\n" "When the device reconnects, man:zfsd[8] brings it back online; if the device does not return, zfsd activates an available hot spare in its place." msgstr ""