Look Inside an XFS Filesystem with xfs_db

xfs_db is the read-only way into an XFS device or image: version, geometry, superblock fields, a chosen inode and free space. Point it at a target and walk through those checks without writing a single byte back to the filesystem. The examples match xfs_db 6.6.0 from xfsprogs 6.6.0-1ubuntu2.1.

1. Confirm the tool and identify the target

Check the version, then resolve the target before opening it. Replace the placeholder with the XFS device or image you intend to examine.

$ xfs_db -V
xfs_db version 6.6.0
$ findmnt --source /dev/EXAMPLE_XFS_DEVICE --output SOURCE,TARGET,FSTYPE,OPTIONS

The version command exits immediately. The findmnt result is a useful guard against pointing at the wrong disk. If the target is mounted, record whether it is read-only before continuing.

Checkpoint: You have a specific XFS target, and you know whether it is a mounted filesystem, an unmounted device, or a regular file containing an XFS image.

2. Open it read-only

Use -r for an ordinary device or filename. The option is required when the filesystem is mounted. If the image is a regular file made by copying an XFS filesystem, add -f as well.

$ sudo xfs_db -r -c 'info' /dev/EXAMPLE_XFS_DEVICE
$ xfs_db -f -r -c 'info' /path/to/xfs-image

info prints selected geometry in the same general format used by mkfs.xfs and xfs_info. The first command may need sudo only because the device permissions require it; keep the command unprivileged for a readable image file.

Warning: Do not omit -r as a shortcut. Without it, xfs_db opens for possible modification. The manpage says the flag may be skipped only when a command that changes data, such as write, blocktrash or crc, is actually intended. That is not a safe default for diagnosis.

3. Print the primary superblock

Use multiple -c options when a short inspection should be non-interactive. Commands run in the order supplied and the program then exits.

$ sudo xfs_db -r \
    -c 'sb 0' \
    -c 'p magicnum blocksize dblocks agcount fdblocks uuid' \
    /dev/EXAMPLE_XFS_DEVICE

sb 0 selects the superblock for allocation group 0. The following p prints the requested fields at the current address. Field expressions can be nested and indexed, so you can narrow a large structure instead of dumping every field.

To browse interactively, start the same way without -c:

$ sudo xfs_db -r /dev/EXAMPLE_XFS_DEVICE
xfs_db> sb 0
xfs_db> p uuid blocksize agcount
xfs_db> quit

The prompt name is configurable with -p, but that changes presentation only. help displays command help inside the session; quit exits without changing the filesystem.

4. Move from a path to its inode

When you are investigating a file or directory, path walks the directory tree to an inode. ls lists a directory, and ls -i resolves supplied paths to inode numbers.

$ sudo xfs_db -r \
    -c 'path /var/lib/example/data.db' \
    -c 'p core.mode core.uid core.gid core.size core.nblocks' \
    /dev/EXAMPLE_XFS_DEVICE

The path must exist within the XFS filesystem, not merely in the host namespace. If you only know the directory, inspect it first:

$ sudo xfs_db -r \
    -c 'path /var/lib/example' \
    -c 'ls -i' \
    /dev/EXAMPLE_XFS_DEVICE

If you already have an inode number, use inode INODE_NUMBER and then print its fields. Inode numbers are filesystem data, so do not confuse them with process IDs or host-side file descriptors.

Checkpoint: Your command reaches the expected object and prints fields from the selected structure. If a path fails, recheck the spelling and target device before trying broader commands.

5. Examine space and block mappings

Use freesp for a histogram of free extents. Add -s when you also want totals for free extents, free blocks and average extent size.

$ sudo xfs_db -r -c 'freesp -s' /dev/EXAMPLE_XFS_DEVICE

For a device-level map, fsmap lists extents used by files, allocation-group metadata, the journal and static metadata, plus unused regions. Its optional range is in 512-byte blocks, regardless of the filesystem block size.

$ sudo xfs_db -r -c 'fsmap' /dev/EXAMPLE_XFS_DEVICE

Large filesystems can produce a lot of output. Redirecting it to a report is safe, but check the destination and available space first. The blockget and check commands perform broader consistency scans; the manpage warns that a very large filesystem can make the check run out of memory.

6. Keep expert and write operations out of a diagnosis

Warning: Do not use -x on a production filesystem as part of this workflow. Expert mode enables commands including write, blocktrash and CRC invalidation or revalidation. Commands such as fuzz, uuid, label, logformat and some forms of version can also write metadata or have destructive effects, and a mistaken address or field can make the filesystem unmountable.

Done means