Restore Device-Mapper Era Metadata Safely with era_restore

Writing an era metadata dump back to a device cannot be casually undone, so era_restore deserves a checked, deliberate command. The examples match thin-provisioning-tools 0.9.0-2ubuntu5.1, whose installed era_restore reports version 0.9.0.

Allow about fifteen minutes for the command checks, plus the time needed to identify the correct metadata target and review your backup. You need an XML file produced by era_dump or a compatible preprocessing workflow, the installed thin-provisioning-tools package, and a destination that is not live metadata. The restore writes binary metadata, so plan it as a maintenance operation and use root privileges only where your device permissions require them.

1. Check the installed command

First confirm the binary, package version and option syntax. These are read-only checks that normally need no elevated privileges:

$ command -v era_restore
/usr/sbin/era_restore
$ dpkg-query -W -f='${Package} ${Version}\n' thin-provisioning-tools
thin-provisioning-tools 0.9.0-2ubuntu5.1
$ era_restore --version
0.9.0
$ era_restore --help
Usage: era_restore [options]
Options:
  {-h|--help}
  {-i|--input} <input xml file>
  {-o|--output} <output device or file>
  {-q|--quiet}
  {-V|--version}

The required shape is era_restore -i XML_FILE -o DESTINATION. The input is an XML metadata file; the output is either a metadata block device or a regular file. Do not confuse this tool with era_dump: dump creates the XML, restore consumes it.

2. Check the XML source

Use the exact path to the dump you mean to restore. Check that it exists, is a regular file, and is readable before you involve a device at all:

$ XML_FILE='/srv/backup/era/metadata.xml'
$ test -r "$XML_FILE" && test -f "$XML_FILE"
$ stat --printf='input: %n\nsize: %s bytes\n' "$XML_FILE"
input: /srv/backup/era/metadata.xml
size: 123456 bytes

That size is only an inventory check; it does not tell you how large the restored binary metadata will be, and the sample number is host-specific. If the test fails, stop and locate the correct dump. Do not create an empty XML file just to make the command proceed.

Keep the original XML unchanged. If it was preprocessed, record the command or configuration used to produce it, so another administrator can compare the intended metadata before anything gets written.

3. Choose and inspect a destination

For a block-device restore, use the metadata device named by the target's configuration. Inspect it without opening it for writing:

$ DESTINATION='/dev/vg/metadata'
$ ls -l "$DESTINATION"
$ lsblk -o NAME,TYPE,SIZE,FSTYPE,MOUNTPOINTS "$DESTINATION"

Expect the paths and output to differ on your host. A destination that is mounted, active in a device-mapper target, or otherwise serving live metadata is not safe for this command; stop and resolve that state first. Removing an active mapping or stopping a service is outside this guide and can interrupt workloads.

A regular file works too, for preparing metadata ahead of time. It must already exist, be preallocated, and be large enough to hold the restored metadata. The manpage gives no formula for the required size, so do not guess from the XML byte count:

$ DESTINATION='/srv/restore/era-metadata.bin'
$ stat --printf='output: %n\nsize: %s bytes\n' "$DESTINATION"
output: /srv/restore/era-metadata.bin
size: 1073741824 bytes

If your storage procedure supplies a required size, create or resize the file according to that procedure before the restore. The restore command itself is not a file allocation step: a missing file is rejected by the installed command, and an undersized one cannot hold the result.

4. Restore to a file first when you need a reversible checkpoint

Writing to a regular file gives you a separate artefact to inspect before it becomes part of a device-mapper workflow. Once you have a correctly sized, preallocated destination, run:

$ era_restore --input "$XML_FILE" --output "$DESTINATION"
$ printf 'restore exit status: %s\n' "$?"
restore exit status: 0

Exit status 0 means success. Without --quiet, normal diagnostic output can vary by version and input, and the command returns 1 for an error. Capture errors from the terminal or your job log rather than treating a silent terminal as proof of success.

5. Restore to the metadata device only after review

Once the destination is confirmed as the correct, inactive metadata device, use the same command with the device path. This is the state-changing step, and it normally requires elevated privileges:

# Run only with the confirmed inactive metadata device.
$ sudo era_restore --input "$XML_FILE" --output /dev/vg/metadata
$ printf 'restore exit status: %s\n' "$?"
restore exit status: 0

Replace /dev/vg/metadata only after verifying the real device. Do not add sudo automatically if your account already has the required access, but do not weaken device permissions just to avoid it either. A successful restore does not activate or process the metadata target; the next steps belong to the device-mapper or LVM recovery procedure for your system.

If the command reports that the output file does not exist, check the path and destination type: the installed tool needs a block device or an existing file, and a file must be large enough. An input or XML error means going back to the original dump and preprocessing record, not changing the destination.

6. Use quiet mode in automation

--quiet suppresses output, so automation has to check the exit status instead. A small shell wrapper can make failure visible without hiding it:

if era_restore --quiet --input "$XML_FILE" --output "$DESTINATION"; then
    printf '%s\n' 'era metadata restore succeeded'
else
    status=$?
    printf 'era metadata restore failed with status %s\n' "$status" >&2
    exit "$status"
fi

Keep the input and output variables explicit. Do not build the command by concatenating an untrusted option string, and do not discard the exit status with || true. If a service depends on the restored metadata, run that service's own documented validation separately before calling the recovery complete.