ZFS Metadata Eraser

erase-zfs-metadata.sh permanently overwrites disk metadata that can identify a device as a ZFS vdev. It is intended for decommissioning or repurposing a device after it has been cleanly removed from its pool.

What It Erases

The script performs 10 overwrite passes over the first 4 MiB and the last 4 MiB of the target block device. It uses zeroes by default and can use random data when requested. These regions include:

MBR data and GPT primary partition table at the beginning of a disk.
GPT backup partition table at the end of a disk.
The four conventional ZFS vdev-label regions, including their redundant copies at both ends of the device.

It does not overwrite the entire device. Data outside those metadata regions may remain recoverable.

Requirements

Linux with Bash.
Root privileges.
blockdev, dd, findmnt, lsblk, and the ZFS zpool command.
A target device of at least 8 MiB that is not mounted and is not part of an imported ZFS pool.

Use

First, verify the target device carefully:

lsblk --output NAME,SIZE,TYPE,MOUNTPOINTS
zpool status -P

Then make the script executable and run it with the full block-device path:

chmod +x erase-zfs-metadata.sh
sudo ./erase-zfs-metadata.sh /dev/sdX

Use --source random to overwrite with data from /dev/urandom instead of the default zeroes:

sudo ./erase-zfs-metadata.sh --source random /dev/sdX

The only accepted source values are zeroes and random. Random overwrites are typically slower and do not erase additional parts of the device; both modes overwrite the same first and last 4 MiB regions.

Replace /dev/sdX with the actual device, such as /dev/sdb, /dev/nvme0n1, or a device-mapper path. Do not use the disk containing the running system.

The script displays target details and requires this exact confirmation before it writes anything:

ERASE /dev/sdX

Safety Behavior

Before overwriting, the script refuses to run when:

The supplied path is not a block device.
The device itself is mounted.
A child partition of the device is mounted.
zpool status -P shows the device in an imported pool.
The device is smaller than 8 MiB.

These checks reduce common mistakes but are not a substitute for verifying the device identity yourself. The operation is destructive and cannot be undone.

Prepare a ZFS Device

For a device that belongs to a pool, first use the appropriate ZFS procedure, such as replacing or detaching the vdev, then export the pool if necessary. Confirm the target no longer appears in zpool status -P before running the eraser. Do not use this utility to remove a live vdev from an active pool.

Verify

After completion, inspect the device for residual filesystem or partition signatures:

sudo wipefs --all --no-act /dev/sdX
sudo zdb -l /dev/sdX

wipefs --no-act reports signatures without modifying the device. zdb -l should not find a readable ZFS label after a successful run.

Recovery Assessment

verify-zpool-recovery.sh checks whether ZFS can find and rewind an exported or faulted pool. It cannot restore labels that have been completely overwritten by the eraser, so recovery after a successful erase is unlikely. Use it before erasing a device, or when ZFS still detects at least part of the pool metadata.

List pools ZFS can discover without modifying anything:

sudo ./verify-zpool-recovery.sh

Check whether a specific pool can be recovered with a transaction rewind. This uses zpool import -nF, which is a dry run:

sudo ./verify-zpool-recovery.sh tank

If vdevs must be found in a non-default directory, supply it explicitly:

sudo ./verify-zpool-recovery.sh --directory /dev/disk/by-id tank

After reviewing the dry-run output, attempt the import with rewind recovery:

sudo ./verify-zpool-recovery.sh --apply tank

--apply runs zpool import -N -F: -F may discard the most recent transaction groups, and -N imports the pool without mounting datasets. The script requires the exact confirmation RECOVER tank before issuing that command. Inspect the result with zpool status tank before mounting datasets or performing any further changes.

4.2 KiB Raw Blame History