Safely List Era Metadata Changes with era_invalidate

Backup tools use era_invalidate to find which blocks may have changed since a chosen era, without rereading the whole device. This guide uses era_invalidate from thin-provisioning-tools 0.9.0-2ubuntu5.1, installed on the reference system.

Allow about 15 minutes if the metadata source is already identified. You need a shell, an era metadata device or file, and an era number to compare against. The command reads metadata, but must not inspect live metadata unless you use a metadata snapshot. Have the storage owner or backup operator confirm the source before you run it.

1. Confirm the installed command

Start by checking the version and syntax. Both are ordinary, non-privileged checks:

$ era_invalidate --version
0.9.0
$ era_invalidate --help
Usage: era_invalidate [options] --written-since <era> {device|file}

The package version and program version are related but not identical: the installed Debian package is 0.9.0-2ubuntu5.1, while the program itself reports 0.9.0. The help text also spells out the required comparison: supply --written-since and one metadata source.

2. Identify a safe metadata source

Choose the metadata device or file that belongs to the era metadata you want to inspect. The positional argument accepts either form:

METADATA_SOURCE=/dev/vg/metadata
ERA_NUMBER=13
era_invalidate --written-since "$ERA_NUMBER" "$METADATA_SOURCE"

Replace both values. The manpage's example uses /dev/vg/metadata and era 13; that path is illustrative, not something to copy blindly. An era number is a number from the metadata history, not a date, a logical volume name or a block address.

3. Select the era and run the read

Once the source is confirmed inactive, run one comparison:

$ era_invalidate --written-since 13 /dev/vg/metadata
<output from the metadata scan>

The command lists blocks that may have changed since the start of the requested era. That cautious wording is deliberate: treat the result as a candidate list from era metadata, not proof that every listed block actually holds application data changed by a particular process.

Do not add a second positional path; the synopsis accepts one device|file argument. If the comparison needs repeating, keep the same era and source together in an operator note so a later run does not accidentally compare a different metadata history.

status=$?
printf 'era_invalidate exit status: %s\n' "$status"

The documented error status is 1, which includes errors such as metadata corruption. A non-zero status means the output must not be treated as a valid change list.

4. Save the result when another tool needs it

Use -o with a new, clearly named destination when the result has to be handed to another process or kept for review:

OUTPUT_FILE=/var/tmp/era-13-blocks.xml
era_invalidate --written-since 13 -o "$OUTPUT_FILE" /dev/vg/metadata
status=$?
if [ "$status" -ne 0 ]; then
    printf 'era_invalidate failed with status %s\n' "$status" >&2
    exit "$status"
fi
ls -l -- "$OUTPUT_FILE"

The installed help describes the -o value as an XML file. Keep the destination separate from the metadata source, and check the exit status before passing the file onwards. Selected the wrong output path by accident? Stop and preserve it for review rather than quietly mixing it with a trusted result. Remove an unneeded temporary result only once the responsible operator confirms it is no longer required.

5. Handle live metadata with a snapshot

If the metadata is live, use the metadata snapshot option only when your storage workflow already provides the right snapshot:

$ era_invalidate --metadata-snapshot --written-since 13 /dev/vg/metadata
<output from the metadata snapshot scan>

--metadata-snapshot tells the program to use the metadata snapshot rather than the current superblock. It does not create a snapshot, freeze a target or repair metadata. The name is easy to mistake for something that prepares the snapshot for you, so verify the supplied source and snapshot lifecycle before running it.

Do not treat this option as a reason to skip storage checks. A snapshot from the wrong era, volume or metadata device gives you a technically successful command with the wrong answer.

6. Diagnose the likely failure

• Usage error? Usually --written-since, its era number, or the single source argument is missing. Rerun era_invalidate --help and check shell quoting.
• Failure on a live target means you need the approved metadata snapshot workflow, not a repeated command against the same active source.
• Status of 1 means an error, including possible metadata corruption. Preserve the exact command, source identity and any diagnostic text, then use era_check(8) or the storage team's recovery procedure. Do not attempt a repair with an invalidated result.
• Output unexpectedly empty or different? Confirm the era number and metadata source first; the command reports changes since the selected era, not every block in the target.