• FranklinPiat
• grub.cfg.manpage

#language en

• TODO:

• Verify root variable usage.

• Say more about rescue mode !
• memdisk

---

grub.cfg(5) - grub v2 boot-time configuration file.

NAME

• grub v2 boot-time configuration file.

DESCRIPTION

grub.cfg isn't really a configuration file, it's actually a bash-like script file executed by grub2 bootloader. The various instructions are either built-in, or implemented as external modules, which has to be loaded before use.

The menu structure is actually declared by the command menuentry. A menu entry is a kind of function, which is invoked when the user select it.

On most distributions, the file /boot/grub/grub.cfg is built and updated by update-grub, based on the content of /etc/defaults/grub  and /etc/grub.d/*. Read (8)update-grub for more information.

You should not modify grub.cfg directly.

FORMAT

• Any line starting with a "#" sign is considered as a comment.
• Blank lines are ignored.
• Every other line is expected to be a command.

• Command arguments are usually available in two form : a short form, with single dash like -h, and a long form with two dash like --version.

• A -- signals the end of options and disables further option processing. Any arguments after the -- are treated as arguments, not as an option.

PATHNAMES

In the grub environment, a file path is written as (hd0,1)/path/to/filename.

A typical disk drive specified with (hd0,1) is "the first partition of the first hard-disk", as seen by the computer's firmware (This is similar, but not always identical, to /dev/hda1, /dev/sda1, "C:" or PC-BIOS' drive "80"). note: The partition numbering scheme starts at 1 (like linux' hda1) where grub-v1 used to start counting partition at 0.

The path /path/to/filename is just the regular pathname, according to the partition's filesystem.

note: The appropriate diskaccess, partitioning and filesystem module must be loaded in order to be able to access such file. (typically, biosdisk+pc+ext2 on a legacy PC. read appropriate section below.)

If the disk (drive,partition) is not specified then the path is prefixed with the content of the variable root.

Some well known disk names :

• (fd0), First floppy-disk drive.

• (fd1), Second floppy-disk drive

• (hd0), First Hard-disk drive (seen by the computer firmware).

• (hd0,1), First partition of the First Hard-disk drive.

• (memdisk), Grub's [memdisk] (virtual disk, included in core.img).

• (host), Grub-emu's [hostfs] disk.

• (ata0), When using the optional [ata] module, this is the first IDE/ATA peripheral (HD or CD).

• [loopback] device can have any arbitrary name.

COMMANDS

reminder : Most commands are only available when the corresponding module is loaded (except built-ins commands).

Convention : In this document, when a command is implemented by a loadable module, the module name is written like [mymodule].

BUILT-COMMANDS

Handling modules

insmod [modulename|filename] 

• Insert a module. The argument can be either a file or a module name. The required disk, partition and filesystem modules required to read the modules on disk should be already loaded (or preloaded in core.img) in order to be able to load extra modules from disk.

  If a module is specified by it's name, the matching filename is searched in the folder pointed by the variable prefix (like (hd0,1)/boot/grub/).

lsmod

• List loaded modules.

rmmod [modulename] 

• Remove (unload) a module.

read the (7)grub_modules page.

Menu Entries

menuentry "Sample Menu-entry title" { COMMAND-LINES }  A menu entry is a kind of subroutine, declared with the command menuentry. The list of commands to be executed when the user press "enter" on the selected menu-entry are listed between curly brackets. check the #sample section at the bottom of the page.

To navigate the menu, depending on th system, you may have to use: Left-arrow, Right-arrow, Down-arrow, Up-arrow, or <, >, v and ^ (For non-US, ^ is obtained by pressing Shift+6), or Ctrl-b, Ctrl-f, Ctrl-n, Ctrl-p.

Environment variables

Grub bootloader has some environment variables, that can be use with $. (like echo $root). note that variable names are case sensitives.

set

• List environment variables.

set var=value

• Set an environment variable.

unset

• Remove (unset) an environment variable.

export var

• Export a variable.

read VAR

• Set the variable VAR with user input.

Remarkable variables : root variable

• usually contains grub's root partition (like hd0,1). This variable is prepended to pathname when disk is omitted.

Rescue mode

rescue

• Go to the rescue mode.

OS Loaders commands

linux FILE [ARGS...]

• Load a linux kernel. [_linux]

initrd FILE

• Load an initrd. [linux]

multiboot FILE [ARGS...]

• Load a Multiboot kernel. [_multiboot]

module FILE [ARGS...]

• Load a Multiboot module. [_multiboot]

chainloader [-f|--force] FILE

• Prepare to boot another boot loader. [chain]

  -f, --force : force chainloading, ignoring invalid partition signature (!= 0xaa55).

boot

• Actually boot the specified operating system (You should specify it after the kernel and module is specified). this command is implicit at the end of menu entries.. [boot]

freebsd FILE [OPTS] [ARGS...]

• Load a freebsd kernel. [_bsd]

freebsd_loadenv FILE

• Load freebsd env. [_bsd]

freebsd_module [FILE [type=module_type] [ARGS...]]

• Load freebsd module. [_bsd]

netbsd FILE [OPTS] [ARGS...]

• Load a netbsd kernel. [_bsd]

openbsd FILE [OPTS] [ARGS...]

• Load a openbsd kernel. [_bsd]

Scripting commands

if [expression] then [command] else [command] fi

• sample if [ A=B ] ; then echo "foo" ; else echo "bar" ; fi  (don't put space anywhere between "A=B"... doesn't seems to work with variables, currently; )

[ string=string ]

test string=string

• Evaluate an expression. Currently, only expression of the form A=B is supported. [test]

  TODO describe how the result is returned.

while

• (TODO: not tested)

function

• (TODO: not tested)

configfile FILE

• Load another config file. [configfile]

source FILE

. FILE

• Load another config file without changing context. [configfile]

search [-f|-l] [[-s|--set]] NAME

• Search devices by a file or a filesystem label.
  If --set is specified, the first device found is set to a variable. If no variable name is specified, "root" is used. [search]

search [-f|--file] NAME

• search devices by a file.

search [-l|--label]] NAME

• search devices by a filesystem label.

echo [-e] [-n] FILE

• Print the arguments on the standard output, separated by spaces. [echo]

  -n

  • do not output the trailing newline.

  -e

  • Enable interpretation of backslash escapes :

    \a TODO what is this supposed to to?

    \c Subsequent output is suppressed. This is normally used at the end of the last argument to suppress the trailing newline that echo would otherwise output. TODO needs to be tested.

    \f Output a form feed.

    \n Output a newline character.

    \r Output a carriage return.

    \t Output a (horizontal) tab character.

    \v Output a vertical tab.

    \0 TODO describe what this is supposed to do.

    \\ Output a backslash. All other backslash sequences elicit undefined behaviour.

sleep [-v] [-i] NUMBER_OF_SECONDS

• Wait for a specified number of seconds. [sleep]

  -v, --verbose

  • Verbose Countdown (display remaining seconds during count down).

  -i, --interruptible

  • Countdown is interruptible by pressing escape key.

cmp FILE1 FILE2

• Compare two files. [cmp]

[ EXPRESSION ]

• Evaluate an expression. [test]

test EXPRESSION

• Evaluate an expression. [test]

Tools

help [PATTERN ...]

• Show a help message. [help]

ls [-l|-h|-a] [FILE] List devices and files. [ls]

• -l

  --long

  • show a long list with more detailed information.

  -h

  --human-readable

  • print sizes in a human readable format.

  -a

  --all

  • list all files.

hello

• Say hello [hello]

hexdump [ -s offset ] [-n length] { FILE | (mem) } 

• Dump the contents of a file or memory. [hexdump]

  -s offset

  --skip offset

  • skip offset bytes from the beginning of file.

  -n length

  --length length

  • read only length bytes.

cat FILE

• Show the contents of a file. [cat]

cpuid

• Check for CPU features. running cpuid -h will list the available CPUID test. A sample use is available in the sample below. [cpuid @i386] Currently the only available test is

  -l

  long-mode

  • check for long mode flag.

lspci

• List all PCI devices. [lspci] The output looks like "00:00.0 8086:27a0.0 Device Class".

halt [-n]

• Halt the system, if possible using APM. [halt] ( [@ieee1275] : This command does not work on all firmware)

• -n

  --no-apm

  • Do not use APM to halt the computer. [@i386]

reboot

• Reboot the computer. [reboot @i386,@ieee1275]

suspend

• Return to Open Firmware prompt [suspend @ieee1275]

blocklist FILE

• Print a block list. [blocklist]

loopback [-d|-p] DEVICENAME FILE

• Make a device of a file. [loopback] TODO describe further.

  -d  DEVICENAME FILE

  --delete  DEVICENAME FILE

  • Delete the loopback device entry.

  -p DEVICENAME FILE

  --partitions DEVICENAME FILE

  • Set that the drive has partitions to simulate a harddrive.

play FILE

• Play a tune. [play @i386]

Terminal

terminal [TERM...]

• Select a terminal. [terminal]

  TERM can be one of the following (if appropriate module is supported and loaded) :

  • console : The default terminal (ascii text only) [@i386, @efi].

    ofconsole : The default terminal (ascii text only) [@ieee1275].

    gfxterm : A graphic terminal, which can display nice backgroups bitmaps ! It requires a vesa compatible card. [gfxterm @i386:pc] You should make sure you have loaded a proper font, before switching to gfxterm.

    vga : A graphic mode terminal, that doesn't support bitmap but it does support unicode font and it's compatible with very-old PCs. [vga @i386:pc]

    serial :

  Invoke terminal without arguments to list current and available terminal (based on currently loaded module).

serial [OPTIONS...]

• Configure serial port [serial @i386] The default configuration is port0, 9600bps 8N1

  -u, --unit [0|1|2|3] Set the serial unit number (default=)

  -p, --port [0x3f8|0x2f8|0x400|..] Set the serial port address (default: 0x3f8 on i386:pc ; 0x400 on other platforms)

  -s, --speed [2400|4800|9600|19200|38400|57600|115200] Set the serial port speed. The DTE-DTE speed. (default=9600)

  -w, --word [5|6|7|8] Set the serial port word length, in bits (default=8)

  -r, --parity [no|odd|even] Set the serial port parity (default=no)

  -t, --stop [1|2] Set the serial port stop bits (default=1)

  To navigate the menu, use must use the keys <, >, v and ^ instead of the arrows (For non-US, ^ is obtained by pressing Shift+6).

font FILE...

• Specify one or more font files to display. [manager]

background_image FILE

• Load background image for active terminal, in one of the following format : [gfxterm]
• [tga] : 24 or 32 bits, RLE or uncompressed.
• [jpeg] : (probably only supports DCT-Integer-8bit, 1x1)
• [png] : 8-bit depth RGB or RGBA (i.e 3*8=24 bits of 4*8=32bits), Uncompressed or "Deflated", Unfiltered, Non-interlaced.

terminfo [TERM]

• Set terminfo type. [terminfo]

videotest

• Test video subsystem. [videotest]

  To set the screen resolution, you should set the variable $vbe_mode before loading vbe and/or gfxmterm (default mode is 0x101 i.e. 640x480 8bpp)

vbeinfo

• List compatible VESA BIOS extension video modes. [vbeinfo @i386]

  KNOWN BUG: The video mode reported is the content of the variable $vbe_mode, not the actual resolution.

vbetest

• Test VESA BIOS Extension 2.0+ support. [vbetest @i386]

  The mode to test is specified in variable $vbe_mode, which defaults to 0x101 (640x480 8bpp)

• jpeg file format restriction : unknown (8-bit precision only ?).

Menu colors can be set with the following variables :

set menu_color_normal FG/BG

• Menu's text and frames foreground and background.

set menu_color_highlight FG/BG

• Menu's selection foreground and background.

where FB and BG can be one of :

• black	blue	green	cyan	red	magenta	brown	light-gray
  dark-gray	light-blue	light-green	light-cyan	light-red	light-magenta	yellow	white

If your terminal has graphic capabilities, you can load a background image.

• font (fd0)/boot/grub/$font.pff
  set gfxmode=640x480
  insmod terminal
  insmod gfxterm
  insmod vbe
  set menu_color_normal=white/black
  set menu_color_highlight=white/grey
  terminal gfxterm
  insmod tga
  background_image (fd0)/boot/grub/bg.tga
  

Supported platforms/firmware

• i386-pc
• i386-efi
• i386-linuxbios
• i386-ieee1275
• sparc64-ieee1275
• powerpc-ieee1275

SAMPLE

• # Timeout for menu
  set timeout=10
  
  # Set default boot entry as Entry 0
  set default=0
  
  # Entry 0 - Load Linux kernel.
  menuentry "My Linux Kernel on (hd0,1)" {
      set root=(hd0,1)
      linux   /boot/vmlinuz-2.6.23-1-686 root=/dev/sda1 ro 
      initrd  /boot/initrd.img-2.6.23-1-686
  }
  
  # Entry 1 - Load Debian Installer.
  menuentry "Debian Installer" {
      insmod cpuid
      set root=(hd0,2)
      if cpuid -l ; then
          linux  /debian/etch/debian-installer/amd64/linux vga=normal
          initrd /debian/etch/debian-installer/amd64/initrd.gz
      else
          linux  /debian/etch/debian-installer/i386/linux vga=normal
          initrd /debian/etch/debian-installer/i386/initrd.gz
      fi
  }
  
  # Entry 1 - Chainload another bootloader.
  menuentry "Chainload my OS" {
      set root=(hd0,3)
      chainloader +1
  }
  
  
  

AUTHOR

Program Written by Yoshinori K. Okuji, Robert Millan, Marco Gerards and others (see AUTHORS file).

Manpage Written by Franklin Piat.

BUGS

Report bugs to <bug-grub@gnu.org>.

COPYRIGHT

Copyright © 2008 Free Software Foundation, Inc.

This is free software. You may redistribute copies of it under the terms of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

SEE ALSO

• (5)grub.cfg

• (8)grub-install

• (8)grub-mkdevicemap, (5)grub_device.map.

• (8)grub-mkimage

• (8)grub-mkrescue

• (8)grub-probe

• (8)grub-setup

• (8)grub-set-default

• (8)update-grub, (8)update-grub2

---