Build a GRUB Rescue ISO from a Staging Directory

When a machine will not boot, grub-mkrescue turns a plain directory into a bootable GRUB ISO you can poke at from outside. It never touches real media itself. The workflow below keeps your source tree intact, writes to a named output file, and checks the result before anyone burns a disc or writes a USB stick.

• Time: about fifteen minutes for a small image, longer if you need to install missing helper packages.
• Needs: the installed grub-mkrescue from grub-common, the GRUB platform files, xorriso, and the mformat helper from mtools.

The examples use GRUB 2.12-1ubuntu7.3 from Ubuntu's grub-common package, and none of them need sudo unless you are installing packages or reading files you do not own.

1. Check the local toolchain

grub-mkrescue hands off image creation to xorriso, so a missing helper can make an otherwise correct command fail before it writes anything:

$ grub-mkrescue --version
grub-mkrescue (GRUB) 2.12-1ubuntu7.3
$ command -v xorriso
/usr/bin/xorriso
$ command -v mformat
/usr/bin/mformat

Paths and versions will vary. On a minimal Ubuntu install, mformat can be missing even when grub-common and xorriso are present. If that last check prints nothing, get the package that provides it through your normal package manager, not a blindly pasted install command from somewhere untrusted.

2. Create an isolated image tree

Work in a fresh directory so the image contents stay obvious. The directory you pass as the final argument is a source tree, not the ISO's destination:

$ mkdir -p "$HOME/grub-rescue/iso/boot/grub"
$ printf '%s\n' \
    'set timeout=5' \
    'menuentry "Rescue shell" {' \
    '  echo "Select a real recovery entry before using this image"' \
    '}' > "$HOME/grub-rescue/iso/boot/grub/grub.cfg"
$ printf '%s\n' 'readme from the rescue image' > "$HOME/grub-rescue/iso/README.txt"
$ find "$HOME/grub-rescue/iso" -type f -print
/home/you/grub-rescue/iso/boot/grub/grub.cfg
/home/you/grub-rescue/iso/README.txt

Swap in a directory you actually control. The example configuration is deliberately harmless: it shows the menu working without pretending to be a real recovery system. An actual rescue image usually adds a kernel, an initramfs, diagnostic tools, or a chain-loading entry, each selected and tested for your hardware.

Keep the tree as your source of truth. Editing files inside an already-built ISO is not an undo mechanism; rebuilding from a clean tree keeps every change reviewable.

3. Build to a new output path

Run from outside the source tree and choose an output name that will not clobber anything important:

$ cd "$HOME/grub-rescue"
$ grub-mkrescue --output=grub-rescue.iso iso
$ test -s grub-rescue.iso && echo 'non-empty ISO created'
non-empty ISO created

--output is required. The trailing iso argument is passed to xorriso as an additional source directory, so its contents appear at the root of the resulting image, alongside the GRUB boot structures the command adds itself.

Without mformat, GRUB 2.12 reports something like grub-mkrescue: error: `mformat` invocation failed. That is a missing dependency, not a corrupt build: recheck the helper path, install the package, and rerun the same command. Do not treat a failed build as a usable image.

4. Inspect the image before using it

Start with type and size, both ordinary checks that need no elevated privileges:

$ file grub-rescue.iso
grub-rescue.iso: ISO 9660 CD-ROM filesystem data
$ ls -lh grub-rescue.iso
-rw-r--r-- 1 you you  ... grub-rescue.iso

Exact size and description depend on the GRUB modules, platform targets and source files you used. A zero-byte or suspiciously small file is not a success, whatever the exit status said.

Then confirm your own files actually made it in with xorriso:

$ xorriso -indev grub-rescue.iso -find /boot -type f -print
/boot/grub/grub.cfg
$ xorriso -indev grub-rescue.iso -find / -name README.txt -print
/README.txt

Ignore any xorriso status noise around the listing; the paths themselves are the checkpoint. If something is missing, fix the staging tree and rebuild to a new output name rather than overwriting the source to patch an output-only problem.

5. Add GRUB modules deliberately

The default image ships the normal file set for your installed platform, but a specialised image may need extra modules preloaded. The option takes a quoted, whitespace-separated list:

$ grub-mkrescue --output=grub-rescue-network.iso \
    --modules='net tftp http' \
    iso

Only add modules your configuration and target firmware actually need; a bigger module set means a bigger image and murkier troubleshooting. --install-modules goes the other way, trimming to a named list plus dependencies, but treat that as a compatibility decision rather than a casual size tweak.

Other useful options include --compress=no|xz|gz|lzo, --themes, --locales, --pubkey for an embedded verification key, and --xorriso=FILE for a specific xorriso binary. Anything not owned by grub-mkrescue gets passed to xorriso in mkisofs emulation mode, and a bare -- switches to xorriso's native command mode, so use that only once you have checked xorriso's own option syntax.

6. Test the right boot path

An ISO with all the right files listed can still fail on a specific machine. Test a copy in a virtual machine before you write it to removable media. If you do go on to write to a USB device, double-check the device name: the wrong block device can be destroyed with no guaranteed recovery, and that whole operation sits outside this guide and needs its own backup and device-specific procedure.

Test the firmware mode you actually need, BIOS, UEFI, or both, and make sure it matches the GRUB platform files you built. A successful build proves the image exists, not that a menu entry can boot its kernel, that the initramfs has the right drivers, or that Secure Boot will accept every component. If verification matters, include the correct signing and key material and test on the target class of machine.

If the image is wrong, leave it where it is for diagnosis and rebuild to grub-rescue-v2.iso once the staging tree is fixed. To undo the workflow, remove only the generated ISO files once nothing still needs them; the source tree and any original image are untouched by everything above.