tablet/grub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add Btrfs env block and special env vars

Browse Source 
Update grub.texi to describe the external environment block in the
reserved area of Btrfs header used for grub-reboot and savedefault, and
add a section documenting the saved_entry, next_entry, and env_block
variables.

Signed-off-by: Michael Chang <mchang@suse.com>
Reviewed-by: Neal Gompa <ngompa13@gmail.com>
Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>
This commit is contained in:
Michael Chang 2025-10-17 17:01:42 +08:00 committed by Daniel Kiper
parent b634477481
commit 6435551a66
1 changed files with 60 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/grub.texi
View File

@ -3271,6 +3271,7 @@ GRUB. Others may be used freely in GRUB configuration files.
@menu
* Special environment variables::
* Environment block::
* Special environment block variables::
* Passing environment variables through Xen::
@end menu
@ -3904,9 +3905,68 @@ For safety reasons, this storage is only available when installed on a plain
disk (no LVM or RAID), using a non-checksumming filesystem (no ZFS), and
using BIOS or EFI functions (no ATA, USB or IEEE1275).
On Btrfs filesystems, a reserved area in the filesystem header may be used to
store the environment block. This static block avoids the problems of updating
a normal file on a copy-on-write filesystem, where writing raw block is not
stable and requires metadata update. The reserved area provides a fixed
location that GRUB can update directly, allowing commands such as
@command{grub-reboot} and @samp{GRUB_SAVEDEFAULT} to function correctly on
Btrfs volumes.
@command{grub-mkconfig} uses this facility to implement
@samp{GRUB_SAVEDEFAULT} (@pxref{Simple configuration}).
@node Special environment block variables
@section Special environment block variables
These special variables are usually written to the environment block
(@pxref{Environment block}) to customize the behavior of @file{grub.cfg}
generated by @command{grub-mkconfig}.
@menu
* saved_entry::
* next_entry::
* env_block::
@end menu
@node saved_entry
@subsection saved_entry
The @var{saved_entry} variable sets the default boot entry in @file{grub.cfg}
created by @command{grub-mkconfig}. It can be set with
@command{grub-set-default} to choose a default entry, or at runtime with the
@code{savedefault} function in grub.cfg to save the current entry as the new
default. This may require write access by GRUB.
@node next_entry
@subsection next_entry
The @var{next_entry} variable sets the boot entry for the next boot only. After
it is used, GRUB clears the value so it is not reused. This requires write
access to the environment block (@pxref{Environment block}) at runtime. The
@command{grub-reboot} command is usually used instead of changing this variable
directly.
@node env_block
@subsection env_block
If the filesystem is Btrfs and the disk is not an abstracted device such as
LVM, RAID, or encryption, the reserved space in the Btrfs header can be used as
the environment block (@pxref{Environment block}). This provides a fixed raw
block that GRUB can reliably write to. The @var{env_block} records this
location in GRUB blocklist syntax (@pxref{Block list syntax}) so that
@command{grub-editenv} and @file{grub.cfg} know how to access and use the
external raw block.
This variable is initialized when @file{grubenv} is first created by
@command{grub-editenv} and is treated as read-only to avoid being overwritten
with an unpredictable value.
@node Passing environment variables through Xen
@section Passing environment variables through Xen