Creating pools 11
A pool name starts with a letter, and mirror, raidz, draid, spare and log are reserved names, as is any name beginning with mirror, raidz, draid or spare.
Command What it does
zpool create tank raidz sda sdb sdc sdd sde sdfCreate a RAID-Z pool Six disks become one raidz vdev; the root dataset mounts at /tank unless -m or -R says otherwise.
zpool create tank mirror sda sdb mirror sdc sddCreate a pool of two mirrors Each mirror keyword opens a new group, giving two vdevs of two disks here.
zpool create tank sda1 sdb2Create a pool from partitions The two partitions form a pool that has no redundancy.
zpool create tank /path/to/file/a /path/to/file/bCreate a file-backed pool Plain files serve as devices, which the manual suggests for experiments only.
zpool create tank mirror sda sdb spare sdcCreate a mirror with a hot spare sdc waits unused and stands in when one of the mirror disks fails.
zpool create pool mirror sda sdb mirror sdc sdd log mirror sde sdfCreate a pool with a mirrored log Two data mirrors plus a mirrored pair holding the separate intent log.
zpool create pool sda sdb cache sdc sddCreate a pool plus cache disks Cache devices add a caching layer between memory and disk; they cannot be mirrored or put in raidz.
zpool create -n POOL VDEVPreview a new pool layout Prints the layout that would result and leaves the disks untouched.
zpool create -m MOUNTPOINT POOL VDEVSet the root mount point Takes an absolute path, legacy or none in place of the default /POOL.
zpool create -o PROPERTY=VALUE POOL VDEVSet a pool property at creation Any property from zpoolprops(7), ashift for example; repeat the option for each one.
zpool create -O FILE-SYSTEM-PROPERTY=VALUE POOL VDEVSet a root dataset property Capital -O applies a dataset property to the root file system, where children inherit it.
Checking pool health 15
Command What it does
zpool statusShow pool health Lists each pool with its device states and, during a scrub or resilver, the percentage done.
zpool status -xShow only troubled pools Restricts the report to pools with errors or that are unavailable; outdated-format warnings do not count.
zpool status -vList data errors in detail Adds the full list of data errors recorded since the last completed scrub.
zpool status -LShow real device names Resolves symbolic links so the current block device name appears, whichever /dev/disk path opened it.
zpool status -c vendor,model,sizeAdd script columns to status Runs the named scripts on every vdev and appends their output as extra columns.
zpool listList pools with capacity One line per pool: size, allocated and free space, fragmentation, capacity and health.
zpool list -v dataList space per vdev Breaks the figures of pool data down by vdev and disk, including capacity not yet usable (EXPANDSZ).
zpool list -HList pools for scripts Leaves out the header line and puts one tab between fields.
zpool iostatShow pool I/O statistics Reports logical I/O, which can differ from the physical figures of iostat(1).
zpool iostat -v pool 5Watch I/O per vdev Prints a line for every vdev, cache devices included, and repeats every five seconds.
zpool iostat -lAdd average latency columns Splits waiting time into total, disk and per-queue averages.
zpool historyShow pool command history Covers all pools when no pool is named.
zpool history -lShow history in long format Each record also names the user, the host and the zone that ran the command.
zpool eventsList kernel ZFS events These are the events zed(8) consumes to automate jobs such as swapping in a hot spare.
zpool events -vShow full event payloads
Importing and exporting pools 14
Command What it does
zpool importList importable pools Searches the devices and prints every exported pool it finds with its id, state and layout.
zpool import tankImport a pool by name The numeric identifier shown in the listing can be given instead of the name.
zpool import POOL NEWPOOLImport under a new name The second name replaces the one the pool was exported with.
zpool import -aImport every pool found
zpool import -a -NImport without mounting Brings the pools in but mounts none of their file systems.
zpool import -d DIRSearch a directory for pools Looks for devices or files in that directory; the option may be repeated.
zpool import -f POOLForce an import Needed when the pool was not exported first and so still looks active.
zpool import -R ROOT POOLImport under an alternate root Sets altroot to the directory and cachefile to none for this import.
zpool import -F POOLRecover a damaged pool Throws away the last few transactions to make the pool importable; their data cannot be brought back.
zpool import -DList destroyed pools To bring one back, name it and add -f as well.
zpool export tankExport a pool Unmounts its datasets and marks the devices exported, ready to be moved to another system.
zpool export -f POOLForce an export Unmounts by force and exports even with a shared spare in use, at the risk of corruption.
zpool destroy -f tankDestroy a pool Removes tank with every dataset in it; -f unmounts active datasets by force.
zpool labelclear DEVICEWipe ZFS labels from a device Works only on a device outside any active pool; -f also accepts exported or foreign ones.
Adding and removing devices 13
Command What it does
zpool add tank mirror sda sdbAdd a mirror vdev Assumes the pool already consists of two-way mirrors; datasets can use the new space at once.
zpool add pool cache sdc sddAdd cache devices The cache fills gradually from main memory, which can take more than an hour.
zpool add -n POOL VDEVPreview adding a vdev Shows the layout the pool would have and changes nothing.
zpool attach tank sda sdbTurn a single disk into a mirror Attaches sdb to the existing device sda, so the pair forms a mirror.
zpool attach POOL VDEV NEW_DEVICEAttach a device to a vdev A mirror or plain disk gains a mirror side; a RAID-Z vdev starts a raidz expansion.
zpool detach POOL DEVICEDetach a device from a mirror Refused when no other valid replica exists; for a temporary removal use offline.
zpool remove tank mirror-2Remove a mirrored log device In the example mirror-2 is the log, and both of its sides leave the pool.
zpool remove tank mirror-1Remove a top-level data mirror Its data is evacuated first; the pool stays redundant but has less space.
zpool remove tank sdcRemove a hot spare Takes the spare sdc out of the pool for good.
zpool remove -s POOLCancel a device removal Applies while a top-level vdev is still being evacuated.
zpool split POOL NEWPOOLSplit mirrors into a new pool Every vdev must be a mirror; by default the last disk of each one goes to the new pool.
zpool split -R ROOT POOL NEWPOOLSplit and import the new pool The new pool is imported straight away with altroot set to the directory.
zpool online -e POOL DEVICEExpand onto a larger device Claims the added capacity; in a mirror or raidz every member has to be expanded first.
Replacing and repairing devices 10
Command What it does
zpool replace tank sda sddReplace a failed disk Resilvers onto sdd; a hot spare that had stepped in is freed again afterwards.
zpool replace POOL DEVICEReplace a disk in the same slot With one device name the new disk is taken to sit where the old one was, as after a physical swap.
zpool replace -w POOL DEVICE NEW-DEVICEReplace and wait for completion Returns only when the replacement has finished.
zpool offline POOL DEVICETake a device offline ZFS stops reading from and writing to the device; spares cannot be taken offline.
zpool offline -t POOL DEVICETake a device offline until reboot The device returns to its previous state at the next boot.
zpool online POOL DEVICEBring a device back online Like offline, it does not apply to hot spares.
zpool clear POOLClear device errors Resets the errors of all devices, or only of the devices named, and resumes a suspended pool.
zpool resilver POOLRestart a resilver A running resilver begins again and takes in drives queued for a deferred one.
zpool reopenReopen pool devices Acts on every pool unless pools are named.
zpool reguid POOLGive a pool a new GUID Every device of the pool has to be online and healthy beforehand.
Scrubbing and trimming 11
Command What it does
zpool scrub POOLStart or resume a scrub Reads all data to verify checksums and repairs damage on redundant vdevs; a paused scrub continues.
zpool scrub -p POOLPause a scrub Progress is saved, even across a restart; running zpool scrub again resumes it.
zpool scrub -s POOLStop a scrub
zpool scrub -w POOLScrub and wait for the end The command returns only once the scrub is complete.
zpool scrub -e POOLScrub only files with errors Rechecks what zpool status -v reports and requires the head_errlog feature.
systemctl enable [email protected] --nowSchedule a monthly scrub On systemd machines weekly and monthly timer units exist per pool; the pool name follows the @.
zpool trim POOLTrim free space now Tells the devices which blocks are unallocated, whatever the autotrim property says.
zpool trim -d POOLRun a secure TRIM The device then guarantees the trimmed blocks are erased; not every SSD supports it.
zpool trim -s POOLSuspend trimming Affects all eligible devices unless particular ones are listed.
systemctl enable [email protected] --nowSchedule a weekly TRIM The systemd timer unit takes the pool name, here rpool, after the @.
zpool initialize POOLInitialise unallocated space Writes to every unallocated region of the leaf data and log devices, or of the devices named.
Checkpoints and upkeep 9
Command What it does
zpool checkpoint poolCheckpoint the pool state Works like a pool-wide snapshot taken before a risky change; device removal, attach and detach are blocked meanwhile.
zpool import --rewind-to-checkpoint poolRewind to the checkpoint Export the pool first; the rewind also uses up the checkpoint, so it works once.
zpool checkpoint -d poolDiscard the checkpoint Run it once the risky procedure has gone well.
zpool upgradeList pools lacking features Shows pools without all supported features or still on a legacy version number.
zpool upgrade -vList supported legacy versions Feature flags themselves are described in zpool-features(7).
zpool upgrade -aEnable all features on all pools Afterwards the pools cannot be opened by systems without feature-flag support.
zpool syncFlush dirty data to disk Forces in-memory changes onto main pool storage for all pools, or for the pools named.
zpool wait POOLWait for background activity Blocks until scrub, resilver, trim and similar work in the pool has stopped.
zpool prefetch POOLPreload pool metadata into the ARC Loads the dedup and block-reference tables ahead of time; -t picks one type.
Pool properties 9
Command What it does
zpool get all POOLShow all pool properties Prints name, property, value and source columns for the pool.
zpool get PROPERTY POOLRead one pool property Several property names can be given as a comma-separated list.
zpool set PROPERTY=VALUE POOLSet a pool property zpoolprops(7) lists which properties can be set and their values.
ashift=ASHIFTPool sector size exponent A power-of-two exponent from 9 to 16; the default 0 lets ZFS detect the sector size.
autoexpand=on|offGrow the pool with its devices When on, the pool is resized after the underlying device grows; off is the default.
autoreplace=on|offReplace devices automatically When on, a new disk found in the slot of a former pool member is formatted and used.
autotrim=on|offTrim freed space automatically When on, recently freed space is trimmed periodically; off is the default.
cachefile=PATH|noneWhere the pool config is cached Pools in the default cache are imported at boot; none keeps the pool out of any cache.
listsnapshots=on|offShow snapshots in zfs list Decides whether zfs list prints snapshots when -t is not given; off by default.
Creating and removing datasets 14
Command What it does
zfs create pool/homeCreate a file system It is mounted at once, at the mountpoint it inherits from its parent.
zfs create -p FILESYSTEMCreate with missing parents Missing parent datasets are created and mounted too; an existing target is not an error.
zfs create -o PROPERTY=VALUE FILESYSTEMCreate with a property set Has the effect of zfs set at creation time; repeat -o for further properties.
zfs create -n FILESYSTEMDry-run a creation Nothing is created; with -v or -P it shows the properties that would apply.
zfs create -V SIZE VOLUMECreate a volume The volume appears as a block device under /dev/zvol and reserves its full size by default.
zfs create -s -V SIZE VOLUMECreate a sparse volume Skips the reservation an ordinary volume gets.
zfs destroy pool/project/legacyDestroy a dataset Fails while the dataset still has children or clones.
zfs destroy -r FILESYSTEMDestroy a dataset and its children
zfs destroy -R FILESYSTEMDestroy with dependent clones Also removes clones that live outside the hierarchy being destroyed.
zfs destroy -n -v FILESYSTEMPreview a destroy Prints what would be deleted and removes nothing.
zfs rename pool/project/production pool/project/legacyRename a dataset A file system that inherits a different mount point is unmounted and mounted again there.
zfs upgradeList outdated file systems Shows the file systems that are not on the newest on-disk version.
zfs upgrade -vList supported file system versions
zfs upgrade -aUpgrade all file systems Upgraded file systems can no longer be read by older ZFS releases.
Listing datasets 8
Command What it does
zfs listList file systems and volumes Columns are name, used, available, referenced and mountpoint; snapshots show only when listsnapshots is on.
zfs list -t snapshotList snapshots only snap is accepted as a short form of the type name.
zfs list -t allList every dataset type Adds snapshots and bookmarks to the file systems and volumes.
zfs list -r FILESYSTEMList a dataset and its children
zfs list -o PROPERTYChoose the list columns A comma-separated list of native or user properties; name stands for the dataset name.
zfs list -o spaceShow the space breakdown Shortcut for the columns that split used space between snapshots, the dataset, reservations and children.
zfs list -s PROPERTYSort the list by a property Ascending order; capital -S sorts the other way and both can be repeated.
zfs list -HList datasets for scripts No header line, and a single tab between fields.
Reading and setting properties 13
Sizes can be typed as exact numbers or with a suffix from B, K, M, G, T up to Z, as in quota=50G.
Command What it does
zfs get all pool/home/bobShow all properties of a dataset Each line gives the property, its value and the source it comes from.
zfs get -H -o value compression pool/home/bobPrint a bare property value No header and only the value column, which is what a script needs.
zfs get -r -s local -o name,property,value all pool/home/bobList locally set properties Recursive, and limited to values set on the datasets themselves rather than inherited or default ones.
zfs set compression=off pool/homeTurn compression off Every file system below pool/home that inherits the property follows.
zfs set compression=on pool/home/anneTurn compression on for one child An explicit value on the child overrides what the parent passes down.
zfs set com.example:department=12345 tank/accountingSet a user property User property names contain a colon and do not influence how ZFS behaves.
zfs inherit checksum pool/home/bob pool/home/anneInherit a property from the parent Clears the local checksum setting on both datasets.
zfs inherit -r PROPERTY FILESYSTEMInherit a property for all children
zfs inherit -S PROPERTY FILESYSTEMRevert to the received value Restores the value that arrived with zfs receive, when there is one.
compression=on|off|gzip|gzip-N|lz4|lzjb|zle|zstd|zstd-N|zstd-fast|zstd-fast-NCompression algorithm on selects the current default algorithm, lz4 where the lz4_compress feature is enabled.
recordsize=SIZESuggested file block size Meant for databases with fixed-size records; a power of two from 512 B to 128 KiB without large_blocks.
sync=standard|always|disabledHandling of synchronous writes always flushes every transaction before returning; disabled is fastest but ignores what applications ask for.
volsize=SIZELogical size of a volume Changing it changes the reservation as well; it must be a multiple of volblocksize.
Quotas and space accounting 10
Command What it does
zfs set quota=50G pool/home/bobSet a quota on a file system Caps pool/home/bob together with its descendants at 50 GB.
quota=SIZE|noneLimit a dataset and descendants A hard limit that counts snapshots and child datasets; it cannot be set on volumes.
refquota=SIZE|noneLimit a dataset alone Space taken by descendants and snapshots is left out of this limit.
reservation=SIZE|noneGuarantee space to a dataset tree Counts against the quotas and reservations of the parent datasets.
refreservation=SIZE|none|autoGuarantee space to a dataset alone Descendants are excluded; auto, valid on volumes only, makes the volume thick provisioned.
userquota@USER=SIZE|noneLimit space used by one user Enforcement can lag by several seconds, so a user may briefly exceed it.
zfs userspace FILESYSTEMShow space and quota per user A path is accepted too and stands for the file system that contains it.
zfs groupspace FILESYSTEMShow space and quota per group
zfs projectspace FILESYSTEMShow space and quota per project Projects are identified by number, so the name and type options of userspace do not apply.
zfs project -p ID -rs DIRECTORYAssign a project to a tree Gives the directory and everything below it the ID and the inherit flag, the usual base for tree quotas.
Mounting and sharing 14
Command What it does
zfs mountList mounted file systems With -j the list is printed as JSON.
zfs mount -aMount all file systems The same call runs automatically during boot when the system is configured for it.
zfs mount FILESYSTEMMount one file system Uses the path in its mountpoint property, which has to exist and be empty.
zfs mount -o OPTIONS FILESYSTEMMount with temporary options The comma-separated options hold for this mount only.
zfs unmount FILESYSTEMUnmount a file system The path of the mount point works in place of the dataset name.
zfs unmount -aUnmount all file systems Runs by itself as part of system shutdown.
zfs set mountpoint=/export/home pool/homeChange a mount point Children such as pool/home/bob inherit the new path automatically.
mountpoint=PATH|none|legacyWhere a file system mounts Changing it remounts the file system and inheriting children; legacy hands mounting to mount(8).
canmount=on|off|noautoWhether a file system may mount off makes zfs mount -a skip it; noauto allows explicit mounts only. Not inherited.
atime=on|offAccess-time updates Switching it off avoids writes caused by reads and can speed things up noticeably.
zfs share -aShare all file systems Shares what has sharenfs or sharesmb set; done automatically at boot.
zfs unshare -aStop sharing all file systems
zfs set sharenfs='[email protected] /16:[::1],root=neo' tank/homeShare over NFS with options Grants read-write access to a range of addresses and root access to the host neo.
sharenfs=on|off|OPTSNFS sharing of a file system With any value other than off, zfs share and zfs unshare manage the export.
Snapshots and rollback 9
zfs snap is an alias of zfs snapshot.
Command What it does
zfs snapshot pool/home/bob@yesterdayTake a snapshot Appears on demand under .zfs/snapshot in the top directory of pool/home/bob.
zfs snapshot -r pool/home@yesterdaySnapshot a whole tree Every descendant gets a snapshot with that name, all taken at the same moment.
zfs destroy -r pool/home@yesterdayDestroy a snapshot in every child Removes the snapshots of that name from pool/home and all descendants.
zfs rollback -r pool/home/anne@yesterdayRoll back past newer snapshots Discards everything changed since the snapshot and destroys the snapshots taken after it.
zfs rollback SNAPSHOTRoll back to the latest snapshot Without -r only the most recent snapshot is accepted.
zfs rename -r pool/users@today @yesterdayRename a snapshot recursively Renames the snapshot in every descendant dataset, as in the manual's rolling-snapshot scheme.
zfs diff -F tank/test@before tank/testShow changes since a snapshot Each path is marked -, +, M or R, and -F adds a column with the kind of file.
zfs diff SNAPSHOT SNAPSHOTCompare two snapshots The second snapshot has to be a later one of the same file system.
snapdir=disabled|hidden|visibleVisibility of the .zfs directory Controls the directory at the file system root that holds the snapshots; hidden is the default.
Snapshot holds 5
Command What it does
zfs hold TAG SNAPSHOTPlace a hold on a snapshot As long as the hold exists, zfs destroy on the snapshot fails with EBUSY.
zfs hold -r TAG SNAPSHOTHold a snapshot in all children
zfs holds SNAPSHOTList holds on a snapshot With -r the holds on the same-named snapshots of descendants are listed too.
zfs release TAG SNAPSHOTRelease a hold The tag has to exist on every snapshot named.
zfs destroy -d SNAPSHOTDefer destroying a snapshot A snapshot that is held or cloned is marked and destroyed automatically once that ends.
Clones and bookmarks 7
Command What it does
zfs clone pool/home/bob@yesterday pool/cloneClone a snapshot pool/clone is a writable file system that starts out with the snapshot's contents.
zfs clone -p SNAPSHOT FILESYSTEMClone and create parents Missing parent datasets of the target are created and mounted.
zfs clone -o PROPERTY=VALUE SNAPSHOT FILESYSTEMClone with a property set
zfs promote pool/project/betaPromote a clone Reverses the dependency, so the dataset it was cloned from can then be destroyed.
zfs bookmark rpool@snapshot rpool#bookmarkBookmark a snapshot A bookmark can replace the snapshot as the starting point of an incremental send.
zfs destroy FILESYSTEM|VOLUME#BOOKMARKDestroy a bookmark A # in front of the name marks a bookmark, as @ marks a snapshot.
zfs redact SNAPSHOT REDACTION_BOOKMARK REDACTION_SNAPSHOTCreate a redaction bookmark Records the blocks to withhold, for later use with zfs send --redact.
Sending and receiving 14
zfs recv is an alias of zfs receive.
Command What it does
zfs send pool/fs@a | ssh host zfs receive poolB/received/fs@aSend a full stream to another host poolB/received has to exist on the receiving machine and poolB/received/fs must not.
zfs send -i a pool/fs@b | ssh host zfs receive poolB/received/fsSend an incremental stream Transfers only the changes between snapshots a and b into the existing file system.
zfs send poolA/fsA/fsB@snap | ssh host zfs receive -d poolB/receivedReceive keeping the dataset path With -d the sent name minus its pool is appended, giving poolB/received/fsA/fsB@snap.
zfs send -R SNAPSHOTSend a replication stream Carries the file system with all descendants, their snapshots, clones and properties.
zfs send -I SNAPSHOT SNAPSHOTSend all intermediate snapshots One stream package covers every snapshot between the first and the second.
zfs send -i BOOKMARK SNAPSHOTSend incrementally from a bookmark This form of send accepts a bookmark as the incremental source.
zfs send -n -v SNAPSHOTEstimate a send Generates no stream and reports what would be sent.
zfs send -t RECEIVE_RESUME_TOKENResume an interrupted send The token is read from the receive_resume_token property on the receiving side.
zfs receive -F FILESYSTEMRoll back, then receive Reverts the target to its latest snapshot first, discarding changes made on it since.
zfs receive -s FILESYSTEMReceive with resume support An interrupted transfer keeps its partial state and can continue with zfs send -t.
zfs receive -A FILESYSTEMAbort a resumable receive Deletes the partial state that an interrupted receive -s left behind.
zfs receive -u FILESYSTEMReceive without mounting
zfs receive -o PROPERTY=VALUE FILESYSTEMOverride a property on receive Acts like zfs set run just before the receive.
zfs receive -x PROPERTY FILESYSTEMIgnore a property from the stream The received dataset behaves as though the stream had not carried that property.
Encryption 15
Command What it does
encryption=off|on|aes-128-ccm|aes-192-ccm|aes-256-ccm|aes-128-gcm|aes-192-gcm|aes-256-gcmEncryption cipher suite Has to be chosen when the dataset is created and is fixed afterwards; on currently means aes-256-gcm.
keyformat=raw|hex|passphraseForm of the encryption key Raw and hex keys are 32 random bytes; a passphrase is 8 to 512 bytes long.
keylocation=prompt|file:///absolute/file/path|https://address|http://addressWhere the key is read from prompt, the default, asks on the terminal or reads the key from standard input.
dd if=/dev/urandom bs=32 count=1 of=/path/to/output/keyGenerate a raw key file Writes the 32 random bytes that keyformat=raw expects.
zfs load-key FILESYSTEMLoad an encryption key Unlocks the dataset and the children that inherit its key, but mounts nothing.
zfs load-key -aLoad all keys Covers every encryption root in every imported pool.
zfs load-key -r FILESYSTEMLoad keys recursively
zfs mount -l FILESYSTEMMount and load keys Loads the key of each encryption root before mounting, prompting if keylocation is prompt.
zfs unload-key FILESYSTEMUnload an encryption key The dataset must not be open or mounted; afterwards it cannot be accessed.
zfs unload-key -aUnload all keys
zfs change-key FILESYSTEMChange the user key The current key must be loaded; the data itself is not re-encrypted.
zfs change-key -o keyformat=VALUE FILESYSTEMChange the key format The only way to alter keyformat or pbkdf2iters on an existing dataset.
zfs change-key -i FILESYSTEMInherit the parent's key Possible only on an encryption root whose parent is encrypted.
zfs send -w SNAPSHOTSend raw encrypted data Data leaves exactly as stored, so no key has to be loaded and the receiver cannot read it.
zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfileReceive into an encrypted dataset Encrypts an unencrypted stream on arrival; keylocation=prompt is ruled out because standard input carries the stream.
Delegated administration 12
Command What it does
zfs allow tank/cindysShow delegated permissions Lists what has been delegated on tank/cindys, split into local and descendent permissions.
zfs allow cindys create,destroy,mount,snapshot tank/cindysDelegate permissions to a user User cindys may then create, destroy, mount and snapshot datasets under tank/cindys.
zfs allow staff create,mount tank/usersDelegate permissions to a group Members of the group staff can create file systems in tank/users.
zfs allow -c destroy tank/usersGrant create-time permissions Whoever creates a file system below tank/users may destroy it, but nobody else's.
zfs allow -s @pset create,destroy,snapshot,mount tank/usersDefine a permission set Bundles four permissions under the name @pset for later grants.
zfs allow staff @pset tank/usersGrant a permission set Gives the group staff everything contained in @pset.
zfs allow cindys quota,reservation users/homeDelegate property changes Property names act as permissions: cindys may now set quotas and reservations.
zfs unallow staff snapshot tank/usersRemove a delegated permission Takes the snapshot permission away from the group staff.
zfs unallow -r USER PERM FILESYSTEMRemove a permission recursively Clears it on the file system and on all of its descendants.
zfs zone /proc/1234/ns/user tank/usersDelegate a dataset to a Linux namespace Linux only; the zoned property must be set for management from inside the namespace.
zfs jail JAILID FILESYSTEMAttach a dataset to a FreeBSD jail FreeBSD only; the jailed property must be set for management from inside the jail.
zfs unjail JAILID FILESYSTEMDetach a dataset from a jail
No row on this page matches that filter.
Notes
Pool first, then datasets zpool create tank mirror sda sdb mirror sdc sdd builds a pool from disks and a topology (mirror, raidz), and zpool status is the command you will run most often afterwards — it shows health, errors and any resilver or scrub in progress. zpool list shows capacity, zpool iostat -v pool 5 I/O per device every five seconds. Inside the pool, zfs create pool/home makes a dataset (a file system with its own properties) and zfs list shows the datasets with used and available space. Properties such as compression, recordsize and mountpoint are changed and read as in zfs set compression=on pool/home/anne and zfs get all pool/home/bob; zfs inherit checksum pool/home/bob pool/home/anne resets one to its parent's value.
Snapshots, clones and replication zfs snapshot pool/home/bob@yesterday is created almost instantly and takes no extra space until data changes, zfs rollback -r pool/home/anne@yesterday returns a dataset to a snapshot, and zfs diff -F tank/test@before tank/test lists what changed between a snapshot and now. zfs clone pool/home/bob@yesterday pool/clone makes a writable copy of a snapshot, and zfs promote pool/project/beta reverses the dependency so that the original can be destroyed. Replication is zfs send piped into zfs receive, incrementally between snapshots; zfs hold TAG SNAPSHOT keeps a snapshot from being destroyed while something still depends on it. zfs destroy removes datasets or snapshots and is the command to type slowly: zfs destroy -n -v FILESYSTEM shows what would go without deleting anything.
Maintenance and recovery zpool scrub POOL reads all data, verifies the checksums and repairs from redundancy; on systemd machines systemctl enable [email protected] --now schedules it. When a disk fails, zpool replace tank sda sdd swaps it and starts a resilver, zpool offline POOL DEVICE and zpool online POOL DEVICE take devices out and back, and zpool clear POOL resets the error counters once the cause is fixed. zpool export tank and zpool import tank move a pool between hosts cleanly. zpool history shows the commands that have been run on the pool, which settles "who changed that property". zpool trim POOL tells SSDs which blocks are free, and zpool checkpoint pool lets a risky change be rewound at the pool level with zpool import --rewind-to-checkpoint pool.
Questions
What is the difference between zpool and zfs? zpool manages the pool and its physical devices; zfs manages datasets, snapshots and properties inside the pool.
How do I check whether my pool is healthy? zpool status -x reports only the pools that have errors or are unavailable; plain zpool status lists every device. ONLINE means a device is working; DEGRADED means a device is offline, degraded or faulted while enough replicas remain to keep the pool running.
How do I back up a dataset to another machine? Take a snapshot, then pipe zfs send through ssh into zfs receive on the other host: zfs send pool/fs@a | ssh host zfs receive poolB/received/fs@a. Later sends can be incremental between snapshots: zfs send -i a pool/fs@b | ssh host zfs receive poolB/received/fs.
How often should I scrub? The manual names no interval, but on systemd machines it provides weekly and monthly timer units per pool, enabled with systemctl enable [email protected] --now. A scrub reads all data, verifies the checksums and repairs damage on redundant vdevs.
Sources and checks
54 more source pages zfs-set(8), with zfs get and zfs inherit — OpenZFS 2.4 manual pages Setting, reading and inheriting dataset properties zfs-snapshot(8) — OpenZFS 2.4 manual pages Creating snapshots zfs-rollback(8) — OpenZFS 2.4 manual pages Rolling a dataset back zfs-clone(8) — OpenZFS 2.4 manual pages Cloning snapshots zfs-promote(8) — OpenZFS 2.4 manual pages Promoting clones zfs-send(8), with zfs redact — OpenZFS 2.4 manual pages Send streams and redaction bookmarks zfs-receive(8) — OpenZFS 2.4 manual pages Receiving streams zfs-mount(8), with zfs unmount — OpenZFS 2.4 manual pages Mounting and unmounting file systems zfs-share(8), with zfs unshare — OpenZFS 2.4 manual pages Sharing file systems zfs-hold(8), with zfs holds and zfs release — OpenZFS 2.4 manual pages Snapshot holds zfs-allow(8), with zfs unallow — OpenZFS 2.4 manual pages Delegated permissions zfs-load-key(8), with unload-key and change-key — OpenZFS 2.4 manual pages Encryption keys zfs-diff(8) — OpenZFS 2.4 manual pages Differences between snapshots zfs-bookmark(8) — OpenZFS 2.4 manual pages Bookmarks zfs-userspace(8), with groupspace and projectspace — OpenZFS 2.4 manual pages Space and quota reports zfs-upgrade(8) — OpenZFS 2.4 manual pages File system versions zfs-wait(8) — OpenZFS 2.4 manual pages Waiting for file system activity zfs-project(8) — OpenZFS 2.4 manual pages Project IDs zpool-create(8) — OpenZFS 2.4 manual pages Creating pools zpool-status(8) — OpenZFS 2.4 manual pages Pool health report zpool-list(8) — OpenZFS 2.4 manual pages Pool list and capacity zpool-iostat(8) — OpenZFS 2.4 manual pages Pool I/O statistics zpool-import(8) — OpenZFS 2.4 manual pages Importing pools zpool-export(8) — OpenZFS 2.4 manual pages Exporting pools zpool-scrub(8) — OpenZFS 2.4 manual pages Scrubs and scrub timers zpool-add(8) — OpenZFS 2.4 manual pages Adding vdevs zpool-attach(8) — OpenZFS 2.4 manual pages Attaching devices zpool-detach(8) — OpenZFS 2.4 manual pages Detaching mirror devices zpool-replace(8) — OpenZFS 2.4 manual pages Replacing devices zpool-remove(8) — OpenZFS 2.4 manual pages Removing devices zpool-offline(8), with zpool online — OpenZFS 2.4 manual pages Taking devices offline and online zpool-clear(8) — OpenZFS 2.4 manual pages Clearing device errors zpool-destroy(8) — OpenZFS 2.4 manual pages Destroying pools zpool-upgrade(8) — OpenZFS 2.4 manual pages Pool features and versions zpool-history(8) — OpenZFS 2.4 manual pages Pool command history zpool-events(8) — OpenZFS 2.4 manual pages Kernel events zpool-trim(8) — OpenZFS 2.4 manual pages TRIM and trim timers zpool-resilver(8) — OpenZFS 2.4 manual pages Resilvering zpool-initialize(8) — OpenZFS 2.4 manual pages Initialising devices zpool-split(8) — OpenZFS 2.4 manual pages Splitting mirrored pools zpool-get(8), with zpool set — OpenZFS 2.4 manual pages Reading and setting pool properties zpool-labelclear(8) — OpenZFS 2.4 manual pages Clearing device labels zpool-sync(8) — OpenZFS 2.4 manual pages Flushing pools zpool-wait(8) — OpenZFS 2.4 manual pages Waiting for pool activity zpool-reopen(8) — OpenZFS 2.4 manual pages Reopening devices zpool-reguid(8) — OpenZFS 2.4 manual pages Pool GUID zpool-prefetch(8) — OpenZFS 2.4 manual pages zfsprops(7) — OpenZFS 2.4 manual pages Dataset property definitions zpoolprops(7) — OpenZFS 2.4 manual pages Pool property definitions zpoolconcepts(7) — OpenZFS 2.4 manual pages Vdev types, hot spares, cache devices and pool checkpoints zfs-program(8) — OpenZFS 2.4 manual pages Channel programs zfs-jail(8) — OpenZFS 2.4 manual pages FreeBSD jails zfs-rewrite(8) — OpenZFS 2.4 manual pages Rewriting files zfs-zone(8) — OpenZFS 2.4 manual pages Linux user namespaces
Every row on this page was matched to a line in the documentation above on 6 October 2026 . A binding that could not be found there is not listed.
18 rows from the earlier version of this page were removed in that check: duplicates, and bindings the documentation does not list or lists differently.
Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.