grub-editenv
Modify GRUB environment variables
TLDR
Set a default boot entry (Assuming the boot entry already exists)
Display all GRUB environment variables
Reset the saved_entry variable to the default
SYNOPSIS
grub-editenv [OPTION...] [FILE] create|list|set|unset ENVNAME [VALUE]
PARAMETERS
--help
display this message and exit
--usage
give a short usage message
--version
print version information
FILE
environment file to edit (default: /boot/grub/grubenv)
create
initialize new empty environment file
list
print all variables and values
set ENVNAME [VALUE]
set ENVNAME to VALUE (defaults to empty string)
unset ENVNAME
delete variable ENVNAME
DESCRIPTION
grub-editenv is a utility in the GRUB 2 bootloader suite for manipulating persistent environment variables stored in a simple text file, typically /boot/grub/grubenv. These variables enable GRUB scripts to retain state across reboots, such as boot counters, recovery flags, or saved menu entries used by features like recordfail or savedefault. The file format consists of 1024-byte blocks with a 32-byte checksum header followed by nul-terminated key-value pairs (keys <32 chars, values <1024 chars).
Users invoke it to create an initial empty environment file, list all variables, set a variable to a string value (empty by default), or unset one. This is crucial for custom boot behaviors, like incrementing a reboot counter or toggling a rescue menu. GRUB reads the file early in the boot process, applying variables before loading the menu.
It's lightweight, requiring no special privileges beyond write access to the file, but demands care to avoid checksum mismatches that could halt booting. Ideal for sysadmins scripting boot persistence without recompiling GRUB configs.
CAVEATS
Incorrect edits can corrupt checksums, preventing GRUB from booting. Always backup /boot/grub/grubenv first. Changes apply only after reboot; no live sync needed.
EXAMPLES
grub-editenv create — initialize default file
grub-editenv set bootcount 5 — set counter
grub-editenv list — show contents
grub-editenv unset bootcount — remove variable
FILE FORMAT
32-byte header (magic/checksum) + nul-terminated pairs in 1024-byte block; auto-resized as needed.
HISTORY
Introduced in GRUB 2.02 (2012) with improved environment block format; evolved from early GRUB 2.00 (2009) ad-hoc persistence via scripts.
SEE ALSO
grub-mkconfig(8), grub-default(8), grub-reboot(8), grub-set-default(8)
