ZPool Cheatsheet

THE PRACTICAL GUIDE · NORMANDIN SYSTEMS

Get more from ZPool Cheatsheet

ZPool Cheatsheet summarizes common OpenZFS pool inspection and management commands. A pool groups storage devices into a ZFS storage structure, and its health depends on the underlying topology and device state. Read-only status commands are useful starting points; creation, replacement, removal, or destruction require a precise understanding of the actual storage layout. A cheatsheet works best as a memory aid while you practice a concrete task. Read the command or syntax together with its arguments, placeholders, and surrounding context. Similar-looking options can have very different meanings, and an example written for one platform or version may need adjustment elsewhere. Keep the reference beside a small test case, use read-only examples first when possible, and check the relevant help output before applying an unfamiliar command to valuable files or a running service.

Guide updated October 13, 2026

How to use this tool

1. Identify the operation you want to perform and find the matching section of the reference. Read the whole example before copying any part of it.
2. Begin with status inspection and identify the pool and devices before considering any command that changes storage state.
3. Review the example below and compare its expected behavior with a small sample of your own input before continuing.
4. Try the adapted example on a small test case, compare the result with the explanation, and save the command with a note about the context in which it works.

SEE IT IN PRACTICE

A worked example

zpool status

A report of pool health, device topology, and relevant errors

The report helps establish which pool and device are involved in an issue, rather than assuming a device name from memory.

Pool topology determines the impact of a command

A pool's layout and redundancy influence which device operations are possible and what failures can be tolerated. Device names can change or be confused with similar hardware, so inspect stable identifiers and the actual topology before any modification. Begin with status output and understand which component reports an error. A command that is appropriate for one arrangement may be unsafe or unsupported for another, making a generic example insufficient as an operational plan.

Health reports need surrounding evidence

A status report can reveal errors, degraded devices, or maintenance activity, but interpreting the cause may require system logs, device diagnostics, and knowledge of recent changes. Do not respond to an unfamiliar state by issuing broad destructive commands from a reference. Preserve a verified backup and establish the intended recovery procedure for the actual pool. Read-only inspection is a useful first step, while replacement, creation, removal, and destruction deserve a separate, precise review of their consequences and target identifiers.

When this tool is useful

• Read a pool-health report
• Understand storage topology terminology
• Locate a read-only OpenZFS inspection command

Tips for a better result

• Confirm pool names, device identifiers, redundancy, and backup status, and investigate reported errors with the system's own documentation.
• Replace example paths, identifiers, and names deliberately. Copying a reference command unchanged can target a different file, branch, service, or environment from the one you intended.
• Keep the source and the settings used for this result together. That makes a later comparison or correction easier, especially when another person needs to reproduce the same outcome.

Frequently asked questions