grubby/boot/grub/persistent/docs/06_your_own_configuration_file

6 Writing your own configuration file
*************************************

GRUB is configured using 'grub.cfg', usually located under '/boot/grub'.
This file is quite flexible, but most users will not need to write the
whole thing by hand.

6.1 Simple configuration handling
=================================

The program 'grub-mkconfig' (*note 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 (*note
Booting::, and *note Shell-like scripting::), 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 (*note Environment block::).

     The default is '0'.

'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 (*note Environment block::).

'GRUB_TIMEOUT'
     Boot the default entry this many seconds after the menu is
     displayed, unless a key is pressed.  The default is '5'.  Set to
     '0' 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 'menu', 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> is pressed 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.  *Note
     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_<port>' (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_<port>' (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.  *Note 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_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_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_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.  *Note 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.

'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', 'WIDTHxHEIGHT'['xDEPTH'] to set a particular
     graphics mode, or a sequence of these separated by commas or
     semicolons to try several modes in sequence.  *Note 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'
     Normally, 'grub-mkconfig' will try to use the external 'os-prober'
     program, if installed, to discover other operating systems
     installed on the same system and generate appropriate menu entries
     for them.  Set this option to 'true' to disable this.

'GRUB_OS_PROBER_SKIP_LIST'
     List of space-separated FS UUIDs of filesystems to be ignored from
     os-prober output.  For efi chainloaders it's <UUID>@<EFI FILE>

'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 'y',
     flat menu with all entries on top level will be generated instead.
     Changing this option will require changing existing values of
     'GRUB_DEFAULT', 'fallback' (*note fallback::) and 'default' (*note
     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 'y', '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 *note play::.

'GRUB_BADRAM'
     If this option is set, GRUB will issue a *note 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> is
     pressed 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> is pressed.

     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.  *Note 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'.

   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.

6.2 Root Identifcation Heuristics
=================================

If the target operating system uses the Linux kernel, 'grub-mkconfig'
attempts to identify the root file system via a heuristic algoirthm.
This algorithm selects the identification method of the root file system
by considering three factors.  The first is if an initrd for the target
operating system is also present.  The second is
'GRUB_DISABLE_LINUX_UUID' and if set to 'true', prevents 'grub-mkconfig'
from identifying the root file system by its UUID. The third is
'GRUB_DISABLE_LINUX_PARTUUID' and if set to 'true', prevents
'grub-mkconfig' from identifying the root file system via the UUID of
its enclosing partition.  If the variables are assigned any other value,
that value is considered equivalent to 'false'.  The variables are also
considered to be set to 'false' if they are not set.

   When booting, the Linux kernel will delegate the task of mounting the
root filesystem to the initrd.  Most initrd images determine the root
file system by checking the Linux kernel's command-line for the 'root'
key and use its value as the identification method of the root file
system.  To improve the reliability of booting, most initrd images also
allow the root file system to be identified by its UUID. Because of this
behavior, the 'grub-mkconfig' command will set 'root' to 'root=UUID=...'
to provide the initrd with the filesystem UUID of the root file system.

   If no initrd is detected or 'GRUB_DISABLE_LINUX_UUID' is set to
'true' then 'grub-command' will identify the root filesystem by setting
the kernel command-line variable 'root' to 'root=PARTUUID=...' unless
'GRUB_DISABLE_LINUX_PARTUUID' is also set to 'true'.  If
'GRUB_DISABLE_LINUX_PARTUUID' is also set to 'true', 'grub-command' will
identify by its Linux device name.

   The following table summarizes the behavior of the 'grub-mkconfig'
command.

Initrd     GRUB_DISABLE_LINUX_PARTUUID   GRUB_DISABLE_LINUX_UUID   Linux Root
detected   Set To                        Set To                    ID Method
--------------------------------------------------------------------------------
false      false                         false                     part UUID
false      false                         true                      part UUID
false      true                          false                     dev name
false      true                          true                      dev name
true       false                         false                     fs UUID
true       false                         true                      part UUID
true       true                          false                     fs UUID
true       true                          true                      dev name

   Remember, 'GRUB_DISABLE_LINUX_PARTUUID' and 'GRUB_DISABLE_LINUX_UUID'
are also considered to be set to 'false' when they are unset.

6.3 Writing full configuration files directly
=============================================

'grub.cfg' is written in GRUB's built-in scripting language, which has a
syntax quite similar to that of GNU Bash and other Bourne shell
derivatives.

Words
=====

A "word" is a sequence of characters considered as a single unit by
GRUB. Words are separated by "metacharacters", which are the following
plus space, tab, and newline:

     { } | & $ ; < >

   Quoting may be used to include metacharacters in words; see below.

Reserved words
==============

Reserved words have a special meaning to GRUB. The following words are
recognised as reserved when unquoted and either the first word of a
simple command or the third word of a 'for' command:

     ! [[ ]] { }
     case do done elif else esac fi for function
     if in menuentry select then time until while

   Not all of these reserved words have a useful purpose yet; some are
reserved for future expansion.

Quoting
=======

Quoting is used to remove the special meaning of certain characters or
words.  It can be used to treat metacharacters as part of a word, to
prevent reserved words from being recognised as such, and to prevent
variable expansion.

   There are three quoting mechanisms: the escape character, single
quotes, and double quotes.

   A non-quoted backslash (\) is the "escape character".  It preserves
the literal value of the next character that follows, with the exception
of newline.

   Enclosing characters in single quotes preserves the literal value of
each character within the quotes.  A single quote may not occur between
single quotes, even when preceded by a backslash.

   Enclosing characters in double quotes preserves the literal value of
all characters within the quotes, with the exception of '$' and '\'.
The '$' character retains its special meaning within double quotes.  The
backslash retains its special meaning only when followed by one of the
following characters: '$', '"', '\', or newline.  A backslash-newline
pair is treated as a line continuation (that is, it is removed from the
input stream and effectively ignored(1) (*note Shell-like
scripting-Footnote-1::)).  A double quote may be quoted within double
quotes by preceding it with a backslash.

Variable expansion
==================

The '$' character introduces variable expansion.  The variable name to
be expanded may be enclosed in braces, which are optional but serve to
protect the variable to be expanded from characters immediately
following it which could be interpreted as part of the name.

   Normal variable names begin with an alphabetic character, followed by
zero or more alphanumeric characters.  These names refer to entries in
the GRUB environment (*note Environment::).

   Positional variable names consist of one or more digits.  They
represent parameters passed to function calls, with '$1' representing
the first parameter, and so on.

   The special variable name '?' expands to the exit status of the most
recently executed command.  When positional variable names are active,
other special variable names '@', '*' and '#' are defined and they
expand to all positional parameters with necessary quoting, positional
parameters without any quoting, and positional parameter count
respectively.

Comments
========

A word beginning with '#' causes that word and all remaining characters
on that line to be ignored.

Simple commands
===============

A "simple command" is a sequence of words separated by spaces or tabs
and terminated by a semicolon or a newline.  The first word specifies
the command to be executed.  The remaining words are passed as arguments
to the invoked command.

   The return value of a simple command is its exit status.  If the
reserved word '!' precedes the command, then the return value is instead
the logical negation of the command's exit status.

Compound commands
=================

A "compound command" is one of the following:

for NAME in WORD ...; do LIST; done
     The list of words following 'in' is expanded, generating a list of
     items.  The variable NAME is set to each element of this list in
     turn, and LIST is executed each time.  The return value is the exit
     status of the last command that executes.  If the expansion of the
     items following 'in' results in an empty list, no commands are
     executed, and the return status is 0.

if LIST; then LIST; [elif LIST; then LIST;] ... [else LIST;] fi
     The 'if' LIST is executed.  If its exit status is zero, the 'then'
     LIST is executed.  Otherwise, each 'elif' LIST is executed in turn,
     and if its exit status is zero, the corresponding 'then' LIST is
     executed and the command completes.  Otherwise, the 'else' LIST is
     executed, if present.  The exit status is the exit status of the
     last command executed, or zero if no condition tested true.

while COND; do LIST; done
until COND; do LIST; done
     The 'while' command continuously executes the 'do' LIST as long as
     the last command in COND returns an exit status of zero.  The
     'until' command is identical to the 'while' command, except that
     the test is negated; the 'do' LIST is executed as long as the last
     command in COND returns a non-zero exit status.  The exit status of
     the 'while' and 'until' commands is the exit status of the last
     'do' LIST command executed, or zero if none was executed.

function NAME { COMMAND; ... }
     This defines a function named NAME.  The "body" of the function is
     the list of commands within braces, each of which must be
     terminated with a semicolon or a newline.  This list of commands
     will be executed whenever NAME is specified as the name of a simple
     command.  Function definitions do not affect the exit status in
     '$?'.  When executed, the exit status of a function is the exit
     status of the last command executed in the body.

menuentry TITLE ['--class=class' ...] ['--users=users'] ['--unrestricted'] ['--hotkey=key'] ['--id=id'] { COMMAND; ... }
     *Note menuentry::.

Built-in Commands
=================

Some built-in commands are also provided by GRUB script to help script
writers perform actions that are otherwise not possible.  For example,
these include commands to jump out of a loop without fully completing
it, etc.

break ['n']
     Exit from within a 'for', 'while', or 'until' loop.  If 'n' is
     specified, break 'n' levels.  'n' must be greater than or equal to
     1.  If 'n' is greater than the number of enclosing loops, all
     enclosing loops are exited.  The return value is 0 unless 'n' is
     not greater than or equal to 1.

continue ['n']
     Resume the next iteration of the enclosing 'for', 'while' or
     'until' loop.  If 'n' is specified, resume at the 'n'th enclosing
     loop.  'n' must be greater than or equal to 1.  If 'n' is greater
     than the number of enclosing loops, the last enclosing loop (the
     "top-level" loop) is resumed.  The return value is 0 unless 'n' is
     not greater than or equal to 1.

return ['n']
     Causes a function to exit with the return value specified by 'n'.
     If 'n' is omitted, the return status is that of the last command
     executed in the function body.  If used outside a function the
     return status is false.

setparams ['arg'] ...
     Replace positional parameters starting with '$1' with arguments to
     'setparams'.

shift ['n']
     The positional parameters from 'n'+1 ... are renamed to '$1'....
     Parameters represented by the numbers '$#' down to '$#'-'n'+1 are
     unset.  'n' must be a non-negative number less than or equal to
     '$#'.  If 'n' is 0, no parameters are changed.  If 'n' is not
     given, it is assumed to be 1.  If 'n' is greater than '$#', the
     positional parameters are not changed.  The return status is
     greater than zero if 'n' is greater than '$#' or less than zero;
     otherwise 0.

   (1) Currently a backslash-newline pair within a variable name is not
handled properly, so use this feature with some care.

6.4 Multi-boot manual config
============================

Currently autogenerating config files for multi-boot environments
depends on os-prober and has several shortcomings.  While fixing it is
scheduled for the next release, meanwhile you can make use of the power
of GRUB syntax and do it yourself.  A possible configuration is detailed
here, feel free to adjust to your needs.

   First create a separate GRUB partition, big enough to hold GRUB. Some
of the following entries show how to load OS installer images from this
same partition, for that you obviously need to make the partition large
enough to hold those images as well.  Mount this partition on/mnt/boot
and disable GRUB in all OSes and manually install self-compiled latest
GRUB with:

   'grub-install --boot-directory=/mnt/boot /dev/sda'

   In all the OSes install GRUB tools but disable installing GRUB in
bootsector, so you'll have menu.lst and grub.cfg available for use.
Also disable os-prober use by setting:

   'GRUB_DISABLE_OS_PROBER=true'

   in /etc/default/grub

   Then write a grub.cfg (/mnt/boot/grub/grub.cfg):


     menuentry "OS using grub2" {
        insmod xfs
        search --set=root --label OS1 --hint hd0,msdos8
        configfile /boot/grub/grub.cfg
     }

     menuentry "OS using grub2-legacy" {
        insmod ext2
        search --set=root --label OS2 --hint hd0,msdos6
        legacy_configfile /boot/grub/menu.lst
     }

     menuentry "Windows XP" {
        insmod ntfs
        search --set=root --label WINDOWS_XP --hint hd0,msdos1
        ntldr /ntldr
     }

     menuentry "Windows 7" {
        insmod ntfs
        search --set=root --label WINDOWS_7 --hint hd0,msdos2
        ntldr /bootmgr
     }

     menuentry "FreeBSD" {
               insmod zfs
               search --set=root --label freepool --hint hd0,msdos7
               kfreebsd /freebsd@/boot/kernel/kernel
               kfreebsd_module_elf /freebsd@/boot/kernel/opensolaris.ko
               kfreebsd_module_elf /freebsd@/boot/kernel/zfs.ko
               kfreebsd_module /freebsd@/boot/zfs/zpool.cache type=/boot/zfs/zpool.cache
               set kFreeBSD.vfs.root.mountfrom=zfs:freepool/freebsd
               set kFreeBSD.hw.psm.synaptics_support=1
     }

     menuentry "experimental GRUB" {
               search --set=root --label GRUB --hint hd0,msdos5
               multiboot /experimental/grub/i386-pc/core.img
     }

     menuentry "Fedora 16 installer" {
               search --set=root --label GRUB --hint hd0,msdos5
               linux /fedora/vmlinuz lang=en_US keymap=sg resolution=1280x800
               initrd /fedora/initrd.img
     }

     menuentry "Fedora rawhide installer" {
               search --set=root --label GRUB --hint hd0,msdos5
               linux /fedora/vmlinuz repo=ftp://mirror.switch.ch/mirror/fedora/linux/development/rawhide/x86_64 lang=en_US keymap=sg resolution=1280x800
               initrd /fedora/initrd.img
     }

     menuentry "Debian sid installer" {
               search --set=root --label GRUB --hint hd0,msdos5
               linux /debian/dists/sid/main/installer-amd64/current/images/hd-media/vmlinuz
               initrd /debian/dists/sid/main/installer-amd64/current/images/hd-media/initrd.gz
     }


   Notes:
   * Argument to search after -label is FS LABEL. You can also use UUIDs
     with -fs-uuid UUID instead of -label LABEL. You could also use
     direct 'root=hd0,msdosX' but this is not recommended due to device
     name instability.

6.5 Embedding a configuration file into GRUB
============================================

GRUB supports embedding a configuration file directly into the core
image, so that it is loaded before entering normal mode.  This is
useful, for example, when it is not straightforward to find the real
configuration file, or when you need to debug problems with loading that
file.  'grub-install' uses this feature when it is not using BIOS disk
functions or when installing to a different disk from the one containing
'/boot/grub', in which case it needs to use the 'search' command (*note
search::) to find '/boot/grub'.

   To embed a configuration file, use the '-c' option to 'grub-mkimage'.
The file is copied into the core image, so it may reside anywhere on the
file system, and may be removed after running 'grub-mkimage'.

   After the embedded configuration file (if any) is executed, GRUB will
load the 'normal' module (*note normal::), which will then read the real
configuration file from '$prefix/grub.cfg'.  By this point, the 'root'
variable will also have been set to the root device name.  For example,
'prefix' might be set to '(hd0,1)/boot/grub', and 'root' might be set to
'hd0,1'.  Thus, in most cases, the embedded configuration file only
needs to set the 'prefix' and 'root' variables, and then drop through to
GRUB's normal processing.  A typical example of this might look like
this:

     search.fs_uuid 01234567-89ab-cdef-0123-456789abcdef root
     set prefix=($root)/boot/grub

   (The 'search_fs_uuid' module must be included in the core image for
this example to work.)

   In more complex cases, it may be useful to read other configuration
files directly from the embedded configuration file.  This allows such
things as reading files not called 'grub.cfg', or reading files from a
directory other than that where GRUB's loadable modules are installed.
To do this, include the 'configfile' and 'normal' modules in the core
image, and embed a configuration file that uses the 'configfile' command
to load another file.  The following example of this also requires the
'echo', 'search_label', and 'test' modules to be included in the core
image:

     search.fs_label grub root
     if [ -e /boot/grub/example/test1.cfg ]; then
         set prefix=($root)/boot/grub
         configfile /boot/grub/example/test1.cfg
     else
         if [ -e /boot/grub/example/test2.cfg ]; then
             set prefix=($root)/boot/grub
             configfile /boot/grub/example/test2.cfg
         else
             echo "Could not find an example configuration file!"
         fi
     fi

   The embedded configuration file may not contain menu entries
directly, but may only read them from elsewhere using 'configfile'.