Skip to content

Warn that the ZFS Test Suite destroys pools, and stop suggesting -x #647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gmelikov merged 1 commit into from
Aug 24, 2026
Merged

Warn that the ZFS Test Suite destroys pools, and stop suggesting -x #647

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions docs/Developer Resources/Building ZFS.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,9 @@ the ZFS and SPL source in the traditional autotools fashion.
Install
^^^^^^^

You can run ``zfs-tests.sh`` without installing ZFS, see below. If you
You can run ``zfs-tests.sh`` without installing ZFS, see
:ref:`below <running-zloopsh-and-zfs-testssh>` - but read the warning there
first, as the test suite is destructive. If you
have reason to install ZFS after building it, pay attention to how your
distribution handles kernel modules. On Ubuntu, for example, the modules
from this repository install in the ``extra`` kernel module path, which
Expand All @@ -172,6 +174,13 @@ the kernel modules with ``sudo make -C modules/ install``.
Running zloop.sh and zfs-tests.sh
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. danger::
These are developer tools for validating changes to OpenZFS, not a way
for end users to check an installation. They are destructive: they
create and destroy pools, load and unload the kernel modules, add users
and groups, and write to ``/var/tmp``. Run them only on a dedicated test
machine or VM, never on a system holding data you care about.

If you wish to run the ZFS Test Suite (ZTS), then ``ksh`` and a few
additional utilities must be installed.

Expand Down Expand Up @@ -250,7 +259,15 @@ directory designed to aid developers working with in-tree builds.

::

./scripts/zfs-tests.sh -vx
./scripts/zfs-tests.sh -v

.. danger::
The **-x** option cleans up leftovers from a previous run by removing
test pools, device-mapper and loopback devices, and files. It cannot
always tell those apart from resources that have nothing to do with
testing, so it can destroy an unrelated pool - an exported one, or one
with no mounted datasets. Only use it on a machine dedicated to running
the test suite.

**tip:** The **delegate** tests will be skipped unless group read
permission is set on the zfs directory and its parents.
Loading