Safely Run thin_trim on an Offline Thin Pool

thin_trim sends discard requests for the unprovisioned parts of a thin pool, and it refuses to run on a pool that is still live. This builds a checked command line for it, step by step, so the offline requirement never gets skipped. The local installation is thin-provisioning-tools 0.9.0-2ubuntu5.1, with thin_trim reporting version 0.9.0.

Allow about fifteen minutes for the checks, plus however long your storage takes to process discards. You need shell access, the exact metadata and data paths for the pool, and an approved maintenance window. This is an offline storage operation. Do not use it against a live metadata device, and do not treat a successful exit as a substitute for a backup or a recovery plan.

1. Confirm the installed command

Start with read-only commands. They do not need elevated privileges unless your system hides the binary or package database from your account:

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

Your path and package revision can differ. The important check is that you are about to run the intended binary, not a similarly named wrapper from another installation.

Checkpoint: inspect the option contract as well:

$ thin_trim --help
Usage: thin_trim [options] --metadata-dev {device|file} --data-dev {device|file}
Options:
  {-h|--help}
  {-V|--version}

The installed tool has no dry-run switch, verbosity switch or confirmation prompt documented by its manpage. Plan the checks outside the command, before invoking it.

2. Identify both pool inputs

thin_trim requires two named inputs: --metadata-dev identifies the thin-pool metadata device or file, and --data-dev identifies the corresponding data device or file. Use the exact pair belonging to one pool. Do not substitute the mounted thin volume, a filesystem path inside it, or a different pool's metadata.

Resolve device-mapper names and paths with your normal storage inventory commands. For example, these commands only display information:

$ ls -l /dev/mapper/POOL_METADATA /dev/mapper/POOL_DATA
$ readlink -f /dev/mapper/POOL_METADATA
$ readlink -f /dev/mapper/POOL_DATA

Replace POOL_METADATA and POOL_DATA with names from your own inventory. Do not copy these placeholder paths into a production command. If your pool uses regular files instead of block devices, use the complete file paths and verify that the two files are the intended metadata and data members.

Checkpoint: write down the resolved pair before continuing. A path that exists is not necessarily the right pool member.

3. Stop use of the pool before trimming

The manpage states that this tool cannot be run on live metadata. Arrange the maintenance action that makes the metadata offline according to your pool manager and service design. In practice, that normally means stopping writers, unmounting affected filesystems, and deactivating the thin-pool mapping. The exact commands depend on whether the pool is managed by LVM, device-mapper directly, a virtualisation stack or another layer, so do not apply a guessed sequence.

This is the service-disrupting checkpoint. Record how you will restore the mapping and start the dependent services before you stop anything. Confirm that no process still has the thin pool open, using the read-only checks appropriate to your host:

$ findmnt --source /dev/mapper/THIN_VOLUME
$ lsblk --fs
$ fuser -vm /dev/mapper/POOL_DATA

Output is host-specific. An empty result from a check is useful only when that check covers the actual mapping. If a filesystem remains mounted or a writer is still active, stop here. There is no undo option in thin_trim for restoring discarded storage blocks.

4. Review the final command without running it

Once the pool is offline and the pair has been independently checked, assemble the command with shell variables. This keeps long paths visible and makes the two roles explicit:

$ METADATA_DEV='/dev/mapper/POOL_METADATA'
$ DATA_DEV='/dev/mapper/POOL_DATA'
$ printf 'metadata: %s\ndata: %s\n' "$METADATA_DEV" "$DATA_DEV"
metadata: /dev/mapper/POOL_METADATA
data: /dev/mapper/POOL_DATA

Read the printed values character by character. Quoting prevents spaces or shell metacharacters in a file path from changing the argument boundaries, but it cannot protect you from choosing the wrong device.

Before the destructive step, compare the values with your storage documentation, change record and any backup or snapshot record. If the pool contains valuable data, make sure the recovery procedure has been tested separately. Discard requests may be passed down to the underlying storage and are not a general-purpose data-erasure undo mechanism.

5. Issue the discard requests

Running the tool normally requires elevated privileges because it opens storage devices and asks them to process discard requests. Use the smallest approved privilege boundary for your environment:

$ sudo thin_trim --metadata-dev "$METADATA_DEV" --data-dev "$DATA_DEV"
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means the command completed successfully. The tool may not print a progress report. A non-zero status means the operation did not complete as requested; preserve the error text, do not immediately repeat it, and investigate the exact device state and storage-layer logs.

There is no rollback command documented for this program. If you discover that the wrong device was selected, stop immediately and preserve the command output and host state for incident review. Do not try a second trim as a repair.

6. Verify the pool and restore service

Use your pool manager's read-only status command to confirm that the expected pool members remain associated and that the pool is healthy. Then restore the mapping, mounts and services in the reverse of the maintenance procedure you recorded earlier. Do not infer health solely from thin_trim's exit status.

After the pool is available again, verify the actual consumer rather than only the block devices:

$ findmnt --source /dev/mapper/THIN_VOLUME
$ lsblk --fs
$ df -h /path/to/mount

Replace THIN_VOLUME and /path/to/mount with the real mapping and mount point. Check the service's own health command and logs as well. The discard operation concerns unprovisioned pool space; it does not validate application data, filesystem consistency or backup recoverability.

Common traps

Done means