grub-fstest

grub-fstest [OPTION...] DISK_IMAGE [COMMAND...]

-r, --root=DEVICE
    Set the root device for GRUB (e.g., (hd0,msdos1)). This specifies the device where GRUB should look for its root filesystem.

-p, --prefix=PATH
    Specify the GRUB prefix path (e.g., /boot/grub). This indicates where GRUB modules and configuration files are located relative to the root device.

-d, --debug
    Enable verbose debug messages during operation. Useful for troubleshooting filesystem driver issues.

-s, --skip-fs-probe
    Do not attempt to probe filesystems from the specified DISK_IMAGE. Useful if the filesystem is known or provided via --root, or to speed up startup.

-N, --no-grub-modules
    Prevent loading GRUB modules. This can be used for basic testing or when module loading is not desired or causes issues.

-v, --verbose
    Print more detailed information about the command's execution, including progress and actions taken.

-V, --version
    Display version information about grub-fstest and exit.

-h, --help
    Show a help message with usage instructions and available options, then exit.

grub-fstest is a utility from the GRUB (GRand Unified Bootloader) project designed to test and debug GRUB's internal filesystem drivers. It allows users to "mount" a disk image file or a physical device and interact with the filesystems on it using GRUB's own filesystem handling code, rather than the host system's kernel. This makes it invaluable for verifying GRUB's ability to read from various filesystems (like ext2/3/4, FAT, NTFS, HFS+, Btrfs, XFS, etc.), troubleshooting GRUB boot issues, or even inspecting the contents of GRUB installations or problematic disk partitions from a GRUB perspective. It supports a range of subcommands similar to standard Linux utilities (e.g., ls, cat, cp, stat, md5sum), enabling comprehensive testing and inspection without requiring a full GRUB boot environment. It operates by simulating GRUB's environment to test its filesystem access capabilities directly.

grub-fstest operates with GRUB's own filesystem drivers, which might behave differently or support a distinct set of features compared to the host operating system's kernel. Therefore, results may not always perfectly mirror the host system's filesystem view. It is primarily a debugging and testing tool for GRUB's capabilities. While generally read-only for inspection, care should be taken when using it on live physical devices to avoid any unintended interference with system operation.

grub-fstest supports a variety of subcommands that mimic standard Linux utilities, allowing for file system interaction within the GRUB environment. These commands operate on the specified DISK_IMAGE using GRUB's internal filesystem drivers.

Examples include:
ls PATH: List directory contents.
cat PATH: Print file contents to standard output.
cp SRC DST: Copy a file from source to destination within the GRUB context.
md5sum PATH: Compute and check MD5 checksums of files.
stat PATH: Display file or file system status, including size, type, and timestamps.
hexdump PATH: Display file contents in hexadecimal, decimal, octal, or ASCII format.
cmp FILE1 FILE2: Compare two files byte by byte.
diff FILE1 FILE2: Output the differences between two files.
And many more, enabling comprehensive filesystem testing and inspection of GRUB-accessible data.

grub-fstest is an integral part of the GRUB 2 development suite. Its primary purpose emerged from the need to rigorously test and ensure the robustness of GRUB's sophisticated filesystem handling capabilities independent of a full boot cycle. As GRUB 2 aimed to support a wider array of filesystems and partitioning schemes than its predecessor, a dedicated tool for isolated filesystem driver testing became essential for developers to debug and verify new implementations or regressions efficiently. Its usage grew among system administrators and power users for diagnosing boot issues related to filesystem access or for recovering data from unbootable systems by leveraging GRUB's unique filesystem perspective.

grub-mkconfig(8), grub-install(8), grub(8), debugfs(8)