Restore Thin Provisioning Metadata Safely with thin_restore

thin_restore turns an XML dump of thin provisioning metadata back into binary metadata inside a prepared file or device. Allow about fifteen minutes for a file restore, longer if you must identify the correct inactive device and confirm its size. The examples use thin_restore 0.9.0 from the installed thin-provisioning-tools package.

This is an administrative operation. You need a readable XML file produced by a compatible metadata dump, an output file that already exists and is large enough, or a suitable block device. Writing to a metadata device normally needs elevated privileges; the commands that inspect paths and ask for help do not.

1. Confirm the installed command

Start with read-only checks. They establish which binary and version will perform the restore:

$ command -v thin_restore
/usr/sbin/thin_restore
$ thin_restore --version
0.9.0
$ thin_restore --help
Usage: thin_restore [options]
Options:
  {-h|--help}
  {-i|--input} <input xml file>
  {-o|--output} <output device or file>
  {--transaction-id} <natural>
  {--data-block-size} <natural>
  {--nr-data-blocks} <natural>
  {-q|--quiet}
  {-V|--version}

The required shape is thin_restore -i INPUT.xml -o OUTPUT. The input is XML metadata, not a filesystem image. The output is binary metadata suitable for later processing by the device-mapper target.

2. Prepare the input without changing it

Check that the XML exists and is readable before touching an output:

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

Use an XML file from thin_dump or another tool that produces the thin provisioning metadata format. Keep the original dump as your recovery copy. If you edited it, review the changes before restoring; a syntactically valid document can still describe metadata you did not intend to write.

Checkpoint: confirm the input path is the dump you mean to restore. Do not infer this from a convenient filename alone, especially when several pools or snapshots are involved.

3. Prepare a non-live output

Stop before this step if the target is live. The manual explicitly says that thin_restore cannot run on live metadata. Do not point it at metadata currently in use by a thin pool. Stop the owning workload and follow your volume manager's procedure for making the metadata target inactive before continuing.

For a regular file, the file must already exist and be preallocated to a size large enough for the restored metadata. The command does not create the output for you:

$ fallocate -l SIZE /path/to/preallocated-metadata.bin
$ ls -lh /path/to/preallocated-metadata.bin
-rw-r--r-- 1 operator operator SIZE ... /path/to/preallocated-metadata.bin

Replace SIZE with a measured value appropriate for this metadata set. Do not treat the example size as a recommendation. If the destination is a block device, identify it by its stable volume or mapper name and check it before using it. Writing the wrong device is destructive and may make other metadata or data inaccessible.

For a device destination, use sudo only for the restore command when the device permissions require it:

$ ls -l /dev/mapper/metadata-target
$ sudo thin_restore -i /path/to/metadata.xml -o /dev/mapper/metadata-target

Ordinary users can usually restore to a file in a directory they own. A successful command normally prints no completion report, so its exit status is the first check.

4. Restore to the prepared destination

Run the restore with explicit input and output paths:

$ thin_restore --input /path/to/metadata.xml --output /path/to/preallocated-metadata.bin
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 means the command completed successfully. The short forms, -i and -o, are equivalent:

$ thin_restore -i /path/to/metadata.xml -o /path/to/preallocated-metadata.bin

Do not use shell redirection for the output. The destination is an argument to thin_restore, and the program writes binary metadata into it. The output file must exist before the command starts. On this installed version, a missing file produces an error saying that the output must be a block device or an existing file, then returns status 1.

5. Verify before making the metadata live

First verify that the intended file or device was the destination and that the command returned zero:

$ stat /path/to/preallocated-metadata.bin
$ printf 'last restore status: %s\n' "$?"
last restore status: 0

When you need a stronger check, run the appropriate metadata validation tool for your installation against the restored, still-inactive metadata. The related thin_check command is the usual health check, but it is a separate command and not part of thin_restore. Confirm its result before handing the metadata device back to the device-mapper target.

If the restore fails, preserve the XML and the destination for investigation. A failed run may have changed some output bytes, so do not reuse that destination as if it were known-good. Restore a backup or recreate the file, then correct the input, size or permissions before trying again.

6. Use overrides only when you mean to

The installed command accepts --transaction-id, --data-block-size and --nr-data-blocks. Each overrides the corresponding value from the XML. These are not formatting switches: they change metadata parameters. Leave them out for a normal dump-and-restore operation.

If you intentionally need an override, record the old XML values, the replacement values and the reason in the change record before running the command:

$ thin_restore \
    --input /path/to/metadata.xml \
    --output /path/to/preallocated-metadata.bin \
    --transaction-id TRANSACTION_ID \
    --data-block-size DATA_BLOCK_SIZE \
    --nr-data-blocks DATA_BLOCK_COUNT

Replace every uppercase token with a natural-number value supported by your metadata layout. Do not copy these placeholders literally. If you cannot explain why an override is needed, omit it and restore the values already recorded in the XML.

7. Recover from a wrong or failed destination

There is no undo option in thin_restore. The practical rollback is a known-good metadata file or device image. A backup is not optional when the output is a valuable metadata device.

Done means