Inspect XFS Free Space Safely with xfs_spaceman

xfs_spaceman inspects free space, checks XFS geometry and reports metadata health, plus the commands that actually change storage. The examples target xfsprogs 6.6.0, the version installed on this machine.

Allow about fifteen minutes for read-only inspection. You need an XFS filesystem and a mount point you can read. The command normally runs without sudo for inspection, although access to a protected mount or device may require elevated privileges.

Safety boundary: trim releases backing storage for free space, and prealloc removes speculative preallocation. Treat both as operational changes. Start with the read-only commands below, and do not run a change command on a production filesystem without an explicit maintenance decision.

1. Check the installed command

Confirm which binary and package version you are using. This is an ordinary, read-only check:

$ command -v xfs_spaceman
/usr/sbin/xfs_spaceman
$ xfs_spaceman -V
xfs_spaceman version 6.6.0
$ dpkg-query -W -f='${Package} ${Version}\n' xfsprogs
xfsprogs 6.6.0-1ubuntu2.1

Your package revision can differ. The installed manpage is the contract for the examples here; do not assume that a command from another xfsprogs release has identical output.

2. Choose the filesystem path

Use the mount point as the file argument. Replace /srv/data with the path for the XFS filesystem you intend to inspect:

$ findmnt -t xfs
$ FS_MOUNT=/srv/data
$ findmnt --target "$FS_MOUNT" --output TARGET,SOURCE,FSTYPE
TARGET  SOURCE       FSTYPE
/srv/data /dev/mapper/data xfs

The displayed source and mount point are host-specific. Check that they identify the right filesystem before continuing. A typo can select a different mount, while a path that is not on XFS will be rejected or will not provide the information you expect.

Checkpoint: Stop here if findmnt does not show xfs for your chosen path. The info command specifically requires its opened file to be an XFS mount point.

3. Read the free-space histogram

Run freesp without options for the default histogram. The default bins use successive powers of two:

$ xfs_spaceman -c 'freesp' "$FS_MOUNT"

The exact rows depend on allocation-group layout and current use, so do not copy a sample histogram into a report. The useful result is a distribution of free-space extents rather than a single free-capacity number.

Add a summary when you want the aggregate information as well:

$ xfs_spaceman -c 'freesp -s' "$FS_MOUNT"

Use -g to show free-space block and extent counts for each allocation group. Use -a to restrict collection to a particular AG; it can be repeated:

$ xfs_spaceman -c 'freesp -g -a 0 -a 1' "$FS_MOUNT"

Allocation-group numbers are filesystem-specific. Discover them from the command's output or filesystem documentation rather than assuming that a given number exists.

4. Select a different histogram shape

The histogram modes are mutually exclusive. The default -b uses powers of two. Use -e bsize for one repeated bin size, -h bsize for explicit lower bounds, or -m factor when each bin should be a multiple of the previous one.

$ xfs_spaceman -c 'freesp -e 1m -s' "$FS_MOUNT"
$ xfs_spaceman -c 'freesp -h 64k -h 1m -h 16m -s' "$FS_MOUNT"

Units can be used where the command accepts a size. Do not combine -e, -h or -m with one another or with -b. If you need raw extent details for troubleshooting, add -d; expect substantially more output.

For a realtime device, freesp -r queries realtime free-space information. Use it only when the filesystem has a realtime device; an ordinary data-device histogram is a clearer first check.

5. Inspect geometry and metadata health

Ask for selected filesystem geometry with info:

$ xfs_spaceman -c 'info' "$FS_MOUNT"

This uses the same output format as xfs_info when querying a filesystem. For health reporting, start with the whole filesystem and ask only for unhealthy metadata when you are triaging:

$ xfs_spaceman -c 'health -f' "$FS_MOUNT"
$ xfs_spaceman -c 'health -q' "$FS_MOUNT"

Other useful scopes are an allocation group with -a AGNO, an inode with -i INUM, or a file path supplied to health. The -c health option scans inodes and can be much more expensive than a summary, so use it deliberately:

$ xfs_spaceman -c 'health -a 0' "$FS_MOUNT"
$ xfs_spaceman -c 'health -i 12345' "$FS_MOUNT"
$ xfs_spaceman -c 'health -c' "$FS_MOUNT"

An empty or healthy result is evidence from that check, not a substitute for backups or a complete incident investigation.

6. Understand the commands that change state

prealloc removes speculative preallocation. With no -u, -g or -p filter, it acts on all files. Narrow it by user, group or project ID, and use -m to ignore files below a minimum size:

$ sudo xfs_spaceman -c 'prealloc -u 1001 -m 1m -s' "$FS_MOUNT"

The -s option waits for removal to complete. There is no general undo command in this interface: once speculative preallocation is removed, normal filesystem activity must allocate space again if it needs it. Confirm the filters and maintenance window before pressing Enter.

trim instructs the underlying storage device to release backing storage for free space. It requires one scope: an allocation group, the whole filesystem with -f, or an explicit physical offset and length. The scopes are mutually exclusive:

$ sudo xfs_spaceman -c 'trim -a 0 -m 1m' "$FS_MOUNT"

That command can affect storage performance and thin-provisioned capacity. There is no safe rollback for a completed discard. Do not use trim -f as a casual space-recovery shortcut, and do not guess an offset or length. Check the storage policy and backups first.

7. Use interactive mode when exploring

Without -c, the program runs interactively. Multiple -c options run in the order given and then exit, which is useful for a short, repeatable report:

$ xfs_spaceman -c 'freesp -s' -c 'info' -c 'health -q' "$FS_MOUNT"

Use help or help COMMAND inside the tool to check the locally installed syntax. Use quit to leave an interactive session. The print command lists open files, which can help explain why a filesystem remains busy during an investigation.

Done means