Restore Device-Mapper Cache Metadata with cache_restore

cache_restore rebuilds dm-cache metadata from an XML dump, writing into a prepared regular file or device for you to then verify. The examples match cache_restore 0.9.0 from thin-provisioning-tools package version 0.9.0-2ubuntu5.1. Allow 15 to 30 minutes, plus whatever time it takes to be sure the destination is the right one.

This is a storage operation. You need the XML produced from device-mapper cache metadata, a destination with enough capacity, and a maintenance plan for anything that might use the metadata. The command cannot run against live metadata. Writing to a protected metadata device normally needs elevated privileges; inspecting paths and checking the command do not.

1. Check the installed command

Confirm which executable will run and record its version before you build a recovery procedure around it:

$ command -v cache_restore
/usr/sbin/cache_restore
$ cache_restore --version
0.9.0

The installed manual documents the synopsis as cache_restore [options] -i {xml file} -o {device|file}, accepting both short and long forms of the input and output options. Check the available options on the machine where you will actually run the restore, since package versions differ:

$ cache_restore --help
Usage: cache_restore [options]
Options:
  {-h|--help}
  {-i|--input} <input xml file>
  {-o|--output} <output device or file>
  {-q|--quiet}
  {--metadata-version} <1 or 2>
  {-V|--version}

2. Protect the source and identify the destination

Work from a copy of the XML dump if you need to preprocess it, and inspect both paths without touching storage:

$ ls -l -- /srv/recovery/cache-metadata.xml
$ file -- /srv/recovery/cache-metadata.xml
$ ls -l -- /srv/recovery/cache-metadata.bin
$ stat --format='destination: %n, bytes: %s' /srv/recovery/cache-metadata.bin

The input is XML; the output is binary metadata for a device-mapper cache target, not a second XML document. Choose the destination deliberately: a regular file must already exist, be preallocated and be large enough for the metadata, while a block device must be the intended metadata device, not a data volume or one already carrying live metadata.

3. Prepare a regular-file destination

A regular file suits a dry recovery workspace or moving restored metadata between controlled stages. Create it at the size your storage plan calls for, on a path that holds nothing valuable already:

$ sudo install -m 0600 /dev/null /srv/recovery/cache-metadata-restored.bin
$ sudo fallocate -l 64M /srv/recovery/cache-metadata-restored.bin
$ stat --format='destination: %n, bytes: %s' /srv/recovery/cache-metadata-restored.bin
destination: /srv/recovery/cache-metadata-restored.bin, bytes: 67108864

The 64M here is only an example; the manual defines no universal size, so size it to your actual metadata plus headroom. If fallocate cannot reserve the space, fix the filesystem or pick another prepared destination rather than deleting a useful file to make room.

4. Restore into the prepared destination

Pass the XML path with -i and the prepared file or device with -o:

$ sudo cache_restore \
    --input /srv/recovery/cache-metadata.xml \
    --output /srv/recovery/cache-metadata-restored.bin
$ printf 'cache_restore status: %s\n' "$?"
cache_restore status: 0

Status 0 means the restore completed successfully. The command can print diagnostics along the way, so do not treat a blank terminal as your success test; the documented error status is 1. Capture the status immediately if your script needs to branch on it:

if sudo cache_restore -q \
    -i /srv/recovery/cache-metadata.xml \
    -o /srv/recovery/cache-metadata-restored.bin
then
    printf '%s\n' 'cache metadata restored'
else
    status=$?
    printf 'cache_restore failed with status %s\n' "$status" >&2
    exit "$status"
fi

--quiet suppresses normal output and leaves the exit code as the check. It does not make an unsafe destination safe, and it does not bypass the live-metadata restriction.

5. Restore directly to a metadata device

$ lsblk -o NAME,TYPE,SIZE,FSTYPE,MOUNTPOINTS /dev/vg/cache_metadata
$ sudo cache_restore \
    -i /srv/recovery/cache-metadata.xml \
    -o /dev/vg/cache_metadata

This writes restored binary metadata to whatever device -o names, and it can destroy or invalidate data already there. A mistake here is not fixed by changing the option and trying again. Want an intermediate check? Restore to a new, sufficiently large regular file first, and validate it with the next stage of your storage platform's documented recovery process.

6. Choose metadata handling deliberately

--metadata-version selects metadata version 1 or 2:

$ sudo cache_restore \
    --metadata-version 2 \
    --input /srv/recovery/cache-metadata.xml \
    --output /srv/recovery/cache-metadata-restored.bin

Do not add this as a guess; use the version your device-mapper target and the metadata dump actually require. The command also exposes --debug-override-metadata-version and --omit-clean-shutdown, both specialised controls. The first overrides the version stored in the metadata, the second stops the clean-shutdown flag being set. Use either only when your recovery procedure explicitly calls for it; neither is a general fix for a failed restore.

7. Recover from a failed attempt

Status 1 means preserve the XML and record the exact command, version, destination and diagnostic output. Check the basics first without writing again:

$ test -r /srv/recovery/cache-metadata.xml && echo 'input is readable'
$ stat --format='output bytes: %s' /srv/recovery/cache-metadata-restored.bin
$ cache_restore --version
0.9.0

Typical boundary errors include a missing output path, a regular file too small, an unreadable input, an invalid XML dump, or a metadata-version mismatch. Fix the condition you identify and use a new destination if the previous attempt may hold partial data. Keep the failed file for diagnosis until your recovery record is complete; do not overwrite the only copy of a known-good metadata destination.

If a restore has already changed a metadata device, stop and follow the storage system's recovery procedure. Status 0 alone is not permission to put the device back into service; the restored metadata still needs to be accepted by the device-mapper target and checked by the next operational layer.