Dump Era Metadata Safely with era_dump

Before you can restore or inspect device-mapper era metadata, you need an XML dump, and era_dump is the only supported way to get one. The examples use era_dump 0.9.0 from the Ubuntu thin-provisioning-tools package version 0.9.0-2ubuntu5.1.

Allow about fifteen minutes for a straightforward export, longer if you need to track down the right metadata volume. You need a shell, the thin-provisioning-tools package, and a metadata device or file that is not live. Reading a protected block device may need sudo, but the command itself does not normally require elevated privileges when the input is already readable.

1. Check the installed command

Start with read-only checks. These confirm the binary, package version and option syntax without opening a metadata device:

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

The required positional argument is either a device or a file. The command writes XML to standard output unless you pick another output file with -o.

2. Confirm the input is offline

Use the path from your storage inventory rather than guessing from a volume name. The manpage example uses /dev/vg/metadata, but that is only a placeholder for a real metadata device on the host:

$ METADATA='/dev/vg/metadata'
$ test -r "$METADATA" && printf 'readable: %s\n' "$METADATA"
readable: /dev/vg/metadata

That test command only checks that the current account can read the path; it does not prove the metadata is offline or that it belongs to the expected pool. Check the device-mapper and thin-provisioning state with your normal maintenance procedure before running era_dump.

If the metadata is readable only by root, repeat the later command with sudo. Do not use sudo as a substitute for stopping the workload: root access changes permissions, not whether the metadata is live or offline.

3. Write the XML to standard output

For a small inspection, dump the offline input directly. This is an ordinary command if the path is readable:

$ era_dump "$METADATA"
<era_metadata>
  ... XML emitted by the metadata dump ...
</era_metadata>

Element names and contents depend on the metadata; do not treat the sample above as a promise for every release or metadata version. A successful command returns exit status 0, an error returns 1.

Capture the status immediately if the dump is part of a script:

$ era_dump "$METADATA" >/tmp/era-metadata.xml
$ status=$?
$ printf 'era_dump exit status: %s\n' "$status"
era_dump exit status: 0
$ test "$status" -eq 0

Keep the output path on a filesystem with enough free space. Standard output is handy for a pipe, but an unchecked pipeline can hide which command actually failed. Saving the status like this gives the caller an unambiguous result.

4. Save the dump with era_dump

Use -o when you want the program to open the destination itself:

$ era_dump -o /tmp/era-metadata.xml "$METADATA"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ test -s /tmp/era-metadata.xml
$ head -n 5 /tmp/era-metadata.xml

Pick a destination you control, and do not overwrite the only copy of an existing dump. The example uses /tmp for a temporary working file; move or archive a verified result according to your retention policy, and remember that /tmp is not a durable backup.

When the dump will feed straight into another tool, redirect standard output instead:

$ era_dump "$METADATA" > era-metadata.xml
$ test -s era-metadata.xml
$ printf 'dump written: %s bytes\n' "$(wc -c < era-metadata.xml)"

Do not confuse a non-empty file with a valid or complete dump. Exit status is the first check. If the file is headed for era_restore, validate it in a separate, controlled workflow before restoring anything.

5. Decide whether logical output is appropriate

The --logical option folds unprocessed write sets into the final era array. The installed manual says this usually makes the XML simpler for further processing. It changes how the dump is represented, so use it when the next consumer expects the logical form:

$ era_dump --logical -o era-metadata-logical.xml "$METADATA"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Keep an unmodified dump as well when investigating an incident or comparing metadata: it gives you a reference if a later processing step rejects the logical form. Do not add --logical just to shrink a file, and do not assume it repairs damaged metadata.

6. Treat repair as a separate maintenance action

--repair asks era_dump to repair the metadata while dumping it. This is not a harmless display switch: repair can affect the result you are collecting, and may be inappropriate while another process can still access the metadata.

If a repair is authorised, use an explicit output file and keep the exit status:

$ sudo era_dump --repair -o /var/tmp/era-repaired.xml /dev/vg/metadata
$ status=$?
$ printf 'repair dump exit status: %s\n' "$status"
repair dump exit status: 0

That sudo is conditional: use it only when device or destination permissions demand it. A successful status does not replace your storage team's validation of the repaired metadata.

7. Diagnose the common failures

• No input path makes the installed command return status 1 and print No input file provided. followed by its usage text; the positional argument is missing, not the metadata corrupt.
• A bad path also returns non-zero. On this installation, era_dump /dev/null reports bad path and returns 1. Check the exact path, whether it is really a metadata device or file, and whether the workload has actually been stopped before you retry.
• Do not retry with --repair just to make an input error disappear.
• Empty or absent output file? Inspect the destination directory and permissions, then rerun with a new destination.

$ era_dump
No input file provided.
Usage: era_dump [options] {device|file}
...
$ printf 'exit status: %s\n' "$?"
exit status: 1

If the command reports an error after opening the input, preserve its diagnostic text and the original offline metadata for investigation.