Dump Device-Mapper Cache Metadata with cache_dump

Use cache_dump when you need dm-cache metadata as readable XML instead of an opaque binary blob, whether for analysis or to feed into a later restore. This covers the installed thin-provisioning-tools 0.9.0 command on Ubuntu, and takes about ten minutes once you know which metadata device or file to inspect.

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

1. Check the installed command

Run these as your normal user first. They inspect nothing and change nothing:

$ 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 with any runbook or incident record, since option sets and diagnostic text differ between package releases.

2. Stop before choosing a live source

cache_dump takes one positional argument, a device or a file, and dumps the binary metadata the device-mapper cache target created. The manual is explicit: live metadata cannot be used.

Do not assume a path named metadata is safe just because of its name. Confirm how your storage stack exposes it, and follow the maintenance or recovery procedure that makes the source inactive first. Working from a backup or image? Make a read-only working copy where you can. This guide will not stop a cache target, unmount a filesystem, deactivate a volume group or take a snapshot for you.

Reading a block device may need elevated privileges. Use sudo only for that read if device permissions require it; the command itself needs no 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

Swap /path/to/cache-metadata for a real, inactive metadata device or file. Do not paste that placeholder unchanged.

3. Dump XML to standard output

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

$ cache_dump /path/to/cache-metadata

The command writes XML straight to the terminal. Its exact content depends on your metadata, so do not compare it against a fixed sample. The useful check 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 output stops it flooding your terminal, but the shell creates or truncates the destination before cache_dump even runs. Use a fresh temporary name whenever the destination might already hold a useful export.

4. Write directly to a chosen XML file

Send the XML straight to a file with -o instead:

$ 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

For a safer replacement of an existing export, write to a new file and only rename it once 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

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 source, and it can change how you should read the exported XML too. Do not add it to a first diagnostic run.

Before using it, take an exact backup or snapshot through your storage team's normal process, confirm 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 appears here because metadata devices commonly need elevated access, not because repair always does. If this fails, do not just rerun it against the original source; preserve the diagnostic and go back to your backup or recovery procedure. This option is not a substitute for cache_check or a storage-specific recovery plan.

6. Troubleshoot without changing state

Status 1 means an error occurred, but not what caused it. 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

Missing or unreadable file? Fix the path or access through your normal storage controls. Live source? Stop and obtain an inactive copy first. If the XML comes out empty or the command returns 1, leave 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.

Quote a shell variable when you pass one, so whitespace or shell metacharacters cannot change the arguments:

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