xfs_db

xfs_db [ -c CMD ] ... [ -f ] [ -i ] [ -l LOGFILE ] [ -p PROG ] [ -r ] [ -s ] [ -x ] device

-c CMD
    Executes the specified CMD (command) upon opening the filesystem. Multiple -c options can be provided, with commands executed in the order given. This allows for non-interactive use.

-f
    Specifies that the filesystem image is contained within a regular file, rather than a block device.

-i
    Allows commands that would normally be disallowed on a mounted filesystem, such as commands requiring write access. This option should be used with extreme caution as it can lead to severe data corruption if the filesystem is actively in use.

-l LOGFILE
    Specifies a logfile to which all input commands and output responses from xfs_db will be copied, providing a record of the debugging session.

-p PROG
    Sets the program name that will be displayed in the command prompt during interactive sessions.

-r
    Opens the filesystem in read-only mode. This is the default behavior if the specified filesystem is currently mounted.

-s
    Disables shared exclusive device access, which can be useful in certain diagnostic scenarios.

-x
    Prints all numerical values in hexadecimal format, which is often preferred for low-level filesystem debugging.

device
    The block device node (e.g., /dev/sdb1) or image file containing the XFS filesystem to be debugged.

xfs_db is a powerful utility designed for debugging and inspecting XFS filesystems. It allows users to open a block device or an image file containing an XFS filesystem, providing an interactive command-line interface. This interface enables deep examination and, if necessary, modification of the filesystem's internal structures.

Primarily, xfs_db is intended for XFS filesystem developers, expert administrators, and those needing to diagnose and potentially repair highly corrupted filesystems that xfs_repair cannot handle. It offers direct, low-level access to the filesystem's metadata, making it a potent tool for understanding XFS internals.

Due to its ability to directly manipulate raw filesystem structures, xfs_db carries a significant risk of data loss or further corruption if used incorrectly. Therefore, it is strongly advised to use xfs_repair for standard filesystem checks and repairs. xfs_db should be reserved for advanced diagnostic scenarios or when xfs_repair proves insufficient. It also supports executing commands non-interactively via the -c option, allowing for scripting of specific inspections.

Using xfs_db on a mounted XFS filesystem, especially with options like -i that allow write access, is extremely dangerous and can lead to immediate system crashes, severe data corruption, or an unbootable system. It is highly recommended to unmount the filesystem before using xfs_db or, if unmounting is not possible, to use it in read-only mode (which is the default for mounted filesystems). Always back up critical data before attempting any low-level filesystem manipulation.

Upon launching xfs_db without the -c option, it enters an interactive mode. In this mode, users can issue a variety of commands to navigate and examine different aspects of the XFS filesystem. These commands allow for inspection of superblock information (sb), inode structures (inode), directory entries (dir), allocation group headers (agf, agi), free space maps (freesp), and more. Users can print raw block contents (block), interpret data structures (print), and even write data directly to the filesystem (write), though the latter is highly discouraged unless fully understanding the implications. The help command provides a list of available interactive commands.

xfs_db is a foundational utility within the XFS filesystem toolset, which originated at Silicon Graphics, Inc. (SGI) in the early 1990s. XFS was open-sourced in 2000 and subsequently integrated into the Linux kernel. xfs_db has evolved alongside the XFS filesystem, remaining a critical low-level debugging and inspection tool for developers and advanced administrators.

xfs_repair(8), mkfs.xfs(8), xfs_info(8), xfs_io(8), xfs_admin(8)