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.
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 ...] MOUNTPOINTThe 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.
Checkpoint: if grub-mount --version fails, stop and check that grub-common is installed. Do not substitute an unverified option from a different GRUB release.
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-viewNever 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.
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.
Checkpoint: confirm a file you expect is actually visible below the mountpoint. An empty or unexpected directory does not prove the image is empty, it can equally mean the wrong image, the wrong partition, or a filesystem this GRUB build cannot read.
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.
Warning: a wrong partition number can still mount successfully if it happens to contain a supported filesystem. Treat the image as untrusted data, and do not execute anything from inside it.
--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"
Security warning: entering a passphrase is security-sensitive. Only do it with an image and mountpoint you have deliberately chosen, make sure nobody can see the terminal, and never let the passphrase end up in shell history or a process argument.
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.
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.
Warning: never run a recursive delete against a path you have not checked. The image view itself is read-only, but careless cleanup can still remove unrelated files if the mountpoint path is mistyped.
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.ls -l and test -r on the image path.--root if needed.--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.
grub-mount were checked.--root.