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.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm the tool and identify the target
2. Open it read-only
3. Print the primary superblock
4. Move from a path to its inode
5. Examine space and block mappings
6. Keep expert and write operations out of a diagnosis

Time: about 15 minutes for a first inspection.
What you need: the xfsprogs package and the correct block device, filesystem image or copied metadata file.
Privileges: most examples need none, but opening a block device commonly does.
What this will not do: repair, mount, unmount or change the filesystem.

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.

Recover with the right tool. Make a verified image or metadata copy first and use the documented specialist tool for the actual repair. xfs_db is primarily an examiner.
Do not chase a write prompt. If a command unexpectedly asks for write access, stop and re-check every option and target rather than adding -x until it works.
Read the narrow options carefully. -F continues when the superblock magic is not correct, for use with xfs_metadump, not as a general way to force an arbitrary file to be treated as a valid filesystem. -i permits operation on a mounted filesystem only when it is mounted read-only, with semantics distinct from -r.

Done means

Versions confirmed. You checked xfs_db and xfsprogs versions and selected the correct target.
Read-only enforced. Inspection used -r, with -f for a regular-file image.
Geometry printed. info, sb 0 and p produced the fields you needed.
Object located. path, ls -i or inode identified the relevant filesystem object.
Space checked. You used freesp or fsmap without enabling expert mode.
Nothing changed. No command used -x or altered filesystem metadata.