Size a Thin-Pool Metadata Device with thin_metadata_size

Guess a thin pool's metadata device too small and you rebuild it later under pressure; thin_metadata_size exists so you never have to guess. It calculates an initial size, in whatever unit suits your storage plan, before you provision anything. The examples use thin_metadata_size 0.9.0 from the installed thin-provisioning-tools package.

Allow about ten minutes. You need a shell and the package installed. This guide only calculates a number: it does not create a logical volume, format a device, activate a pool or change existing storage, so no elevated privileges are needed for the examples.

1. Confirm the local tool

Check which executable your shell will run and record its version:

$ command -v thin_metadata_size
/usr/sbin/thin_metadata_size
$ thin_metadata_size --version
0.9.0

The path can differ between distributions. The version matters because the calculation and accepted unit spellings belong to the installed build. If the command is missing, install the distribution's thin-provisioning-tools package using your normal package-management process, then repeat this check.

Checkpoint: Continue only when thin_metadata_size --version exits successfully. The command does not inspect your current thin pool, so it is safe to run on a host that is serving workloads.

2. Supply the three planning inputs

The calculation needs the thin-device block size, the total pool size and the maximum combined count of thin devices and snapshots. The short options are -b, -s and -m:

$ thin_metadata_size -b64k -s1t -m1000
thin_metadata_size - 1073224 sectors estimated metadata area size for "--block-size=64kibibytes --pool-size=1tebibytes --max-thins=1000"

Here, 64k is a 64-kibibyte block size, 1t is a tebibyte pool and 1000 is the maximum sum of all thin devices and snapshots. With no unit on an input, the tool interprets block and pool sizes as sectors, and interprets -m as an absolute count. Add units deliberately rather than relying on those defaults.

The result above is in sectors because the output unit was not specified. It is an estimate for the metadata area, not a command that allocates that many sectors.

3. Make the result script-friendly

Use --unit when another unit is easier to compare with your storage plan, and --numeric-only when another command will consume the result:

$ thin_metadata_size --block-size=1g --pool-size=1P --max-thins=1M --unit=G --numeric-only
4.13

This asks for a 1-gibibyte block size, a 1-petabyte pool and one million combined thin devices and snapshots. The output is the number in gigabytes, with no label. The installed tool accepts short unit letters and long unit names, so the equivalent long-form inputs are:

$ thin_metadata_size --block-size=1gibi --pool-size=1petabytes --max-thins=1mega --unit=G --numeric-only=short
4.13G
$ thin_metadata_size --block-size=1gibi --pool-size=1petabytes --max-thins=1mega --unit=G -nlong
4.13gigabytes

-n and --numeric-only accept short or long. Bare --numeric-only omits the unit identifier. Do not confuse the input suffix G with the output request: input and output units are controlled separately.

4. Match the estimate to the real pool design

Before creating a metadata device, rerun the calculation with the largest values your design permits. Include snapshots in --max-thins, not just currently active thin volumes. A pool planned for 100 thin volumes and 900 snapshots needs --max-thins=1000.

Keep a record of the exact command and its output alongside the storage layout. This is especially useful when the result is rounded for a platform-specific logical-volume size. The calculator gives an estimated metadata area size; it does not select a device name, reserve free extents or validate your volume group's geometry.

Safety boundary: Do not treat the printed value as permission to overwrite an existing metadata device. Commands that create, initialise or replace thin-pool metadata can destroy recoverable state. Stop and take a verified backup before changing live storage, and follow the storage manager's documented recovery procedure if the estimate was wrong. There is no undo operation in thin_metadata_size because it makes no state change.

5. Diagnose the common failures

A missing required input produces a non-zero exit status. For example:

$ thin_metadata_size -s1t -m1000
thin_metadata_size - block size required!
$ printf '%s\n' "$?"
1

Capture the status immediately if a script needs to react to failure. The documented success status is 0 and the documented error status is 1. A message about a required value usually means that -b, -s or -m was omitted, misspelled or not passed as the value expected by the option.

If a result looks implausible, inspect each suffix first. The tool distinguishes bytes, sectors, kibibytes, kilobytes and larger units according to the suffix supplied. A bare input is not automatically interpreted as bytes. Then compare the requested output unit with the unit shown in the output. For automation, prefer --numeric-only and check the exit status instead of scraping the descriptive sentence.

Done means