Restore Device-Mapper Cache Metadata Safely with cache_restore

You will restore an XML cache-metadata dump into a prepared regular file or device, then verify the command status and destination. 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 however long you need to confirm the destination is the correct 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 on 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}. It accepts both the short and long forms of the input and output options. Check the available options on the machine where you will perform the restore, because package versions can 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}

Checkpoint: stop if the version or binary is not the one your recovery notes expect. Do not substitute a similarly named tool from another package without checking its manual.

2. Protect the source and identify the destination

Use a copy of the XML dump if you need to preprocess it, and inspect both paths without changing 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 an XML file. 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. A block device must be the intended metadata device, not a data volume or a device currently carrying live metadata.

Do not run the restore against live metadata. Stop or isolate the relevant device-mapper target according to your storage platform's recovery procedure before writing a metadata device. That service disruption is outside this command and cannot be undone by rerunning it.

3. Prepare a regular-file destination

A regular file is useful for a dry recovery workspace or for moving restored metadata between controlled stages. Create it with the size your storage plan requires, using a path that does not contain valuable existing data:

$ 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 value is only an example. The manual does not define a universal size, so use the capacity required by your metadata and leave suitable headroom. If fallocate cannot reserve the requested space, fix the filesystem or choose another prepared destination. Do not remove a useful file just to satisfy this step.

Checkpoint: the file exists before cache_restore runs and its reported size is sufficient. The installed command rejects a missing output file before it can process the input.

4. Restore into the prepared destination

Use 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 that the restore completed successfully. The normal command can print diagnostics, so do not treat a blank terminal as the success test. The documented error status is 1. Capture the status immediately if you need 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

Only use a block device after an independent device-identity check and the maintenance procedure for the target. The destination below is an example placeholder, not a device to copy blindly:

$ 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 the device named by -o. It can destroy or invalidate data at that destination. A mistake here is not repaired by changing the option and trying again. If you need an intermediate check, restore to a new, sufficiently large regular file first and validate that file with the next stage of your storage platform's documented recovery process.

6. Choose metadata handling deliberately

The --metadata-version option 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 option as a guess. Use the version required by the device-mapper target and the metadata dump you are restoring. The command also exposes --debug-override-metadata-version and --omit-clean-shutdown. These are specialised controls: the first overrides the version stored in the metadata, while the second prevents the clean-shutdown flag being set. Use either only when your recovery procedure explicitly calls for it. They are not general fixes for a failed restore.

7. Recover from a failed attempt

If the command returns 1, preserve the XML and record the exact command, version, destination and diagnostic output. First check the basics 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 that is too small, an unreadable input, an invalid XML dump, or a metadata-version mismatch. Correct the identified condition and use a new destination when the previous attempt may contain partial data. Keep the failed file for diagnosis until the 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. Do not put the device back into service merely because the process returned 0; the restored metadata still needs to be accepted by the device-mapper target and checked by the next operational layer.