Validate Device-Mapper Cache Metadata Safely with cache_check

You will finish with a repeatable check for device-mapper cache metadata stored on a device or in a file, plus a clear interpretation 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 for a large metadata device. You need shell access, the exact metadata path, and enough permission to read it. The metadata must not be live or actively used by the cache target. Checking the wrong path, or checking a live metadata device, can turn a diagnostic task into a storage incident.

1. Confirm the installed command

Start with read-only commands. These do not need 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. The version matters when comparing diagnostics or option lists, because distributions may backport changes.

Checkpoint: if command -v finds nothing, stop and install or enable the package through your normal system-management process. Do not substitute a similarly named tool.

2. Establish that the metadata is inactive

cache_check accepts one positional argument, either a device or a file. It cannot be run on live metadata. Before invoking it, identify which component owns the path and ensure the cache target is stopped, detached or otherwise inactive according to your storage layout.

This is the point where elevated privileges may be required. Reading a root-owned metadata file can need sudo, and stopping a service or deactivating a logical volume normally needs it. Those are host-specific operations, so do not copy a guessed service name into a maintenance command.

Use a read-only inspection to confirm the path before the check:

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

Replace /dev/vg/cache-metadata with the actual cache metadata device or file. The second output is only an example of how a device-mapper name may resolve; it is not a universal mapping. If the path is a regular file, use its file name directly and confirm that it is the intended metadata copy.

3. Run a normal metadata check

Run one check against the inactive path. Use an ordinary command when your account can read the metadata; prefix it with sudo only when the permissions or storage controls require that:

$ cache_check /dev/vg/cache-metadata

A successful run exits with status 0. The command can print diagnostic messages while it works. The installed manual defines status 1 as an error, 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

The final line is the useful verification. Do not infer success from a quiet terminal or from the command returning to your prompt. If the status is 1, preserve the diagnostic output and do not activate the metadata again 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 result, add --quiet. It suppresses output messages and leaves the return code available to the shell:

$ 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

Use this form only after testing the non-quiet command. Quiet mode removes context that is useful during an incident, and it does not make a live metadata check safe. Keep the path quoted if you use a file name containing whitespace:

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

5. Narrow the check only for a stated reason

The installed command provides three switches that skip parts of validation: --super-block-only, --skip-hints and --skip-discards. Use them when you have a specific diagnostic question, not as a way to make a failed full check appear healthy.

--super-block-only limits the check to the superblock. The other two skip policy hint values or discard bits in the metadata. A passing narrowed check does not certify the portions you omitted, 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

The zero status above is an example of the success path, not a promise about your device. If you need a complete answer, rerun without a skip switch and retain that result.

6. Treat needs-check clearing as a separate change

The kernel can set a flag requiring the cache metadata to be checked before its next activation. --clear-needs-check-flag clears that flag only if the check succeeds. This option changes metadata, so it is not part of a first inspection.

Do not combine it with a path you have not independently verified, and do not use it to silence a failed check. A failed check leaves the flag set and the manual points to cache_repair as the next repair step. Repair is a separate, potentially disruptive operation: take the recovery path approved for your storage system, preserve the original metadata where possible, and make sure you can restore service before starting.

After a successful repair, run cache_check again. Only when that check succeeds should you consider whether clearing the flag is appropriate:

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

There is no general undo command described by the manual for restoring the flag. Treat the switch as an intentional state change and keep the pre-change diagnostic record.

7. Diagnose the common traps

• The command refuses the path. Check that 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. Return to the ownership and activation check in step 2. Do not work around this protection with another option.
• The check returns 1. Save the complete 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 its purpose. Inspect $? immediately, or use the if form in step 4.
• A narrowed check passes but activation still fails. Rerun the full check. The skipped metadata areas have not been validated.

For an unknown option or a local packaging difference, ask the installed binary for its own help:

$ cache_check --help

On this installation, help also lists --skip-mappings, while the installed cache_check(8) page does not document it. Do not rely on undocumented options in a procedure until you have checked the exact binary and package that will run it.