Dump Device-Mapper Cache Metadata Safely with cache_dump

You will export device-mapper cache metadata as XML with cache_dump, either to standard output or to a named file. This guide covers the installed thin-provisioning-tools 0.9.0 command on Ubuntu, and takes about ten minutes if you already know which metadata device or file to inspect.

The export is for analysis or post-processing. The XML can later be supplied to cache_restore to recreate metadata on a metadata device or in a file. The command cannot read live metadata, so identify an offline copy or an otherwise inactive metadata source before you begin.

1. Check the installed command

Run these checks as your normal user first. They do not inspect or change metadata:

$ command -v cache_dump
/usr/sbin/cache_dump
$ cache_dump --version
0.9.0
$ cache_dump --help
Usage: cache_dump [options] {device|file}
Options:
  {-h|--help}
  {-o <xml file>}
  {-V|--version}
  {--repair}

The package version on this host is thin-provisioning-tools 0.9.0-2ubuntu5.1. Keep that detail with any runbook or incident record: option sets and diagnostic text can differ between package releases.

2. Stop before choosing a live source

cache_dump accepts one positional argument, either a device or a file. It dumps binary cache metadata created by the device-mapper cache target. The manual explicitly says that live metadata cannot be used.

Do not guess that a path named metadata is safe. Confirm how your storage stack exposes it, and arrange the maintenance or recovery procedure that makes the source inactive. If you are working from a backup or image, make a read-only working copy where practical. This guide does not stop a cache target, unmount a filesystem, deactivate a volume group, or create a snapshot for you.

Reading a block device may require elevated privileges. Use sudo only for the read operation if the device permissions require it. The command itself does not need root when the input and output are accessible to your account.

$ test -r /path/to/cache-metadata && echo 'input is readable'
input is readable
$ ls -l /path/to/cache-metadata

Replace /path/to/cache-metadata with an actual inactive metadata device or file. Do not paste that placeholder unchanged.

3. Dump XML to standard output

For a quick inspection, pass the source as the final argument:

$ cache_dump /path/to/cache-metadata

The command writes XML to the terminal. Its exact content depends on the cache metadata, so do not compare it with a fixed sample. The useful verification is the exit status:

$ cache_dump /path/to/cache-metadata > /tmp/cache-metadata.xml
$ status=$?
$ printf 'cache_dump exit status: %s\n' "$status"
cache_dump exit status: 0
$ test -s /tmp/cache-metadata.xml && echo 'XML file is non-empty'
XML file is non-empty

Redirecting standard output avoids flooding the terminal, but the shell creates or truncates the destination before cache_dump runs. Use a new temporary name when the destination may already contain a useful export.

4. Write directly to a chosen XML file

Use the documented -o option to send the XML to a file instead of standard output:

$ cache_dump -o /path/to/cache-metadata.xml /path/to/cache-metadata
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ test -s /path/to/cache-metadata.xml && echo 'XML file is non-empty'
XML file is non-empty

The output path is separate from the positional input. Keep them different unless you have verified the tool's behaviour for your exact source type; overwriting the source would destroy the data you intended to read. The command's documented success status is 0. An error returns status 1.

For a safer replacement of an existing export, write to a new file and rename it only after the command succeeds:

$ cache_dump -o /path/to/cache-metadata.xml.new /path/to/cache-metadata
$ mv -- /path/to/cache-metadata.xml.new /path/to/cache-metadata.xml

If the dump fails, leave the old XML in place and remove the incomplete .new file after checking its path. If the rename has already happened, there is no command-specific undo; restore the previous export from your backup.

5. Treat repair as a separate operation

--repair asks cache_dump to repair the metadata while dumping it. That is not a read-only inspection. It can change the metadata source, and it can also affect the interpretation of the exported XML. Do not add it to a first diagnostic run.

Before using it, preserve an exact backup or snapshot through your storage team's normal process, confirm that the source is inactive, and record who approved the repair. Then use a distinct output name:

$ sudo cache_dump --repair -o /path/to/cache-metadata-repaired.xml /path/to/cache-metadata
$ printf 'exit status: %s\n' "$?"
exit status: 0

sudo is shown because metadata devices commonly require elevated access, not because repair always requires it. If this command fails, do not repeatedly rerun it against the original source. Preserve the diagnostic and return to the backup or recovery procedure. The repair option is not a substitute for cache_check or a storage-specific recovery plan.

6. Troubleshoot without changing state

A status of 1 means an error occurred, but it does not identify the cause by itself. Check the path, permissions and source state first:

$ ls -l /path/to/cache-metadata
$ test -r /path/to/cache-metadata && echo readable
$ cache_dump -o /tmp/cache-dump-test.xml /path/to/cache-metadata
$ printf 'exit status: %s\n' "$?"
exit status: 0

If the file is missing or unreadable, fix the path or access through the normal storage controls. If the source is live, stop and obtain an inactive copy. If the XML file is empty or the command returns 1, keep the original source untouched and inspect the error output. Do not treat a newly created file as a valid export until the command returned 0 and the file is non-empty.

When passing a shell variable, quote it so whitespace or shell metacharacters do not change the arguments:

$ source='/path/to/cache-metadata'
$ output='/path/to/cache-metadata.xml'
$ cache_dump -o "$output" "$source"