Safely export thin provisioning metadata with thin_dump

You will export device-mapper thin provisioning metadata to XML or human-readable text, check the result, and keep the original metadata device untouched. The examples use thin_dump 0.9.0 from the installed thin-provisioning-tools package. Allow about fifteen minutes if you already know which metadata device belongs to the thin pool.

This is an administrative storage operation. You need a readable metadata device or file and enough space for the output. Most inspection commands can run as your normal user, but a device under /dev may require elevated access. Use sudo only for the command that needs it. Do not run the examples against a guessed device.

1. Confirm the installed command

Start with read-only checks. They do not open a metadata device for dumping:

$ command -v thin_dump
/usr/sbin/thin_dump
$ thin_dump --version
0.9.0
$ dpkg-query -W -f='${Package} ${Version}\n' thin-provisioning-tools
thin-provisioning-tools 0.9.0-2ubuntu5.1

The command accepts one device or file after its options. Its normal output is XML on standard output. The installed manual says that it cannot run on live metadata unless you use --metadata-snap.

2. Identify the metadata source

Set a shell variable to the exact metadata device or file you have identified through your LVM and device-mapper records. The value below is a placeholder, not a device to try blindly:

$ METADATA='/dev/vg/metadata'
$ ls -l -- "$METADATA"
$ test -r "$METADATA" && echo 'metadata source is readable'
metadata source is readable

Replace /dev/vg/metadata with your real path. If ls fails, stop and resolve the path or permissions first. A successful path check does not prove that the source contains valid thin provisioning metadata.

Checkpoint: make sure the source is not a live metadata device. If the thin pool must remain active, arrange for a metadata snapshot using the device-mapper thin provisioning workflow and obtain its block number. The kernel creates and releases that snapshot; thin_dump only reads it.

3. Dump XML to a new file

XML is the default format and is the form that can be fed to thin_restore. Write to a new destination so an existing export is not truncated:

$ OUTPUT='/path/to/thin-metadata.xml.new'
$ thin_dump "$METADATA" > "$OUTPUT"
$ printf 'thin_dump status: %s\n' "$?"
thin_dump status: 0
$ test -s "$OUTPUT" && echo 'XML export is non-empty'
XML export is non-empty

Shell redirection creates or truncates the destination before the command starts. Choose a new name, or copy the old export to a separately named backup before replacing it. If dumping fails, leave the original export in place and remove only the incomplete .new file after checking that no later command still needs it.

For a metadata device that requires elevated access, use the same safe destination pattern:

$ sudo thin_dump "$METADATA" > "$OUTPUT"
$ test -s "$OUTPUT" && echo 'XML export is non-empty'

The redirection is performed by your shell, not by sudo. Therefore the destination directory must be writable by your user. If only the device is restricted, this is usually the least privilege needed.

4. Inspect a readable report

Human-readable output is useful for a quick review, but it is not suitable input for thin_restore. Send it to the terminal only when the report is small, or save it as a separate file:

$ thin_dump --format human_readable "$METADATA" \
    > /path/to/thin-metadata.txt
$ sed -n '1,40p' /path/to/thin-metadata.txt

The short form is -f human_readable. Do not confuse this report with XML: a readable report may help you inspect metadata, but the manual specifically describes it as not processable by thin_restore.

5. Dump a metadata snapshot safely

If the metadata is live, use the default metadata snapshot created by the thin provisioning target, or name a particular snapshot block:

$ thin_dump --metadata-snap "$METADATA" \
    > /path/to/thin-metadata-snapshot.txt
$ thin_dump --metadata-snap=BLOCK_NUMBER "$METADATA" \
    > /path/to/thin-metadata-snapshot.xml

Replace BLOCK_NUMBER with the block number retrieved from the kernel workflow. With no number, thin_dump uses the default metadata snapshot. The first command above deliberately uses human-readable output only if you add --format human_readable; without that option its output remains XML. A snapshot gives you a consistent source to inspect, but it is still your responsibility to release it through the device-mapper workflow when it is no longer needed.

Do not invent a block number and do not release a snapshot while another recovery or inspection process depends on it. Snapshot lifecycle changes can affect storage operations and belong in a planned maintenance procedure.

6. Select devices or mappings only when needed

A metadata dump can contain mappings for multiple thin devices. Add --dev-id to select a device, and repeat it to select more than one:

$ thin_dump --dev-id 42 --dev-id 43 "$METADATA" \
    > /path/to/selected-thin-devices.xml
$ test -s /path/to/selected-thin-devices.xml && echo 'selected export is non-empty'
selected export is non-empty

Use --skip-mappings when you need metadata without dumping the mappings. This can make an inspection export smaller, but it is not a complete backup of the mapping information:

$ thin_dump --skip-mappings "$METADATA" \
    > /path/to/metadata-without-mappings.xml

7. Treat repair and overrides as recovery work

--repair repairs metadata whilst dumping it. Do not add it to a routine inspection command. Before using it, make a separate copy or snapshot, record the source and command, and confirm the recovery plan with whoever owns the thin pool. A repair can change what you are trying to preserve, and this guide does not provide an undo operation.

The options --transaction-id, --data-block-size and --nr-data-blocks override values in the input XML. They are specialised recovery or migration controls, not ordinary display settings. Use them only when the metadata format and the receiving workflow require a specific value. Likewise, -o writes output to the named XML file instead of standard output, so check its path before allowing it to replace an existing export.

8. Diagnose a failed dump

thin_dump returns status 0 for success and 1 for an error. Capture that status immediately:

$ thin_dump "$METADATA" > /path/to/thin-metadata.xml.new
$ status=$?
$ printf 'thin_dump status: %s\n' "$status"
thin_dump status: 1

For a bad path, check the source without changing it:

$ ls -l -- "$METADATA"
$ test -r "$METADATA" && echo readable

If the command reports live metadata, stop rather than adding --repair. Use an appropriate metadata snapshot and verify the block number. If the output is empty or incomplete, keep the source intact, preserve any useful diagnostic, and rerun to a new destination after correcting the source or permissions.