Regenerate GRUB Safely with update-grub

You will regenerate the configuration at /boot/grub/grub.cfg, check that the new file was installed, and know where to look when generation fails. On this machine, update-grub comes from grub2-common version 2.12-1ubuntu7.3. The command is a small wrapper around grub-mkconfig; it is not a menu editor.

Allow about ten minutes, plus time to review any boot setting you are changing. You need an administrator shell and a working GRUB installation. This guide changes the generated boot configuration, so keep recovery access available before you start. Do not run it as a routine experiment on a remote machine unless you have a tested way to reach the console or repair its boot files.

1. Check the setting before regenerating

GRUB reads its main distribution configuration from /etc/default/grub. It also reads matching configuration fragments from /etc/default/grub.d/, then runs executable scripts in /etc/grub.d/. Inspect the relevant files first:

$ sudo sed -n '1,220p' /etc/default/grub
$ sudo find /etc/default/grub.d -maxdepth 1 -type f -name '*.cfg' -print 2>/dev/null
$ sudo find /etc/grub.d -maxdepth 1 -type f -perm /111 -printf '%f\n' | sort

Use sudo for these reads if your account cannot read the files. Do not edit /boot/grub/grub.cfg by hand. It is generated output and the next update will replace it.

2. Make one controlled configuration change

If you need a different menu timeout, for example, edit the existing setting in /etc/default/grub with an editor you understand:

$ sudoedit /etc/default/grub

Keep the file valid POSIX shell input. A simple assignment is safe to read back later, such as GRUB_TIMEOUT=5. Values containing spaces or shell punctuation need quoting. Do not paste untrusted text into this file: it is sourced as shell code during generation.

Save a copy before editing if you want a quick undo:

$ sudo cp -p /etc/default/grub /etc/default/grub.backup-before-grub-update

To undo this example before regenerating, restore that copy and inspect it:

$ sudo cp -p /etc/default/grub.backup-before-grub-update /etc/default/grub
$ sudo sh -n /etc/default/grub

The shell syntax check is only a check. It does not validate that a GRUB variable has the result you intended.

3. Regenerate the GRUB configuration

Run the wrapper as root:

$ sudo update-grub
Sourcing file `/etc/default/grub'`
Generating grub configuration file ...
done

The exact source-file lines vary with installed fragments and scripts. The important result is a successful exit and the final done message. The installed wrapper executes grub-mkconfig -o /boot/grub/grub.cfg, so no output filename is needed. The update-grub2 name is an alias for the same operation on this system.

4. Verify the generated file

Check the exit status immediately when you use the command in a script or automation:

$ sudo update-grub
$ status=$?
$ printf 'update-grub exit status: %s\n' "$status"
update-grub exit status: 0

Then confirm that the target exists, is owned by root, and contains generated content:

$ sudo stat -c '%U %G %a %s %n' /boot/grub/grub.cfg
root root 600 12345 /boot/grub/grub.cfg
$ sudo sed -n '1,16p' /boot/grub/grub.cfg

The size is only an example and will differ. The opening comments should identify the file as automatically generated. Do not treat a plausible file size as proof that every desired menu entry is present. Search for a known entry when you have a specific one to check:

$ sudo grep -nF 'menuentry' /boot/grub/grub.cfg | head

5. Diagnose a failed update without guessing

If the command exits non-zero, read the error before retrying. A syntax error in /etc/default/grub or an executable script in /etc/grub.d/ can stop generation. Check the shell syntax of files you changed, and inspect permissions and recent edits:

$ sudo sh -n /etc/default/grub
$ sudo ls -l /etc/grub.d
$ sudo find /etc/default/grub.d -maxdepth 1 -type f -name '*.cfg' -exec sh -n '{}' \;

Generation uses a temporary file beside the target and validates it before installing it. A failed run should not be treated as permission to edit the existing grub.cfg manually. Fix the reported source file, run the checks again, and regenerate.

For a harmless capability check, ask the underlying command for help. This exits before generation:

$ grub-mkconfig --help
Usage: grub-mkconfig [OPTION]
Generate a grub config file

Do not use grub-mkconfig --output=/tmp/test.cfg as a substitute for the real update without understanding the environment. A different output path still runs the discovery scripts, and it may not reproduce the machine's normal boot configuration context.

6. Recover from an unwanted change

If you have not rebooted, the previous boot configuration may still be available in your backups or package-managed recovery process. Restore the configuration source that caused the problem, then run sudo update-grub again. For the example backup above:

$ sudo cp -p /etc/default/grub.backup-before-grub-update /etc/default/grub
$ sudo sh -n /etc/default/grub
$ sudo update-grub

If the machine is already unable to boot, use its provider console or boot a trusted recovery environment. Mount the installed system, repair /etc/default/grub or the relevant /etc/grub.d/ file, then chroot according to that distribution's documented recovery procedure. Do not delete /boot/grub/grub.cfg as a first response.