Validate Device-Mapper Cache Metadata with cache_check

Run cache_check before you trust a dm-cache metadata device: checking the wrong path can turn a diagnostic task into a storage incident. This gets you a repeatable check plus a clear read of the result. The examples use cache_check from thin-provisioning-tools 0.9.0, packaged here as version 0.9.0-2ubuntu5.1.

Allow about fifteen minutes for a check, longer on a large metadata device. You need shell access, the exact metadata path, and permission to read it. The metadata itself must not be live or in active use by the cache target.

1. Confirm the installed command

Start with read-only commands that need no elevated privileges:

$ command -v cache_check
/usr/sbin/cache_check
$ cache_check --version
0.9.0
$ dpkg-query -W -f='${Package} ${Version}\n' thin-provisioning-tools
thin-provisioning-tools 0.9.0-2ubuntu5.1

The exact binary path and package version can differ on another host, and the version matters whenever you compare diagnostics or option lists, since distributions backport changes.

2. Establish that the metadata is inactive

cache_check takes one positional argument, a device or a file, and it cannot run on live metadata. Before you invoke it, work out which component owns the path and make sure the cache target is stopped, detached or otherwise inactive for your storage layout.

This is usually where elevated privileges enter the picture. Reading a root-owned metadata file can need sudo, and stopping a service or deactivating a logical volume normally does too. Both are host-specific operations, so do not copy a guessed service name into a maintenance command.

Confirm the path with a read-only inspection first:

$ ls -l /dev/vg/cache-metadata
$ readlink -f /dev/vg/cache-metadata
/dev/mapper/vg-cache--metadata

Swap /dev/vg/cache-metadata for your actual metadata device or file. That second line is only an example of how a device-mapper name can resolve, not a universal mapping. If the path is a regular file, use its file name directly and confirm it really is the metadata copy you meant.

3. Run a normal metadata check

Check the inactive path directly. Use an ordinary command if your account can read the metadata, and only prefix sudo when permissions or storage controls actually require it:

$ cache_check /dev/vg/cache-metadata

A successful run exits with status 0, and the command may print diagnostic messages along the way. Status 1 means an error, per the installed manual, so capture the status immediately if you need to record it:

$ cache_check /dev/vg/cache-metadata
$ status=$?
$ printf 'cache_check exit status: %s\n' "$status"
cache_check exit status: 0

That final line is the only verification that matters. Do not infer success from a quiet terminal or from getting your prompt back. Status 1 means preserve the diagnostic output and leave the metadata inactive until you understand the failure.

4. Use quiet mode in a monitored check

For a script or an operator check where the exit status is the whole result, add --quiet. It suppresses the output messages and leaves the return code for the shell to use:

$ if cache_check --quiet /dev/vg/cache-metadata; then
>     echo 'cache metadata check passed'
> else
>     echo 'cache metadata check failed' >&2
>     exit 1
> fi
cache metadata check passed

Only reach for this after testing the non-quiet command first. Quiet mode strips out context that matters during an incident, and it does not make a live-metadata check safe. Quote the path if a file name contains whitespace:

$ cache_check --quiet "/srv/metadata/cache metadata.bin"

5. Narrow the check only for a stated reason

Three switches skip parts of validation: --super-block-only, --skip-hints and --skip-discards. Use them for a specific diagnostic question, never as a way to make a failed full check look healthy.

• --super-block-only limits the check to the superblock.
• --skip-hints skips policy hint values in the metadata.
• --skip-discards skips discard bits in the metadata.

A narrowed check passing does not certify the bits you skipped, so record the exact command in any incident notes:

$ cache_check --super-block-only /dev/vg/cache-metadata
$ printf 'exit status: %s\n' "$?"
exit status: 0

That zero is an example of the success path, not a promise about your device. Need a complete answer? Rerun without a skip switch and keep that result.

6. Treat needs-check clearing as a separate change

The kernel can set a flag that forces the cache metadata to be checked before its next activation. --clear-needs-check-flag only clears that flag if the check succeeds, and because it changes metadata, it does not belong in a first inspection.

Run cache_check again after a successful repair. Only once that succeeds should you consider clearing the flag:

$ cache_check --clear-needs-check-flag /dev/vg/cache-metadata
$ printf 'exit status: %s\n' "$?"
exit status: 0

The manual describes no general undo for restoring the flag afterwards. Treat the switch as a deliberate state change, and keep your pre-change diagnostic record.

Common traps

• The command refuses the path. Check you supplied exactly one device or file and that the path still exists; a shell typo is not evidence of damaged metadata.
• The check reports live metadata. Stop, and go back to the ownership and activation check in step 2. Do not work around this protection with another option.
• The check returns 1. Save the full non-quiet output, leave the metadata inactive, and follow your repair procedure. Do not clear the needs-check flag.
• A quiet check appears to do nothing. That is the point. Check $? immediately, or use the if form from step 4.
• A narrowed check passes but activation still fails. Rerun the full check; the areas you skipped were never actually validated.

For an unknown option or a local packaging quirk, ask the binary itself:

$ cache_check --help

On this installation, help also lists --skip-mappings, which the installed cache_check(8) page does not document. Do not build a procedure around an undocumented option until you have checked the exact binary and package that will run it.