Repair Offline Thin-Pool Metadata with thin_repair

thin_repair writes a repaired copy of damaged thin provisioning metadata somewhere else entirely, leaving the original input untouched. The result can then be checked before anyone considers handing it back to the thin-provisioning target.

This guide takes about 10 minutes once the metadata is available, but the repair itself can take longer on a large device. The examples use the thin-provisioning-tools 0.9.0 package installed here. You need the package, enough space for a preallocated output file or a suitable spare metadata device, and elevated privileges if either path is not readable or writable by your user.

1. Confirm the installed tool

Check the binary and its version before relying on an example. The command accepts an input and a different output, each of which may be a file or a device.

$ command -v thin_repair
/usr/sbin/thin_repair
$ thin_repair --version
0.9.0

Checkpoint: if the version or path differs, run thin_repair --help and compare the available options with the commands below. Do not assume another distribution's package has the same behaviour.

2. Stop access to the metadata

Do not run thin_repair on live metadata. Stop the service or deactivate the thin pool using your normal storage procedure, then confirm that the metadata device is no longer actively used. This is a service-disrupting step and the exact deactivation command depends on how the pool was created.

Do not guess a device path. Record the input you intend to repair, for example:

$ INPUT='/path/to/metadata'
$ test -r "$INPUT" && printf 'input is readable: %s\n' "$INPUT"
input is readable: /path/to/metadata

For a logical volume, a path such as /dev/vg/metadata may be used. Treat it as a real block device, not as an ordinary file you can casually replace.

3. Prepare a separate output

The output must not be the input. If you write to a file, thin_repair requires that file to be preallocated and large enough for the metadata. Create the output in a filesystem with enough free space, using an obvious temporary name:

$ OUTPUT='/path/to/metadata.repaired'
$ truncate -s 8G "$OUTPUT"
$ stat -c 'output size: %s bytes' "$OUTPUT"
output size: 8589934592

Replace 8G with a size that is large enough for your metadata. The command above changes the filesystem and may replace an existing file, so inspect OUTPUT first. Keep the original input until verification and any recovery work are complete. If the repair fails and the output is only a disposable file, remove that output and recreate it; never remove the only metadata copy.

If the destination is a spare metadata device rather than a file, identify it twice before proceeding. Writing a repaired image to the wrong device can destroy unrelated data. A device destination does not need file preallocation, but it still must not be the live input.

4. Run the repair

Run the command with explicit paths. Use sudo only when permissions require it:

$ thin_repair --input "$INPUT" --output "$OUTPUT"
$ printf 'thin_repair exit status: %s\n' "$?"
thin_repair exit status: 0

Success means the program returned exit status 0. It does not mean that the output is safe to activate without a check. A status of 1 means an error; retain the input and investigate the message, path permissions, output size, and whether the metadata was still live.

For a privileged path, run the same operation as:

$ sudo thin_repair --input "$INPUT" --output "$OUTPUT"

Do not insert another command before checking $?, because the shell status always belongs to the command immediately before it. If the output file is incomplete after a failed attempt, treat it as unusable and do not activate it.

5. Check the repaired metadata

Run thin_check against the repaired output while it remains offline:

$ thin_check "$OUTPUT"
$ printf 'thin_check exit status: %s\n' "$?"
thin_check exit status: 0

Both tools use exit status 0 for success and 1 for an error. A failed check is a stop point, not a reason to clear flags or activate the pool. Preserve the original and repaired files, capture the diagnostic output, and follow your storage recovery procedure.

Only after a successful check should an administrator consider supplying the repaired metadata to the device-mapper target. Activation is outside thin_repair; follow the procedure for your LVM or device-mapper setup and keep a rollback path.

6. Use metadata overrides only for recovery

The command has three override options: --transaction-id, --data-block-size, and --nr-data-blocks. They replace values read from the input metadata. Use them only when you have independently established the correct values from the pool configuration or a documented recovery plan. A plausible number is not evidence, and a wrong override can produce metadata that describes the wrong pool.

$ thin_repair --input "$INPUT" --output "$OUTPUT" \
    --transaction-id <TRANSACTION_ID> \
    --data-block-size <DATA_BLOCK_SIZE> \
    --nr-data-blocks <NR_DATA_BLOCKS>

Do not copy this override example with the angle-bracket placeholders still present. For an ordinary repair, omit all three options and let the input metadata provide these values.

Done means