Simple configuration (GNU GRUB Manual 2.14)

Simple configuration (GNU GRUB Manual 2.14)
Next:
Root Identification Heuristics
, Up:
Writing your own configuration file
Contents
][
Index
6.1 Simple configuration handling
The program
grub-mkconfig
(see
Invoking grub-mkconfig
generates
grub.cfg
files suitable for most cases. It is suitable for
use when upgrading a distribution, and will discover available kernels and
attempt to generate menu entries for them.
grub-mkconfig
does have some limitations. While adding extra
custom menu entries to the end of the list can be done by editing
/etc/grub.d/40_custom
or creating
/boot/grub/custom.cfg
changing the order of menu entries or changing their titles may require
making complex changes to shell scripts stored in
/etc/grub.d/
. This
may be improved in the future. In the meantime, those who feel that it
would be easier to write
grub.cfg
directly are encouraged to do so
(see
Booting
, and
Writing full configuration files directly
), and to disable any system
provided by their distribution to automatically run
grub-mkconfig
The file
/etc/default/grub
controls the operation of
grub-mkconfig
. It is sourced by a shell script, and so must be
valid POSIX shell input; normally, it will just be a sequence of
KEY=value
’ lines, but if the value contains spaces or other special
characters then it must be quoted. For example:
GRUB_TERMINAL_INPUT="console serial"
Valid keys in
/etc/default/grub
are as follows:
GRUB_DEFAULT
The default menu entry. This may be a number, in which case it identifies
the Nth entry in the generated menu counted from zero, or the title of a
menu entry, or the special string ‘
saved
’. Using the id may be
useful if you want to set a menu entry as the default even though there may
be a variable number of entries before it.
For example, if you have:
menuentry 'Example GNU/Linux distribution' --class gnu-linux --id example-gnu-linux {
...
then you can make this the default using:
GRUB_DEFAULT=example-gnu-linux
Previously it was documented the way to use entry title. While this still
works it’s not recommended since titles often contain unstable device names
and may be translated
If you set this to ‘
saved
’, then the default menu entry will be that
saved by ‘
GRUB_SAVEDEFAULT
’ or
grub-set-default
. This relies on
the environment block, which may not be available in all situations
(see
The GRUB environment block
).
The default is ‘
’.
GRUB_SAVEDEFAULT
If this option is set to ‘
true
’, then, when an entry is selected, save
it as a new default entry for use by future runs of GRUB. This is only
useful if ‘
GRUB_DEFAULT=saved
’; it is a separate option because
GRUB_DEFAULT=saved
’ is useful without this option, in conjunction with
grub-set-default
. Unset by default.
This option relies on the environment block, which may not be available in
all situations (see
The GRUB environment block
).
GRUB_TIMEOUT
Boot the default entry this many seconds after the menu is displayed, unless
a key is pressed. The default is ‘
’. Set to ‘
’ to boot
immediately without displaying the menu, or to ‘
-1
’ to wait
indefinitely.
If ‘
GRUB_TIMEOUT_STYLE
’ is set to ‘
countdown
’ or ‘
hidden
’,
the timeout is instead counted before the menu is displayed.
GRUB_TIMEOUT_STYLE
If this option is unset or set to ‘
’, then GRUB will display the
menu and then wait for the timeout set by ‘
GRUB_TIMEOUT
’ to expire
before booting the default entry. Pressing a key interrupts the timeout.
If this option is set to ‘
countdown
’ or ‘
hidden
’, then, before
displaying the menu, GRUB will wait for the timeout set by ‘
GRUB_TIMEOUT
to expire. If
ESC
or
F4
are pressed, or
SHIFT
is held down
during that time, it will display the menu and wait for input. If a hotkey
associated with a menu entry is pressed, it will boot the associated menu entry
immediately. If the timeout expires before either of these happens, it will
boot the default entry. In the ‘
countdown
’ case, it will show a one-line
indication of the remaining time.
GRUB_DEFAULT_BUTTON
GRUB_TIMEOUT_BUTTON
GRUB_TIMEOUT_STYLE_BUTTON
GRUB_BUTTON_CMOS_ADDRESS
Variants of the corresponding variables without the ‘
_BUTTON
’ suffix,
used to support vendor-specific power buttons. See
Using GRUB with vendor power-on keys
GRUB_DISTRIBUTOR
Set by distributors of GRUB to their identifying name. This is used to
generate more informative menu entry titles.
GRUB_TERMINAL_INPUT
Select the terminal input device. You may select multiple devices here,
separated by spaces.
Valid terminal input names depend on the platform, but may include
console
’ (native platform console), ‘
serial
’ (serial terminal),
serial_
’ (serial terminal with explicit port selection),
at_keyboard
’ (PC AT keyboard), or ‘
usb_keyboard
’ (USB keyboard
using the HID Boot Protocol, for cases where the firmware does not handle
this).
The default is to use the platform’s native terminal input.
GRUB_TERMINAL_OUTPUT
Select the terminal output device. You may select multiple devices here,
separated by spaces.
Valid terminal output names depend on the platform, but may include
console
’ (native platform console), ‘
serial
’ (serial terminal),
serial_
’ (serial terminal with explicit port selection),
gfxterm
’ (graphics-mode output), ‘
vga_text
’ (VGA text output),
mda_text
’ (MDA text output), ‘
morse
’ (Morse-coding using system
beeper) or ‘
spkmodem
’ (simple data protocol using system speaker).
spkmodem
’ is useful when no serial port is available. Connect the output
of sending system (where GRUB is running) to line-in of receiving system
(usually developer machine).
On receiving system compile ‘
spkmodem-recv
’ from
util/spkmodem-recv.c
’ and run:
parecord --channels=1 --rate=48000 --format=s16le | ./spkmodem-recv
The default is to use the platform’s native terminal output.
GRUB_TERMINAL
If this option is set, it overrides both ‘
GRUB_TERMINAL_INPUT
’ and
GRUB_TERMINAL_OUTPUT
’ to the same value.
GRUB_SERIAL_COMMAND
A command to configure the serial port when using the serial console.
See
serial
. Defaults to ‘
serial
’.
GRUB_CMDLINE_LINUX
Command-line arguments to add to menu entries for the Linux kernel.
GRUB_CMDLINE_LINUX_DEFAULT
Unless ‘
GRUB_DISABLE_RECOVERY
’ is set to ‘
true
’, two menu
entries will be generated for each Linux kernel: one default entry and one
entry for recovery mode. This option lists command-line arguments to add
only to the default menu entry, after those listed in
GRUB_CMDLINE_LINUX
’.
GRUB_CMDLINE_LINUX_RECOVERY
Unless ‘
GRUB_DISABLE_RECOVERY
’ is set to ‘
true
’, two menu
entries will be generated for each Linux kernel: one default entry and one
entry for recovery mode. This option lists command-line arguments to add
only to the recovery menu entry, before those listed in ‘
GRUB_CMDLINE_LINUX
’.
The default is ‘
single
’.
GRUB_CMDLINE_NETBSD
GRUB_CMDLINE_NETBSD_DEFAULT
As ‘
GRUB_CMDLINE_LINUX
’ and ‘
GRUB_CMDLINE_LINUX_DEFAULT
’, but for
NetBSD.
GRUB_CMDLINE_GNUMACH
As ‘
GRUB_CMDLINE_LINUX
’, but for GNU Mach.
GRUB_CMDLINE_XEN
GRUB_CMDLINE_XEN_DEFAULT
The values of these options are passed to Xen hypervisor Xen menu entries,
for all respectively normal entries.
GRUB_CMDLINE_LINUX_XEN_REPLACE
GRUB_CMDLINE_LINUX_XEN_REPLACE_DEFAULT
The values of these options replace the values of ‘
GRUB_CMDLINE_LINUX
and ‘
GRUB_CMDLINE_LINUX_DEFAULT
’ for Linux and Xen menu entries.
GRUB_TOP_LEVEL
GRUB_TOP_LEVEL_XEN
This option should be an absolute path to a kernel image. If provided, the
image specified will be made the top-level entry if it is found in the scan.
GRUB_TOP_LEVEL_OS_PROBER
This option should be a line of output from
os-prober
. As
GRUB_TOP_LEVEL
’, if provided, the image specified will be made the
top-level entry if it is found in the scan.
GRUB_EARLY_INITRD_LINUX_CUSTOM
GRUB_EARLY_INITRD_LINUX_STOCK
List of space-separated early initrd images to be loaded from ‘
/boot
’.
This is for loading things like CPU microcode, firmware, ACPI tables, crypto
keys, and so on. These early images will be loaded in the order declared,
and all will be loaded before the actual functional initrd image.
GRUB_EARLY_INITRD_LINUX_STOCK
’ is for your distribution to declare
images that are provided by the distribution. It should not be modified
without understanding the consequences. They will be loaded first.
GRUB_EARLY_INITRD_LINUX_CUSTOM
’ is for your custom created images.
The default stock images are as follows, though they may be overridden by
your distribution:
intel-uc.img intel-ucode.img amd-uc.img amd-ucode.img early_ucode.cpio microcode.cpio
GRUB_DISABLE_LINUX_UUID
Normally,
grub-mkconfig
will generate menu entries that use
universally-unique identifiers (UUIDs) to identify the root filesystem to
the Linux kernel, using a ‘
root=UUID=...
’ kernel parameter. This is
usually more reliable, but in some cases it may not be appropriate. To
disable the use of UUIDs, set this option to ‘
true
’.
GRUB_DISABLE_LINUX_PARTUUID
If
grub-mkconfig
cannot identify the root filesystem via its
universally-unique indentifier (UUID),
grub-mkconfig
can use the UUID
of the partition containing the filesystem to identify the root filesystem to
the Linux kernel via a ‘
root=PARTUUID=...
’ kernel parameter. This is not
as reliable as using the filesystem UUID, but is more reliable than using the
Linux device names. When ‘
GRUB_DISABLE_LINUX_PARTUUID
’ is set to
false
’, the Linux kernel version must be 2.6.37 (3.10 for systems using
the MSDOS partition scheme) or newer. This option defaults to ‘
true
’. To
enable the use of partition UUIDs, set this option to ‘
false
’.
GRUB_DISABLE_RECOVERY
If this option is set to ‘
true
’, disable the generation of recovery
mode menu entries.
GRUB_DISABLE_UUID
Normally,
grub-mkconfig
will generate menu entries that use
universally-unique identifiers (UUIDs) to identify various filesystems to
search for files. This is usually more reliable, but in some cases it may
not be appropriate. To disable this use of UUIDs, set this option to
true
’. Setting this option to ‘
true
’, will also set the options
GRUB_DISABLE_LINUX_UUID
’ and ‘
GRUB_DISABLE_LINUX_PARTUUID
’ to
true
’, unless they have been explicitly set to ‘
false
’.
GRUB_VIDEO_BACKEND
If graphical video support is required, either because the ‘
gfxterm
graphical terminal is in use or because ‘
GRUB_GFXPAYLOAD_LINUX
’ is set,
then
grub-mkconfig
will normally load all available GRUB video
drivers and use the one most appropriate for your hardware. If you need to
override this for some reason, then you can set this option.
After
grub-install
has been run, the available video drivers are
listed in
/boot/grub/video.lst
GRUB_GFXMODE
Set the resolution used on the ‘
gfxterm
’ graphical terminal. Note that
you can only use modes which your graphics card supports via VESA BIOS
Extensions (VBE), so for example native LCD panel resolutions may not be
available. The default is ‘
auto
’, which tries to select a preferred
resolution. See
gfxmode
GRUB_BACKGROUND
Set a background image for use with the ‘
gfxterm
’ graphical terminal.
The value of this option must be a file readable by GRUB at boot time, and
it must end with
.png
.tga
.jpg
, or
.jpeg
The image will be scaled if necessary to fit the screen. Image height and
width will be restricted by an artificial limit of 16384.
GRUB_THEME
Set a theme for use with the ‘
gfxterm
’ graphical terminal.
GRUB_GFXPAYLOAD_LINUX
Set to ‘
text
’ to force the Linux kernel to boot in normal text mode,
keep
’ to preserve the graphics mode set using ‘
GRUB_GFXMODE
’,
width
height
’[‘
depth
’] to set a particular
graphics mode, or a sequence of these separated by commas or semicolons to
try several modes in sequence. See
gfxpayload
Depending on your kernel, your distribution, your graphics card, and the
phase of the moon, note that using this option may cause GNU/Linux to suffer
from various display problems, particularly during the early part of the
boot sequence. If you have problems, set this option to ‘
text
’ and
GRUB will tell Linux to boot in normal text mode.
GRUB_DISABLE_OS_PROBER
The
grub-mkconfig
has a feature to use the external
os-prober
program to discover other operating systems installed on
the same machine and generate appropriate menu entries for them. It is disabled
by default since automatic and silent execution of
os-prober
, and
creating boot entries based on that data, is a potential attack vector. Set
this option to ‘
false
’ to enable this feature in the
grub-mkconfig
command.
GRUB_OS_PROBER_SKIP_LIST
List of space-separated case insensitive UUIDs of filesystems to be ignored
from os-prober output. For EFI chainloaders it’s @. For
backward compatibility with previous behaviour, @/dev/* is also accepted
for non-EFI chainloaders even if the device does not match, and comma and
semicolon are also accepted as separator.
GRUB_DISABLE_SUBMENU
Normally,
grub-mkconfig
will generate top level menu entry for
the kernel with highest version number and put all other found kernels
or alternative menu entries for recovery mode in submenu. For entries returned
by
os-prober
first entry will be put on top level and all others
in submenu. If this option is set to ‘
true
’, flat menu with all entries
on top level will be generated instead. Changing this option will require
changing existing values of ‘
GRUB_DEFAULT
’, ‘
fallback
’ (see
fallback
and ‘
default
’ (see
default
) environment variables as well as saved
default entry using
grub-set-default
and value used with
grub-reboot
GRUB_ENABLE_CRYPTODISK
If set to ‘
’,
grub-mkconfig
and
grub-install
will
check for encrypted disks and generate additional commands needed to access
them during boot. Note that in this case unattended boot is not possible
because GRUB will wait for passphrase to unlock encrypted container.
GRUB_INIT_TUNE
Play a tune on the speaker when GRUB starts. This is particularly useful
for users unable to see the screen. The value of this option is passed
directly to
play
GRUB_BADRAM
If this option is set, GRUB will issue a
badram
command to filter
out specified regions of RAM.
GRUB_PRELOAD_MODULES
This option may be set to a list of GRUB module names separated by spaces.
Each module will be loaded as early as possible, at the start of
grub.cfg
The following options are still accepted for compatibility with existing
configurations, but have better replacements:
GRUB_HIDDEN_TIMEOUT
Wait this many seconds before displaying the menu. If
ESC
or
F4
are
pressed, or
SHIFT
is held down during that time, display the menu and wait
for input according to ‘
GRUB_TIMEOUT
’. If a hotkey associated with a menu
entry is pressed, boot the associated menu entry immediately. If the timeout
expires before either of these happens, display the menu for the number of
seconds specified in ‘
GRUB_TIMEOUT
’ before booting the default entry.
If you set ‘
GRUB_HIDDEN_TIMEOUT
’, you should also set
GRUB_TIMEOUT=0
’ so that the menu is not displayed at all unless
ESC
or
F4
are pressed, or
SHIFT
is held down.
This option is unset by default, and is deprecated in favour of the less
confusing ‘
GRUB_TIMEOUT_STYLE=countdown
’ or
GRUB_TIMEOUT_STYLE=hidden
’.
GRUB_HIDDEN_TIMEOUT_QUIET
In conjunction with ‘
GRUB_HIDDEN_TIMEOUT
’, set this to ‘
true
’ to
suppress the verbose countdown while waiting for a key to be pressed before
displaying the menu.
This option is unset by default, and is deprecated in favour of the less
confusing ‘
GRUB_TIMEOUT_STYLE=countdown
’.
GRUB_HIDDEN_TIMEOUT_BUTTON
Variant of ‘
GRUB_HIDDEN_TIMEOUT
’, used to support vendor-specific power
buttons. See
Using GRUB with vendor power-on keys
This option is unset by default, and is deprecated in favour of the less
confusing ‘
GRUB_TIMEOUT_STYLE=countdown
’ or
GRUB_TIMEOUT_STYLE=hidden
’.
GRUB_FORCE_EFI_ALL_VIDEO
When set to true, this will allow grub-mkconfig to generate a GRUB config
that supports loading the all_video module on the EFI platform instead of
just the efi_gop and efi_uga modules.
This option is unset by default.
For more detailed customisation of
grub-mkconfig
’s output, you may
edit the scripts in
/etc/grub.d
directly.
/etc/grub.d/40_custom
is particularly useful for adding entire custom
menu entries; simply type the menu entries you want to add at the end of
that file, making sure to leave at least the first two lines intact.
Next:
Root Identification Heuristics
, Up:
Writing your own configuration file
Contents
][
Index