Repair Device-Mapper Cache Metadata with cache_repair

cache_repair writes a repaired copy of dm-cache metadata to a file or device while leaving the original source completely untouched. The installed command comes from thin-provisioning-tools 0.9.0-2ubuntu5.1, and the binary itself reports version 0.9.0. Allow about fifteen minutes for the command and the checks around it; the repair can take longer on large metadata, and deciding whether the source is safe to use is on you, not the tool.

This guide covers offline binary metadata. It does not repair a mounted or active cache. You need a shell, read access to the input, write access to the destination, enough free space, and a maintenance plan if the destination is a real metadata device.

1. Confirm the installed command

Start with read-only checks. None of these need elevated privileges unless your system hides the binary or its version from your account:

command -v cache_repair
cache_repair --version
cache_repair --help

On this installation, the version output is:

0.9.0

The help text shows the shape you need: an input picked with -i or --input, and an output picked with -o or --output. Either can name a device or a file. Do not confuse this with cache_check, a separate tool that only checks metadata.

2. Stop before touching live metadata

This boundary matters because cache_repair reads binary metadata and writes a repaired result somewhere else entirely. A successful exit status is not permission to run it against an active metadata device. If you cannot prove the source is offline, do not run the repair at all.

3. Inspect the input and choose a new destination

Record the exact source and destination before you add sudo. Replace the placeholders below with real paths from your maintenance plan:

INPUT=/path/to/offline-cache-metadata
OUTPUT=/path/to/repaired-cache-metadata
printf 'input: %s\noutput: %s\n' "$INPUT" "$OUTPUT"
test -r "$INPUT" && printf '%s\n' 'input is readable'
test ! -e "$OUTPUT" && printf '%s\n' 'output does not already exist'

These checks do not prove the input actually holds valid cache metadata, but they do catch two common distractions: a mistyped path, and an output name that would clobber an existing file. Keep the original input, and never point both variables at the same path.

4. Run the repair into the separate destination

Once the source is offline and the destination is checked, run the ordinary command:

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

Success shows up as status 0. The diagnostic contract is simple: 0 for success, 1 for an error. Do not treat a missing or truncated output as repaired just because a command was typed. Check the captured status immediately, before running anything else.

Use elevated privileges only when the source or destination permissions actually require them:

sudo cache_repair --input "$INPUT" --output "$OUTPUT"
status=$?
printf 'cache_repair exit status: %s\n' "$status"

5. Verify the result before putting it back into service

Check the destination first, using whatever storage tools suit its type. For a regular file, confirm it exists and is non-zero:

test -s "$OUTPUT" && stat --printf='repaired output: %n (%s bytes)\n' "$OUTPUT"

Size alone does not prove the metadata is usable. Run the offline validation or inspection tool relevant to your deployment and review its result before you present the destination to the target. The cache_repair manual names cache_check, cache_dump and cache_restore as related tools, but it defines no single validation sequence that fits every deployment.

6. Return to service carefully

Only use the repaired metadata with the device-mapper target once it has passed your environment's checks, and follow the documented activation or replacement procedure for that host. This guide deliberately gives no generic activation command, because the right action depends on the device names, logical volumes and service manager in use.

There is no single undo for a write to a metadata device. Recovery means keeping the original source, keeping a verified backup, and following the cache owner's rollback procedure. Wrote to a regular output file instead? Undo is simple: stop using it, preserve it for investigation, and select the original or another verified copy through your normal maintenance process. Do not delete the original just because the repaired output now exists.