Home / Alt manpages / grub-reboot(8)

  • grub-reboot(8)
  • Admin command
  • linux

Set a One-Time GRUB Boot Entry with grub-reboot

Testing a new kernel or booting a recovery entry just once is exactly what grub-reboot is for. It schedules a single menu entry for the next reboot only, leaving your normal default untouched afterwards. Allow about ten minutes, plus whatever time it takes to pin down the exact menu entry you want. The examples target GRUB 2.12-1ubuntu7.3 from Ubuntu's grub2-common package.

The route

Jump straight to the step you need, or tick off Done means at the end.

Warning

This command changes bootloader state, and the very next reboot will follow your choice. Never run it against a remote machine unless you already have a tested way back in if the selected entry fails to come up.

1. Check the installed command

These checks run as your ordinary user and change nothing:

$ command -v grub-reboot
/usr/sbin/grub-reboot
$ grub-reboot --version
grub-reboot (GRUB) 2.12-1ubuntu7.3
$ dpkg-query -W -f='${Package} ${Version}\n' grub2-common
grub2-common 2.12-1ubuntu7.3

Your package revision may differ. What matters is a GRUB installation whose generated configuration supports a saved environment block; the command expects GRUB data under /boot/grub unless you point it elsewhere.

Checkpoint

Stop here if command -v finds nothing, or if this machine does not actually boot through GRUB. Installing or repairing a bootloader is a separate job with a much bigger recovery risk.

2. Choose the entry name GRUB understands

grub-reboot takes one menu entry argument: a number, a visible title, or a menu entry identifier.

  • Numbers are counted from zero at each menu level, so they drift wrong the moment kernels are added or removed.
  • Identifiers are usually the safer bet when your configuration exposes one.

Use the exact spelling and capitalisation GRUB itself displays. Search the generated configuration as your ordinary user to check without changing anything:

$ sudo grep -nE "^(menuentry|submenu) " /boot/grub/grub.cfg
12:menuentry 'Ubuntu, with Linux 6.8.0-xx-generic' --class ubuntu --id 'gnulinux-6.8.0-xx-generic-advanced-...'
27:submenu 'Advanced options for Ubuntu' $menuentry_id_option 'gnulinux-advanced-...'

The output is installation-specific, so treat those lines as a shape to expect rather than values to copy. Reading /boot/grub/grub.cfg normally needs no privilege; sudo is shown only because permissions vary by system. Do not hand-edit grub.cfg for this task.

3. Handle entries inside submenus

For a submenu, join the submenu component and the entry component with a greater-than character and no spaces. Titles, identifiers and numbers can all be mixed:

$ sudo grub-reboot 'Advanced options for Ubuntu>Ubuntu, with Linux 6.8.0-xx-generic'

The single quotes matter: without them the shell reads > as output redirection. The same form works with identifiers:

$ sudo grub-reboot 'gnulinux-advanced-...>gnulinux-6.8.0-xx-generic-advanced-...'

Replace every placeholder with the real value from this machine, not the ellipses shown here. A top-level entry only needs one argument.

4. Schedule the next boot

This is the state-changing step, and it needs elevated privileges because the command writes GRUB's environment block:

$ sudo grub-reboot 'EXACT MENU ENTRY OR ID'
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means the write succeeded. It does not boot the machine immediately, and it is not proof the selected system will actually start. Reboot only when you are ready:

$ sudo systemctl reboot

Checkpoint

Confirm you have console or out-of-band access before rebooting a server, and do not run the reboot until you have double-checked the entry you scheduled.

5. Confirm what happens afterwards

Once the machine is up, check what actually booted with the relevant local command. For Linux:

$ uname -r
6.8.0-xx-generic

Then check the normal GRUB selection on the following reboot, rather than assuming the one-time choice became permanent. grub-reboot only ever affects the next boot; grub-set-default is the separate command for a persistent default, and the two are not interchangeable.

6. Diagnose an entry that stays selected

Warning

The installed manual warns that GRUB can be unable to write its environment block when it lives on an MDRAID or LVM device. When that happens, the selected entry can remain the default even after reboot, so a command that reports success is not enough evidence one-time behaviour actually works.

If the same entry keeps booting, check the storage layout and environment-block location without editing any boot files yet:

$ findmnt -no SOURCE,FSTYPE,TARGET /boot /boot/grub 2>/dev/null
$ sudo grub-editenv /boot/grub/grubenv list

The second command reads GRUB's environment block directly. If it reports the file missing, unreadable, or unsuitable for writing, stop and investigate your distribution's GRUB layout rather than creating a replacement environment file or touching mount and RAID settings as a quick fix on a production system: those changes affect boot reliability and deserve their own recovery plan.

If you picked the wrong entry but have not rebooted yet, just run grub-reboot again with the right one. To clear a pending choice on a writable environment block, use your distribution's supported tooling after checking its documentation, and never hand-edit /boot/grub/grubenv as plain text.

Done means

  • Command confirmed: grub-reboot --version identifies the installed GRUB release, and the command is available.
  • Entry path exact: the top-level or submenu path was copied straight from this machine's GRUB configuration.
  • Submenu syntax correct: the path uses > with no spaces and is quoted against shell redirection.
  • Write confirmed: the command returned status 0 before any reboot was started.
  • Recovery understood: you know environment-block storage can defeat one-time behaviour, and you have recovery access before rebooting.