ZFS commands

OpenZFS is administered with two commands: zpool for storage pools and their disks, zfs for the datasets, snapshots and properties inside a pool. The rows are command lines from the OpenZFS 2.4 manual pages, grouped by task. Lower-case names such as tank or pool/home come from the manual's examples; capitals such as POOL or SNAPSHOT are placeholders, and a row like atime=on|off gives the values a property accepts. Environment variables and the debugging tools are left out.

222 commands in 20 sections. Checked row by row against zfs(8) on . Edited by Jay.

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.

CommandWhat it does
zpool create tank raidz sda sdb sdc sdd sde sdfCreate a RAID-Z poolSix 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 mirrorsEach mirror keyword opens a new group, giving two vdevs of two disks here.
zpool create tank sda1 sdb2Create a pool from partitionsThe two partitions form a pool that has no redundancy.
zpool create tank /path/to/file/a /path/to/file/bCreate a file-backed poolPlain files serve as devices, which the manual suggests for experiments only.
zpool create tank mirror sda sdb spare sdcCreate a mirror with a hot sparesdc 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 logTwo data mirrors plus a mirrored pair holding the separate intent log.
zpool create pool sda sdb cache sdc sddCreate a pool plus cache disksCache 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 layoutPrints the layout that would result and leaves the disks untouched.
zpool create -m MOUNTPOINT POOL VDEVSet the root mount pointTakes an absolute path, legacy or none in place of the default /POOL.
zpool create -o PROPERTY=VALUE POOL VDEVSet a pool property at creationAny 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 propertyCapital -O applies a dataset property to the root file system, where children inherit it.

Checking pool health 15

CommandWhat it does
zpool statusShow pool healthLists each pool with its device states and, during a scrub or resilver, the percentage done.
zpool status -xShow only troubled poolsRestricts the report to pools with errors or that are unavailable; outdated-format warnings do not count.
zpool status -vList data errors in detailAdds the full list of data errors recorded since the last completed scrub.
zpool status -LShow real device namesResolves symbolic links so the current block device name appears, whichever /dev/disk path opened it.
zpool status -c vendor,model,sizeAdd script columns to statusRuns the named scripts on every vdev and appends their output as extra columns.
zpool listList pools with capacityOne line per pool: size, allocated and free space, fragmentation, capacity and health.
zpool list -v dataList space per vdevBreaks the figures of pool data down by vdev and disk, including capacity not yet usable (EXPANDSZ).
zpool list -HList pools for scriptsLeaves out the header line and puts one tab between fields.
zpool iostatShow pool I/O statisticsReports logical I/O, which can differ from the physical figures of iostat(1).
zpool iostat -v pool 5Watch I/O per vdevPrints a line for every vdev, cache devices included, and repeats every five seconds.
zpool iostat -lAdd average latency columnsSplits waiting time into total, disk and per-queue averages.
zpool historyShow pool command historyCovers all pools when no pool is named.
zpool history -lShow history in long formatEach record also names the user, the host and the zone that ran the command.
zpool eventsList kernel ZFS eventsThese 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

CommandWhat it does
zpool importList importable poolsSearches the devices and prints every exported pool it finds with its id, state and layout.
zpool import tankImport a pool by nameThe numeric identifier shown in the listing can be given instead of the name.
zpool import POOL NEWPOOLImport under a new nameThe second name replaces the one the pool was exported with.
zpool import -aImport every pool found
zpool import -a -NImport without mountingBrings the pools in but mounts none of their file systems.
zpool import -d DIRSearch a directory for poolsLooks for devices or files in that directory; the option may be repeated.
zpool import -f POOLForce an importNeeded when the pool was not exported first and so still looks active.
zpool import -R ROOT POOLImport under an alternate rootSets altroot to the directory and cachefile to none for this import.
zpool import -F POOLRecover a damaged poolThrows away the last few transactions to make the pool importable; their data cannot be brought back.
zpool import -DList destroyed poolsTo bring one back, name it and add -f as well.
zpool export tankExport a poolUnmounts its datasets and marks the devices exported, ready to be moved to another system.
zpool export -f POOLForce an exportUnmounts by force and exports even with a shared spare in use, at the risk of corruption.
zpool destroy -f tankDestroy a poolRemoves tank with every dataset in it; -f unmounts active datasets by force.
zpool labelclear DEVICEWipe ZFS labels from a deviceWorks only on a device outside any active pool; -f also accepts exported or foreign ones.

Adding and removing devices 13

CommandWhat it does
zpool add tank mirror sda sdbAdd a mirror vdevAssumes the pool already consists of two-way mirrors; datasets can use the new space at once.
zpool add pool cache sdc sddAdd cache devicesThe cache fills gradually from main memory, which can take more than an hour.
zpool add -n POOL VDEVPreview adding a vdevShows the layout the pool would have and changes nothing.
zpool attach tank sda sdbTurn a single disk into a mirrorAttaches sdb to the existing device sda, so the pair forms a mirror.
zpool attach POOL VDEV NEW_DEVICEAttach a device to a vdevA mirror or plain disk gains a mirror side; a RAID-Z vdev starts a raidz expansion.
zpool detach POOL DEVICEDetach a device from a mirrorRefused when no other valid replica exists; for a temporary removal use offline.
zpool remove tank mirror-2Remove a mirrored log deviceIn the example mirror-2 is the log, and both of its sides leave the pool.
zpool remove tank mirror-1Remove a top-level data mirrorIts data is evacuated first; the pool stays redundant but has less space.
zpool remove tank sdcRemove a hot spareTakes the spare sdc out of the pool for good.
zpool remove -s POOLCancel a device removalApplies while a top-level vdev is still being evacuated.
zpool split POOL NEWPOOLSplit mirrors into a new poolEvery 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 poolThe new pool is imported straight away with altroot set to the directory.
zpool online -e POOL DEVICEExpand onto a larger deviceClaims the added capacity; in a mirror or raidz every member has to be expanded first.

Replacing and repairing devices 10

CommandWhat it does
zpool replace tank sda sddReplace a failed diskResilvers onto sdd; a hot spare that had stepped in is freed again afterwards.
zpool replace POOL DEVICEReplace a disk in the same slotWith 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 completionReturns only when the replacement has finished.
zpool offline POOL DEVICETake a device offlineZFS stops reading from and writing to the device; spares cannot be taken offline.
zpool offline -t POOL DEVICETake a device offline until rebootThe device returns to its previous state at the next boot.
zpool online POOL DEVICEBring a device back onlineLike offline, it does not apply to hot spares.
zpool clear POOLClear device errorsResets the errors of all devices, or only of the devices named, and resumes a suspended pool.
zpool resilver POOLRestart a resilverA running resilver begins again and takes in drives queued for a deferred one.
zpool reopenReopen pool devicesActs on every pool unless pools are named.
zpool reguid POOLGive a pool a new GUIDEvery device of the pool has to be online and healthy beforehand.

Scrubbing and trimming 11

CommandWhat it does
zpool scrub POOLStart or resume a scrubReads all data to verify checksums and repairs damage on redundant vdevs; a paused scrub continues.
zpool scrub -p POOLPause a scrubProgress 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 endThe command returns only once the scrub is complete.
zpool scrub -e POOLScrub only files with errorsRechecks what zpool status -v reports and requires the head_errlog feature.
systemctl enable [email protected] --nowSchedule a monthly scrubOn systemd machines weekly and monthly timer units exist per pool; the pool name follows the @.
zpool trim POOLTrim free space nowTells the devices which blocks are unallocated, whatever the autotrim property says.
zpool trim -d POOLRun a secure TRIMThe device then guarantees the trimmed blocks are erased; not every SSD supports it.
zpool trim -s POOLSuspend trimmingAffects all eligible devices unless particular ones are listed.
systemctl enable [email protected] --nowSchedule a weekly TRIMThe systemd timer unit takes the pool name, here rpool, after the @.
zpool initialize POOLInitialise unallocated spaceWrites to every unallocated region of the leaf data and log devices, or of the devices named.

Checkpoints and upkeep 9

CommandWhat it does
zpool checkpoint poolCheckpoint the pool stateWorks 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 checkpointExport the pool first; the rewind also uses up the checkpoint, so it works once.
zpool checkpoint -d poolDiscard the checkpointRun it once the risky procedure has gone well.
zpool upgradeList pools lacking featuresShows pools without all supported features or still on a legacy version number.
zpool upgrade -vList supported legacy versionsFeature flags themselves are described in zpool-features(7).
zpool upgrade -aEnable all features on all poolsAfterwards the pools cannot be opened by systems without feature-flag support.
zpool syncFlush dirty data to diskForces in-memory changes onto main pool storage for all pools, or for the pools named.
zpool wait POOLWait for background activityBlocks until scrub, resilver, trim and similar work in the pool has stopped.
zpool prefetch POOLPreload pool metadata into the ARCLoads the dedup and block-reference tables ahead of time; -t picks one type.

Pool properties 9

CommandWhat it does
zpool get all POOLShow all pool propertiesPrints name, property, value and source columns for the pool.
zpool get PROPERTY POOLRead one pool propertySeveral property names can be given as a comma-separated list.
zpool set PROPERTY=VALUE POOLSet a pool propertyzpoolprops(7) lists which properties can be set and their values.
ashift=ASHIFTPool sector size exponentA power-of-two exponent from 9 to 16; the default 0 lets ZFS detect the sector size.
autoexpand=on|offGrow the pool with its devicesWhen on, the pool is resized after the underlying device grows; off is the default.
autoreplace=on|offReplace devices automaticallyWhen on, a new disk found in the slot of a former pool member is formatted and used.
autotrim=on|offTrim freed space automaticallyWhen on, recently freed space is trimmed periodically; off is the default.
cachefile=PATH|noneWhere the pool config is cachedPools in the default cache are imported at boot; none keeps the pool out of any cache.
listsnapshots=on|offShow snapshots in zfs listDecides whether zfs list prints snapshots when -t is not given; off by default.

Creating and removing datasets 14

CommandWhat it does
zfs create pool/homeCreate a file systemIt is mounted at once, at the mountpoint it inherits from its parent.
zfs create -p FILESYSTEMCreate with missing parentsMissing parent datasets are created and mounted too; an existing target is not an error.
zfs create -o PROPERTY=VALUE FILESYSTEMCreate with a property setHas the effect of zfs set at creation time; repeat -o for further properties.
zfs create -n FILESYSTEMDry-run a creationNothing is created; with -v or -P it shows the properties that would apply.
zfs create -V SIZE VOLUMECreate a volumeThe volume appears as a block device under /dev/zvol and reserves its full size by default.
zfs create -s -V SIZE VOLUMECreate a sparse volumeSkips the reservation an ordinary volume gets.
zfs destroy pool/project/legacyDestroy a datasetFails while the dataset still has children or clones.
zfs destroy -r FILESYSTEMDestroy a dataset and its children
zfs destroy -R FILESYSTEMDestroy with dependent clonesAlso removes clones that live outside the hierarchy being destroyed.
zfs destroy -n -v FILESYSTEMPreview a destroyPrints what would be deleted and removes nothing.
zfs rename pool/project/production pool/project/legacyRename a datasetA file system that inherits a different mount point is unmounted and mounted again there.
zfs upgradeList outdated file systemsShows the file systems that are not on the newest on-disk version.
zfs upgrade -vList supported file system versions
zfs upgrade -aUpgrade all file systemsUpgraded file systems can no longer be read by older ZFS releases.

Listing datasets 8

CommandWhat it does
zfs listList file systems and volumesColumns are name, used, available, referenced and mountpoint; snapshots show only when listsnapshots is on.
zfs list -t snapshotList snapshots onlysnap is accepted as a short form of the type name.
zfs list -t allList every dataset typeAdds snapshots and bookmarks to the file systems and volumes.
zfs list -r FILESYSTEMList a dataset and its children
zfs list -o PROPERTYChoose the list columnsA comma-separated list of native or user properties; name stands for the dataset name.
zfs list -o spaceShow the space breakdownShortcut for the columns that split used space between snapshots, the dataset, reservations and children.
zfs list -s PROPERTYSort the list by a propertyAscending order; capital -S sorts the other way and both can be repeated.
zfs list -HList datasets for scriptsNo 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.

CommandWhat it does
zfs get all pool/home/bobShow all properties of a datasetEach line gives the property, its value and the source it comes from.
zfs get -H -o value compression pool/home/bobPrint a bare property valueNo 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 propertiesRecursive, and limited to values set on the datasets themselves rather than inherited or default ones.
zfs set compression=off pool/homeTurn compression offEvery file system below pool/home that inherits the property follows.
zfs set compression=on pool/home/anneTurn compression on for one childAn explicit value on the child overrides what the parent passes down.
zfs set com.example:department=12345 tank/accountingSet a user propertyUser 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 parentClears 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 valueRestores 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 algorithmon selects the current default algorithm, lz4 where the lz4_compress feature is enabled.
recordsize=SIZESuggested file block sizeMeant 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 writesalways flushes every transaction before returning; disabled is fastest but ignores what applications ask for.
volsize=SIZELogical size of a volumeChanging it changes the reservation as well; it must be a multiple of volblocksize.

Quotas and space accounting 10

CommandWhat it does
zfs set quota=50G pool/home/bobSet a quota on a file systemCaps pool/home/bob together with its descendants at 50 GB.
quota=SIZE|noneLimit a dataset and descendantsA hard limit that counts snapshots and child datasets; it cannot be set on volumes.
refquota=SIZE|noneLimit a dataset aloneSpace taken by descendants and snapshots is left out of this limit.
reservation=SIZE|noneGuarantee space to a dataset treeCounts against the quotas and reservations of the parent datasets.
refreservation=SIZE|none|autoGuarantee space to a dataset aloneDescendants are excluded; auto, valid on volumes only, makes the volume thick provisioned.
userquota@USER=SIZE|noneLimit space used by one userEnforcement can lag by several seconds, so a user may briefly exceed it.
zfs userspace FILESYSTEMShow space and quota per userA 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 projectProjects 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 treeGives the directory and everything below it the ID and the inherit flag, the usual base for tree quotas.

Mounting and sharing 14

CommandWhat it does
zfs mountList mounted file systemsWith -j the list is printed as JSON.
zfs mount -aMount all file systemsThe same call runs automatically during boot when the system is configured for it.
zfs mount FILESYSTEMMount one file systemUses the path in its mountpoint property, which has to exist and be empty.
zfs mount -o OPTIONS FILESYSTEMMount with temporary optionsThe comma-separated options hold for this mount only.
zfs unmount FILESYSTEMUnmount a file systemThe path of the mount point works in place of the dataset name.
zfs unmount -aUnmount all file systemsRuns by itself as part of system shutdown.
zfs set mountpoint=/export/home pool/homeChange a mount pointChildren such as pool/home/bob inherit the new path automatically.
mountpoint=PATH|none|legacyWhere a file system mountsChanging it remounts the file system and inheriting children; legacy hands mounting to mount(8).
canmount=on|off|noautoWhether a file system may mountoff makes zfs mount -a skip it; noauto allows explicit mounts only. Not inherited.
atime=on|offAccess-time updatesSwitching it off avoids writes caused by reads and can speed things up noticeably.
zfs share -aShare all file systemsShares 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 optionsGrants read-write access to a range of addresses and root access to the host neo.
sharenfs=on|off|OPTSNFS sharing of a file systemWith 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.

CommandWhat it does
zfs snapshot pool/home/bob@yesterdayTake a snapshotAppears on demand under .zfs/snapshot in the top directory of pool/home/bob.
zfs snapshot -r pool/home@yesterdaySnapshot a whole treeEvery descendant gets a snapshot with that name, all taken at the same moment.
zfs destroy -r pool/home@yesterdayDestroy a snapshot in every childRemoves the snapshots of that name from pool/home and all descendants.
zfs rollback -r pool/home/anne@yesterdayRoll back past newer snapshotsDiscards everything changed since the snapshot and destroys the snapshots taken after it.
zfs rollback SNAPSHOTRoll back to the latest snapshotWithout -r only the most recent snapshot is accepted.
zfs rename -r pool/users@today @yesterdayRename a snapshot recursivelyRenames 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 snapshotEach path is marked -, +, M or R, and -F adds a column with the kind of file.
zfs diff SNAPSHOT SNAPSHOTCompare two snapshotsThe second snapshot has to be a later one of the same file system.
snapdir=disabled|hidden|visibleVisibility of the .zfs directoryControls the directory at the file system root that holds the snapshots; hidden is the default.

Snapshot holds 5

CommandWhat it does
zfs hold TAG SNAPSHOTPlace a hold on a snapshotAs 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 snapshotWith -r the holds on the same-named snapshots of descendants are listed too.
zfs release TAG SNAPSHOTRelease a holdThe tag has to exist on every snapshot named.
zfs destroy -d SNAPSHOTDefer destroying a snapshotA snapshot that is held or cloned is marked and destroyed automatically once that ends.

Clones and bookmarks 7

CommandWhat it does
zfs clone pool/home/bob@yesterday pool/cloneClone a snapshotpool/clone is a writable file system that starts out with the snapshot's contents.
zfs clone -p SNAPSHOT FILESYSTEMClone and create parentsMissing 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 cloneReverses the dependency, so the dataset it was cloned from can then be destroyed.
zfs bookmark rpool@snapshot rpool#bookmarkBookmark a snapshotA bookmark can replace the snapshot as the starting point of an incremental send.
zfs destroy FILESYSTEM|VOLUME#BOOKMARKDestroy a bookmarkA # in front of the name marks a bookmark, as @ marks a snapshot.
zfs redact SNAPSHOT REDACTION_BOOKMARK REDACTION_SNAPSHOTCreate a redaction bookmarkRecords the blocks to withhold, for later use with zfs send --redact.

Sending and receiving 14

zfs recv is an alias of zfs receive.

CommandWhat it does
zfs send pool/fs@a | ssh host zfs receive poolB/received/fs@aSend a full stream to another hostpoolB/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 streamTransfers 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 pathWith -d the sent name minus its pool is appended, giving poolB/received/fsA/fsB@snap.
zfs send -R SNAPSHOTSend a replication streamCarries the file system with all descendants, their snapshots, clones and properties.
zfs send -I SNAPSHOT SNAPSHOTSend all intermediate snapshotsOne stream package covers every snapshot between the first and the second.
zfs send -i BOOKMARK SNAPSHOTSend incrementally from a bookmarkThis form of send accepts a bookmark as the incremental source.
zfs send -n -v SNAPSHOTEstimate a sendGenerates no stream and reports what would be sent.
zfs send -t RECEIVE_RESUME_TOKENResume an interrupted sendThe token is read from the receive_resume_token property on the receiving side.
zfs receive -F FILESYSTEMRoll back, then receiveReverts the target to its latest snapshot first, discarding changes made on it since.
zfs receive -s FILESYSTEMReceive with resume supportAn interrupted transfer keeps its partial state and can continue with zfs send -t.
zfs receive -A FILESYSTEMAbort a resumable receiveDeletes 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 receiveActs like zfs set run just before the receive.
zfs receive -x PROPERTY FILESYSTEMIgnore a property from the streamThe received dataset behaves as though the stream had not carried that property.

Encryption 15

CommandWhat it does
encryption=off|on|aes-128-ccm|aes-192-ccm|aes-256-ccm|aes-128-gcm|aes-192-gcm|aes-256-gcmEncryption cipher suiteHas 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 keyRaw 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 fromprompt, 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 fileWrites the 32 random bytes that keyformat=raw expects.
zfs load-key FILESYSTEMLoad an encryption keyUnlocks the dataset and the children that inherit its key, but mounts nothing.
zfs load-key -aLoad all keysCovers every encryption root in every imported pool.
zfs load-key -r FILESYSTEMLoad keys recursively
zfs mount -l FILESYSTEMMount and load keysLoads the key of each encryption root before mounting, prompting if keylocation is prompt.
zfs unload-key FILESYSTEMUnload an encryption keyThe dataset must not be open or mounted; afterwards it cannot be accessed.
zfs unload-key -aUnload all keys
zfs change-key FILESYSTEMChange the user keyThe current key must be loaded; the data itself is not re-encrypted.
zfs change-key -o keyformat=VALUE FILESYSTEMChange the key formatThe only way to alter keyformat or pbkdf2iters on an existing dataset.
zfs change-key -i FILESYSTEMInherit the parent's keyPossible only on an encryption root whose parent is encrypted.
zfs send -w SNAPSHOTSend raw encrypted dataData 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 datasetEncrypts an unencrypted stream on arrival; keylocation=prompt is ruled out because standard input carries the stream.

Delegated administration 12

CommandWhat it does
zfs allow tank/cindysShow delegated permissionsLists 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 userUser cindys may then create, destroy, mount and snapshot datasets under tank/cindys.
zfs allow staff create,mount tank/usersDelegate permissions to a groupMembers of the group staff can create file systems in tank/users.
zfs allow -c destroy tank/usersGrant create-time permissionsWhoever 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 setBundles four permissions under the name @pset for later grants.
zfs allow staff @pset tank/usersGrant a permission setGives the group staff everything contained in @pset.
zfs allow cindys quota,reservation users/homeDelegate property changesProperty names act as permissions: cindys may now set quotas and reservations.
zfs unallow staff snapshot tank/usersRemove a delegated permissionTakes the snapshot permission away from the group staff.
zfs unallow -r USER PERM FILESYSTEMRemove a permission recursivelyClears it on the file system and on all of its descendants.
zfs zone /proc/1234/ns/user tank/usersDelegate a dataset to a Linux namespaceLinux only; the zoned property must be set for management from inside the namespace.
zfs jail JAILID FILESYSTEMAttach a dataset to a FreeBSD jailFreeBSD only; the jailed property must be set for management from inside the jail.
zfs unjail JAILID FILESYSTEMDetach a dataset from a jail

Help, versions and other tools 9

CommandWhat it does
zfs -?Show zfs help
zfs --versionShow the zfs version-V is the short form of the same option.
zfs versionShow userland and module versionsPrints the version of the zfs utility and of the kernel module; -j gives JSON.
zpool -?Show zpool help
zpool --versionShow the zpool versionThe short form of this option is -V.
zpool versionShow zpool and module versionsCovers the zpool utility and the kernel module; add -j for JSON output.
zfs wait FILESYSTEMWait for file system activityReturns when the internal delete queue has emptied, or at once if nothing is pending.
zfs program POOL SCRIPTRun a channel programExecutes a Lua script atomically against one pool; root privileges are required.
zfs rewrite FILERewrite file blocks in placeBlocks are written again unchanged, so new settings such as compression or checksum take effect.

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

Every row on this page was matched to a line in the documentation above on . 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.