Inspect a GRUB Filesystem Image Safely with grub-mount

When you need to look inside a disk image without letting the kernel near it, grub-mount exposes it read-only through FUSE at a directory you choose. Browse it like any other folder, then unmount cleanly when done. Allow about 15 minutes for a known-good image, longer if you need to work out which partition you actually want on a whole-disk image.

The examples match GRUB 2.12-1ubuntu7.3 from the Debian package grub-common installed on this machine. This is a debugging tool, not a general replacement for mount: it only understands filesystems the GRUB build supports, and it is only available when GRUB was built with FUSE support at all.

1. Check the installed command

Version and help output first. Neither reads an image or changes a mount:

$ grub-mount --version
grub-mount (GRUB) 2.12-1ubuntu7.3
$ grub-mount --help
Usage: grub-mount [OPTION...] IMAGE1 [IMAGE2 ...] MOUNTPOINT

The positional arguments are one or more images followed by the mountpoint. The local manual calls this a debug tool for a filesystem driver; upstream describes the resulting mount as read-only, with multiple images treated as a RAID set.

2. Prepare a mountpoint you control

Use a dedicated, existing directory in a working area. Creating it is an ordinary filesystem change, so pick a path with nothing you need to preserve:

$ mkdir -p "$HOME/tmp/grub-image-view"
$ ls -ld "$HOME/tmp/grub-image-view"
drwxr-xr-x ... /home/you/tmp/grub-image-view

Never point the command at a directory used by a live service, a system mount, or anywhere else you expect its current contents to stay visible: while the FUSE view is active, the image contents are what appears at that path.

You normally need no elevated privilege when both the image and mountpoint are accessible to your user. A block device like /dev/sda1 may need extra read permission, but do not widen access further than that just for convenience.

3. Mount a filesystem image

For a filesystem contained directly in a file, pass the image then the mountpoint:

$ grub-mount /path/to/filesystem.img "$HOME/tmp/grub-image-view"

Swap in a real image path. The command stays attached to the mount in the foreground while the view is active, so open another terminal to inspect the files:

$ find "$HOME/tmp/grub-image-view" -maxdepth 2 -type f -print
$ stat "$HOME/tmp/grub-image-view/path/inside/the/image"

Both of those only read through the FUSE view; the source image is untouched. If the mount itself errors out, keep the error text and check the image path, read permission and filesystem type before changing anything.

4. Select a partition inside a whole-disk image

A whole-disk image can hold a partition table rather than a filesystem at its outermost level. --root selects the GRUB root device, and a bare number is treated as a partition number within the supplied image:

$ grub-mount --root=2 /path/to/disk.img "$HOME/tmp/grub-image-view"

That selects partition 2, not a byte offset, a Linux device name, or a filesystem label. Confirm the number from your image inventory before running it. If you already have a separate partition image, leave --root off; GRUB normally sets the root device to the root of the supplied filesystem.

5. Handle encryption and ZFS deliberately

--crypto asks grub-mount to mount encrypted devices, prompting for a passphrase when needed:

$ grub-mount --crypto /path/to/encrypted.img "$HOME/tmp/grub-image-view"

For ZFS encryption, the installed command accepts --zfs-key=FILE or --zfs-key=prompt. A key file is sensitive: check its ownership and permissions before use, and remove any temporary copy through your normal secure key-handling process once the inspection is done. Neither option makes an unsupported filesystem readable.

6. Unmount and remove the temporary directory

When you are finished, go back to the terminal running grub-mount and stop it with Ctrl+C. Then check the directory before removing it:

$ find "$HOME/tmp/grub-image-view" -maxdepth 1 -mindepth 1 -print
$ rmdir "$HOME/tmp/grub-image-view"

rmdir only removes an empty directory. If it complains the directory is still in use, confirm the grub-mount process has actually stopped and no terminal still has it as its working directory before trying again. If you deliberately left files there yourself, check and remove them individually first.

Diagnose the common failures

• No image and mountpoint: the command prints grub-mount: error: need an image and mountpoint. and exits with status 1 on this install, a malformed invocation rather than a failed filesystem probe.
• Cannot open the image: check it without changing state, using ls -l and test -r on the image path.
• Filesystem not recognised: check whether you actually supplied a filesystem image versus a whole-disk one, and revisit the partition number and --root if needed.
• Encrypted or ZFS image: use --crypto only with the key material in hand and the security implications understood. The local manpage does not promise support for every filesystem, encryption format or partition layout.

$ grub-mount
grub-mount: error: need an image and mountpoint.
$ printf '%s\n' "$?"
1

$ ls -l /path/to/filesystem.img
$ test -r /path/to/filesystem.img && echo readable

Use --verbose for additional diagnostic messages, and --debug=STRING when you already know which GRUB debug setting you need. Keep both for troubleshooting only, verbose output is not a substitute for checking the image and partition you actually selected.