Inspect Thin Pool Volumes Safely with thin_ls

You will finish with a repeatable way to list thin volumes from a device-mapper thin pool, select useful columns, and recognise when a metadata snapshot is required. The examples use thin-provisioning-tools 0.9.0, installed here as Debian package version 0.9.0-2ubuntu5.1.

Allow about fifteen minutes. You need a Linux shell, thin-provisioning-tools, and access to a thin pool's metadata device or a metadata file. Reading metadata is normally an unprivileged operation only when your account can read the path. Do not grant yourself broad permissions just to make a report work.

1. Confirm the installed command

Start with read-only checks. These commands do not need elevated privileges:

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

Your executable path may differ. The package version and the program version are separate pieces of useful evidence, because a distribution can package a release with its own revision.

Checkpoint: the command should print a version and exit successfully. If it is missing, stop here and use your normal package-management process. This guide does not install packages.

2. Identify the metadata path

thin_ls expects the pool's metadata device, not the pool's data device. In an LVM thin pool, the metadata LV commonly has a name ending in _tmeta, but do not infer the path from that suffix alone. Confirm it from your storage inventory and the LVM metadata.

For an LVM-managed host, an ordinary inventory command is:

$ lvs -a -o vg_name,lv_name,lv_attr,lv_size,lv_role
  VG       LV              Attr       LSize   LV Role
  VG_NAME  POOL_NAME       twi-a-tz--  100.00g thin-pool
  VG_NAME  POOL_NAME_tdata -wi-a-----  100.00g linear
  VG_NAME  POOL_NAME_tmeta -wi-a-----    2.00g linear

Replace VG_NAME and POOL_NAME with values from your host. The exact columns and formatting vary with the LVM version. The useful result is the path for the metadata LV, such as /dev/VG_NAME/POOL_NAME_tmeta. The tdata path is not the input for this command.

This inventory is read-only, but lvs may need elevated privileges on a restricted system. If so, run only the inventory command with sudo; do not make the later reporting command root-only without a reason.

3. Test the path before querying a pool

Check that the candidate path exists and is readable. The following is a path check, not a pool operation:

$ META_DEV=/dev/VG_NAME/POOL_NAME_tmeta
$ test -r "$META_DEV" && echo "metadata is readable"
metadata is readable

Use a shell variable only after replacing the placeholder with the exact path. Quoting it keeps whitespace or shell metacharacters in a path from changing the command. If the test fails, check the path and permissions. Do not point thin_ls at the data LV as a guess.

A deliberately missing path demonstrates the failure shape without touching storage:

$ thin_ls /tmp/no-such-thin-metadata
Couldn't stat path
$ printf 'exit status: %s\n' "$?"
exit status: 1

The error text is concise, and the non-zero status is the part scripts should rely on. Do not interpret an error as evidence that the pool is damaged until the input path has been checked.

4. Query a stable metadata source

The manual warns that live metadata cannot be read directly. For a live pool, first obtain a metadata snapshot using the storage workflow appropriate to your deployment, then pass that snapshot to thin_ls with --metadata-snap. Taking a snapshot is a storage-management action and can affect service behaviour, capacity or your recovery plan, so it is outside this read-only example. Follow your platform's documented procedure and record how to remove the snapshot afterwards.

Once you have a safe metadata path, the basic report is:

$ thin_ls "$META_DEV"
DEV MAPPED_BLOCKS EXCLUSIVE_BLOCKS SHARED_BLOCKS MAPPED_SECTORS EXCLUSIVE_SECTORS SHARED_SECTORS MAPPED_BYTES EXCLUSIVE_BYTES SHARED_BYTES MAPPED EXCLUSIVE SHARED TRANSACTION CREATE_TIME SNAP_TIME
... host-specific rows ...

The rows and values depend on the pool. Do not copy the displayed ellipsis into a script. A successful exit status means the metadata was read, not that every thin volume is healthy or mounted.

For a snapshot path, use:

$ thin_ls --metadata-snap /path/to/metadata-snapshot

The option tells thin_ls that the input is a metadata snapshot. It is not a command to create one. Do not add it to a live metadata path unless your snapshot workflow really produced the required snapshot.

5. Select fields for a useful report

The default output is wide. Use -o or --format with a comma-separated list of fields when a report needs only a few values:

$ thin_ls --format DEV,MAPPED_BYTES,EXCLUSIVE_BYTES,SHARED_BYTES "$META_DEV"
DEV MAPPED_BYTES EXCLUSIVE_BYTES SHARED_BYTES
... host-specific rows ...

The installed command accepts these fields: DEV, block, sector and byte counters for mapped, exclusive and shared space, the MAPPED, EXCLUSIVE and SHARED flags, plus TRANSACTION, CREATE_TIME and SNAP_TIME. Spell field names as shown. If a field is absent or misspelled, the command rejects the request rather than silently inventing a value.

For machine-readable, header-free output, combine a deliberately chosen format with --no-headers:

$ thin_ls --no-headers --format DEV,MAPPED_BYTES "$META_DEV"
... host-specific rows without the header ...

Keep the field order in the command and in the parser together. If a script needs a header, write one in the script or leave the header enabled. Do not parse the default wide report by assuming that its columns will never change.

6. Diagnose the common mistakes

If a live metadata device is rejected, stop and use a metadata snapshot. Re-running the same command with sudo does not make live metadata safe to read. If the command cannot stat the path, check the exact device node, whether the volume is active, and whether your account can read it.

If the report has no rows, first verify that you supplied the metadata device rather than the pool data device and that the selected fields are valid. A report is not a substitute for checking the pool's LVM state or thin-volume consumers.

There is no undo operation for these reporting commands: they do not alter the metadata. Snapshot creation and removal are different operations. Before creating one for an investigation, document the snapshot name, owner, expected lifetime and removal command. Never delete a snapshot merely because a report is complete if another recovery or monitoring process still needs it.