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.

7 Theme file format

7.1 Introduction

The GRUB graphical menu supports themes that can customize the layout and appearance of the GRUB boot menu. The theme is configured through a plain text file that specifies the layout of the various GUI components (including the boot menu, timeout progress bar, and text messages) as well as the appearance using colors, fonts, and images. Example is available in docs/example_theme.txt

7.2 Theme Elements

7.2.1 Colors

Colors can be specified in several ways:

HTML-style “#RRGGBB” or “#RGB” format, where *R*, *G*, and *B* are hexadecimal digits (e.g., “#8899FF”)
as comma-separated decimal RGB values (e.g., “128, 128, 255”)
with “SVG 1.0 color names” (e.g., “cornflowerblue”) which must be specified in lowercase.

7.2.2 Fonts

The fonts GRUB uses “PFF2 font format” bitmap fonts. Fonts are specified with full font names. Currently there is no provision for a preference list of fonts, or deriving one font from another. Fonts are loaded with the “loadfont” command in GRUB (loadfont). To see the list of loaded fonts, execute the “lsfonts” command (lsfonts). If there are too many fonts to fit on screen, do “set pager=1” before executing “lsfonts”.

7.2.3 Progress Bar

Figure 7.1

Figure 7.2

Progress bars are used to display the remaining time before GRUB boots the default menu entry. To create a progress bar that will display the remaining time before automatic boot, simply create a “progress_bar” component with the id “__timeout__”. This indicates to GRUB that the progress bar should be updated as time passes, and it should be made invisible if the countdown to automatic boot is interrupted by the user.

Progress bars may optionally have text displayed on them. This text is controlled by variable “text” which contains a printf template with the only argument %d is the number of seconds remaining. Additionally special values “@TIMEOUT_NOTIFICATION_SHORT@”, “@TIMEOUT_NOTIFICATION_MIDDLE@”, “@TIMEOUT_NOTIFICATION_LONG@” are replaced with standard and translated templates.

7.2.4 Circular Progress Indicator

The circular progress indicator functions similarly to the progress bar. When given an id of “__timeout__”, GRUB updates the circular progress indicator’s value to indicate the time remaining. For the circular progress indicator, there are two images used to render it: the *center* image, and the *tick* image. The center image is rendered in the center of the component, while the tick image is used to render each mark along the circumference of the indicator.

7.2.5 Labels

Text labels can be placed on the boot screen. The font, color, and horizontal alignment can be specified for labels. If a label is given the id “__timeout__”, then the “text” property for that label is also updated with a message informing the user of the number of seconds remaining until automatic boot. This is useful in case you want the text displayed somewhere else instead of directly on the progress bar.

7.2.6 Boot Menu

The boot menu where GRUB displays the menu entries from the “grub.cfg” file. It is a list of items, where each item has a title and an optional icon. The icon is selected based on the *classes* specified for the menu entry. If there is a PNG file named “myclass.png” in the “grub/themes/icons” directory, it will be displayed for items which have the class *myclass*. The boot menu can be customized in several ways, such as the font and color used for the menu entry title, and by specifying styled boxes for the menu itself and for the selected item highlight.

7.2.7 Styled Boxes

One of the most important features for customizing the layout is the use of *styled boxes*. A styled box is composed of 9 rectangular (and potentially empty) regions, which are used to seamlessly draw the styled box on screen:

Northwest (nw)	North (n)	Northeast (ne)
West (w)	Center (c)	East (e)
Southwest (sw)	South (s)	Southeast (se)

To support any size of box on screen, the center slice and the slices for the top, bottom, and sides are all scaled to the correct size for the component on screen, using the following rules:

The edge slices (north, south, east, and west) are scaled in the direction of the edge they are adjacent to. For instance, the west slice is scaled vertically.
The corner slices (northwest, northeast, southeast, and southwest) are not scaled.
The center slice is scaled to fill the remaining space in the middle.

As an example of how an image might be sliced up, consider the styled box used for a terminal view.

Figure 7.3

7.2.8 Creating Styled Box Images

The Inkscape_ scalable vector graphics editor is a very useful tool for creating styled box images. One process that works well for slicing a drawing into the necessary image slices is:

Create or open the drawing you’d like use.
Create a new layer on the top of the layer stack. Make it visible. Select this layer as the current layer.
Draw 9 rectangles on your drawing where you’d like the slices to be. Clear the fill option, and set the stroke to 1 pixel wide solid stroke. The corners of the slices must meet precisely; if it is off by a single pixel, it will probably be evident when the styled box is rendered in the GRUB menu. You should probably go to File | Document Properties | Grids and enable a grid or create a guide (click on one of the rulers next to the drawing and drag over the drawing; release the mouse button to place the guide) to help place the rectangles precisely.
Right click on the center slice rectangle and choose Object Properties. Change the "Id" to “slice_c“ and click Set. Repeat this for the remaining 8 rectangles, giving them Id values of “slice_n“, “slice_ne“, “slice_e“, and so on according to the location.
Save the drawing.
Select all the slice rectangles. With the slice layer selected, you can simply press Ctrl+A to select all rectangles. The status bar should indicate that 9 rectangles are selected.
Click the layer hide icon for the slice layer in the layer palette. The rectangles will remain selected, even though they are hidden.
Choose File | Export Bitmap and check the *Batch export 9 selected objects* box. Make sure that *Hide all except selected* is unchecked. click *Export*. This will create PNG files in the same directory as the drawing, named after the slices. These can now be used for a styled box in a GRUB theme.

7.3 Theme File Manual

The theme file is a plain text file. Lines that begin with “#“ are ignored and considered comments. (Note: This may not be the case if the previous line ended where a value was expected.)

The theme file contains two types of statements:

Global properties.
Component construction.

7.3.1 Global Properties

7.3.2 Format

Global properties are specified with the simple format:

name1: value1
name2: "value which may contain spaces"
name3: #88F

In this example, name3 is assigned a color value.

7.3.3 Global Property List

title-text	Specifies the text to display at the top center of the screen as a title.
title-font	Defines the font used for the title message at the top of the screen.
title-color	Defines the color of the title message.
message-font	Currently unused. Left for backward compatibility.
message-color	Currently unused. Left for backward compatibility.
message-bg-color	Currently unused. Left for backward compatibility.
desktop-image	Specifies the image to use as the background. It will be scaled to fit the screen size or proportionally scaled depending on the scale method.
desktop-image-scale-method	Specifies the scaling method for the desktop-image. Options are “stretch“, “crop“, “padding“, “fitwidth“, “fitheight“. “stretch“ for fitting the screen size. Otherwise it is proportional scaling of a part of desktop-image to the part of the screen. “crop“ part of the desktop-image will be proportionally scaled to fit the screen sizes. “padding“ the entire desktop-image will be contained on the screen. “fitwidth“ for fitting the desktop-image’s width with screen width. “fitheight“ for fitting the desktop-image’s height with the screen height. Default is “stretch“.
desktop-image-h-align	Specifies the horizontal alignment of the desktop-image if desktop-image-scale-method isn’t equeal to “stretch“. Options are “left“, “center“, “right“. Default is “center“.
desktop-image-v-align	Specifies the vertical alignment of the desktop-image if desktop-image-scale-method isn’t equeal to “stretch“. Options are “top“, “center“, “bottom“. Default is “center“.
desktop-color	Specifies the color for the background if desktop-image is not specified.
terminal-box	Specifies the file name pattern for the styled box slices used for the command line terminal window. For example, “terminal-box: terminal_*.png“ will use the images “terminal_c.png“ as the center area, “terminal_n.png“ as the north (top) edge, “terminal_nw.png“ as the northwest (upper left) corner, and so on. If the image for any slice is not found, it will simply be left empty.
terminal-border	Specifies the border width of the terminal window.
terminal-left	Specifies the left coordinate of the terminal window.
terminal-top	Specifies the top coordinate of the terminal window.
terminal-width	Specifies the width of the terminal window.
terminal-height	Specifies the height of the terminal window.

7.3.4 Component Construction

Greater customizability comes is provided by components. A tree of components forms the user interface. *Containers* are components that can contain other components, and there is always a single root component which is an instance of a *canvas* container.

Components are created in the theme file by prefixing the type of component with a ’+’ sign:

+ label { text="GRUB" font="aqui 11" color="#8FF" }

properties of a component are specified as "name = value" (whitespace surrounding tokens is optional and is ignored) where *value* may be:

a single word (e.g., “align = center“, “color = #FF8080“),
a quoted string (e.g., “text = "Hello, World!"“), or
a tuple (e.g., “preferred_size = (120, 80)“).

7.3.5 Component List

The following is a list of the components and the properties they support.

label A label displays a line of text.

Properties:

id	Set to “__timeout__“ to display the time elapsed to an automatical boot of the default entry.
text	The text to display. If “id“ is set to “__timeout__“ and no “text“ property is set then the amount of seconds will be shown. If set to “@KEYMAP_SHORT@“, “@KEYMAP_MIDDLE@“ or “@KEYMAP_LONG@“ then predefined hotkey information will be shown.
font	The font to use for text display.
color	The color of the text.
align	The horizontal alignment of the text within the component. Options are “left“, “center“ and “right“.
visible	Set to “false“ to hide the label.

image A component that displays an image. The image is scaled to fit the component.
Properties:

file The full path to the image file to load.

progress_bar Displays a horizontally oriented progress bar. It can be rendered using simple solid filled rectangles, or using a pair of pixmap styled boxes.

Properties:

id	Set to “__timeout__“ to display the time elapsed to an automatical boot of the default entry.
fg_color	The foreground color for plain solid color rendering.
bg_color	The background color for plain solid color rendering.
border_color	The border color for plain solid color rendering.
text_color	The text color.
bar_style	The styled box specification for the frame of the progress bar. Example: “progress_frame_*.png“ If the value is equal to “highlight_style“ then no styled boxes will be shown.
highlight_style	The styled box specification for the highlighted region of the progress bar. This box will be used to paint just the highlighted region of the bar, and will be increased in size as the bar nears completion. Example: “progress_hl_*.png“. If the value is equal to “bar_style“ then no styled boxes will be shown.
highlight_overlay	If this option is set to “true“ then the highlight box side slices (every slice except the center slice) will overlay the frame box side slices. And the center slice of the highlight box can move all the way (from top to bottom), being drawn on the center slice of the frame box. That way we can make a progress bar with round-shaped edges so there won’t be a free space from the highlight to the frame in top and bottom scrollbar positions. Default is “false“.
font	The font to use for progress bar.
text	The text to display on the progress bar. If the progress bar’s ID is set to “__timeout__“ and the value of this property is set to “@TIMEOUT_NOTIFICATION_SHORT@“, “@TIMEOUT_NOTIFICATION_MIDDLE@“ or “@TIMEOUT_NOTIFICATION_LONG@“, then GRUB will update this property with an informative message as the timeout approaches.

circular_progress Displays a circular progress indicator. The appearance of this component is determined by two images: the *center* image and the *tick* image. The center image is generally larger and will be drawn in the center of the component. Around the circumference of a circle within the component, the tick image will be drawn a certain number of times, depending on the properties of the component.

Properties:

id	Set to “__timeout__“ to display the time elapsed to an automatical boot of the default entry.
center_bitmap	The file name of the image to draw in the center of the component.
tick_bitmap	The file name of the image to draw for the tick marks.
num_ticks	The number of ticks that make up a full circle.
ticks_disappear	Boolean value indicating whether tick marks should progressively appear, or progressively disappear as value approaches end. Specify “true“ or “false“. Default is “false“.
start_angle	The position of the first tick mark to appear or disappear. Measured in "parrots", 1 "parrot" = 1 / 256 of the full circle. Use values “xxx deg“ or “xxx \xc2\xb0“ to set the angle in degrees.

boot_menu Displays the GRUB boot menu. It allows selecting items and executing them.

Properties:

item_font	The font to use for the menu item titles.
selected_item_font	The font to use for the selected menu item, or “inherit“ (the default) to use “item_font“ for the selected menu item as well.
item_color	The color to use for the menu item titles.
selected_item_color	The color to use for the selected menu item, or “inherit“ (the default) to use “item_color“ for the selected menu item as well.
icon_width	The width of menu item icons. Icons are scaled to the specified size.
icon_height	The height of menu item icons.
item_height	The height of each menu item in pixels.
item_padding	The amount of space in pixels to leave on each side of the menu item contents.
item_icon_space	The space between an item’s icon and the title text, in pixels.
item_spacing	The amount of space to leave between menu items, in pixels.
menu_pixmap_style	The image file pattern for the menu frame styled box. Example: “menu_*.png“ (this will use images such as “menu_c.png“, “menu_w.png“, ‘menu_nw.png“, etc.)
item_pixmap_style	The image file pattern for the item styled box.
selected_item_pixmap_style	The image file pattern for the selected item highlight styled box.
scrollbar	Boolean value indicating whether the scroll bar should be drawn if the frame and thumb styled boxes are configured.
scrollbar_frame	The image file pattern for the entire scroll bar. Example: “scrollbar_*.png“
scrollbar_thumb	The image file pattern for the scroll bar thumb (the part of the scroll bar that moves as scrolling occurs). Example: “scrollbar_thumb_*.png“
scrollbar_thumb_overlay	If this option is set to “true“ then the scrollbar thumb side slices (every slice except the center slice) will overlay the scrollbar frame side slices. And the center slice of the scrollbar_thumb can move all the way (from top to bottom), being drawn on the center slice of the scrollbar frame. That way we can make a scrollbar with round-shaped edges so there won’t be a free space from the thumb to the frame in top and bottom scrollbar positions. Default is “false“.
scrollbar_slice	The menu frame styled box’s slice in which the scrollbar will be drawn. Possible values are “west“, “center“, “east“ (default). “west“ - the scrollbar will be drawn in the west slice (right-aligned). “east“ - the scrollbar will be drawn in the east slice (left-aligned). “center“ - the scrollbar will be drawn in the center slice. Note: in case of “center“ slice: a) If the scrollbar should be drawn then boot menu entry’s width is decreased by the scrollbar’s width and the scrollbar is drawn at the right side of the center slice. b) If the scrollbar won’t be drawn then the boot menu entry’s width is the width of the center slice. c) We don’t necessary need the menu pixmap box to display the scrollbar.
scrollbar_left_pad	The left scrollbar padding in pixels. Unused if “scrollbar_slice“ is “west“.
scrollbar_right_pad	The right scrollbar padding in pixels. Unused if “scrollbar_slice“ is “east“.
scrollbar_top_pad	The top scrollbar padding in pixels.
scrollbar_bottom_pad	The bottom scrollbar padding in pixels.
visible	Set to “false“ to hide the boot menu.

canvas Canvas is a container that allows manual placement of components within it. It does not alter the positions of its child components. It assigns all child components their preferred sizes.
hbox The *hbox* container lays out its children from left to right, giving each one its preferred width. The height of each child is set to the maximum of the preferred heights of all children.
vbox The *vbox* container lays out its children from top to bottom, giving each one its preferred height. The width of each child is set to the maximum of the preferred widths of all children.

7.3.6 Common properties

The following properties are supported by all components:

‘left’

The distance from the left border of container to left border of the object in either of three formats:

x	Value in pixels
p%	Percentage
p%+x	mixture of both

‘top’

The distance from the left border of container to left border of the object in same format.

‘width’

The width of object in same format.

‘height’

The height of object in same format.

‘id’

The identifier for the component. This can be any arbitrary string. The ID can be used by scripts to refer to various components in the GUI component tree. Currently, there is one special ID value that GRUB recognizes:

“__timeout__“

Component with this ID will be updated by GRUB and will indicate time elapsed to an automatical boot of the default entry. Affected components: “label“, “circular_progress“, “progress_bar“.

8 Booting GRUB from the network

The following instructions don’t work for *-emu, i386-qemu, i386-coreboot, i386-multiboot, mips_loongson, mips-arc and mips_qemu_mips

To generate a netbootable directory, run:

grub-mknetdir --net-directory=/srv/tftp --subdir=/boot/grub -d /usr/lib/grub/<platform>

E.g. for i386-pc:

grub-mknetdir --net-directory=/srv/tftp --subdir=/boot/grub -d /usr/lib/grub/i386-pc

Then follow instructions printed out by grub-mknetdir on configuring your DHCP server.

The grub.cfg file is placed in the same directory as the path output by grub-mknetdir hereafter referred to as FWPATH. GRUB will search for its configuration files in order using the following rules where the appended value corresponds to a value on the client machine.

‘(FWPATH)’/grub.cfg-‘(UUID OF NIC)’
‘(FWPATH)’/grub.cfg-‘(MAC ADDRESS OF NIC)’
‘(FWPATH)’/grub.cfg-‘(IPv4 OR IPv6 ADDRESS)’
‘(FWPATH)’/grub.cfg

The client will only attempt to look up an IPv6 address config once, however, it will try the IPv4 multiple times. The concrete example below shows what would happen under the IPv4 case.

UUID: 7726a678-7fc0-4853-a4f6-c85ac36a120a
MAC:  52:54:00:ec:33:81
IPV4: 10.0.0.130 (0A000082)

‘(FWPATH)’/grub.cfg-7726a678-7fc0-4853-a4f6-c85ac36a120a
‘(FWPATH)’/grub.cfg-52-54-00-ec-33-81
‘(FWPATH)’/grub.cfg-0A000082
‘(FWPATH)’/grub.cfg-0A00008
‘(FWPATH)’/grub.cfg-0A0000
‘(FWPATH)’/grub.cfg-0A000
‘(FWPATH)’/grub.cfg-0A00
‘(FWPATH)’/grub.cfg-0A0
‘(FWPATH)’/grub.cfg-0A
‘(FWPATH)’/grub.cfg-0
‘(FWPATH)’/grub.cfg

After GRUB has started, files on the TFTP server will be accessible via the ‘(tftp)’ device.

The server IP address can be controlled by changing the ‘(tftp)’ device name to ‘(tftp,server-ip)’. Note that this should be changed both in the prefix and in any references to the device name in the configuration file.

GRUB provides several environment variables which may be used to inspect or change the behaviour of the PXE device. In the following description <interface> is placeholder for the name of network interface (platform dependent):

‘net_<interface>_ip’: The network interface’s IP address. Read-only.
‘net_<interface>_mac’: The network interface’s MAC address. Read-only.
‘net_<interface>_hostname’: The client host name provided by DHCP. Read-only.
‘net_<interface>_domain’: The client domain name provided by DHCP. Read-only.
‘net_<interface>_rootpath’: The path to the client’s root disk provided by DHCP. Read-only.
‘net_<interface>_extensionspath’: The path to additional DHCP vendor extensions provided by DHCP. Read-only.
‘net_<interface>_boot_file’: The boot file name provided by DHCP. Read-only.
‘net_<interface>_dhcp_server_name’: The name of the DHCP server responsible for these boot parameters. Read-only.
‘net_default_interface’: Initially set to name of network interface that was used to load grub. Read-write, although setting it affects only interpretation of ‘net_default_ip’ and ‘net_default_mac’
‘net_default_ip’: The IP address of default interface. Read-only. This is alias for the ‘net_${net_default_interface}_ip’.
‘net_default_mac’: The default interface’s MAC address. Read-only. This is alias for the ‘net_${net_default_interface}_mac’.
‘net_default_server’: The default server used by network drives (see Device syntax). Read-write, although setting this is only useful before opening a network device.

9 Using GRUB via a serial line

This chapter describes how to use the serial terminal support in GRUB.

If you have many computers or computers with no display/keyboard, it could be very useful to control the computers through serial communications. To connect one computer with another via a serial line, you need to prepare a null-modem (cross) serial cable, and you may need to have multiport serial boards, if your computer doesn’t have extra serial ports. In addition, a terminal emulator is also required, such as minicom. Refer to a manual of your operating system, for more information.

As for GRUB, the instruction to set up a serial terminal is quite simple. Here is an example:

grub> serial --unit=0 --speed=9600
grub> terminal_input serial; terminal_output serial

The command serial initializes the serial unit 0 with the speed 9600bps. The serial unit 0 is usually called ‘COM1’, so, if you want to use COM2, you must specify ‘--unit=1’ instead. This command accepts many other options, so please refer to serial, for more details.

The commands terminal_input (see terminal_input) and terminal_output (see terminal_output) choose which type of terminal you want to use. In the case above, the terminal will be a serial terminal, but you can also pass console to the command, as ‘terminal_input serial console’. In this case, a terminal in which you press any key will be selected as a GRUB terminal. In the example above, note that you need to put both commands on the same command line, as you will lose the ability to type commands on the console after the first command.

However, note that GRUB assumes that your terminal emulator is compatible with VT100 by default. This is true for most terminal emulators nowadays, but you should pass the option --dumb to the command if your terminal emulator is not VT100-compatible or implements few VT100 escape sequences. If you specify this option then GRUB provides you with an alternative menu interface, because the normal menu requires several fancy features of your terminal.

10 Using GRUB with vendor power-on keys

Some laptop vendors provide an additional power-on button which boots another OS. GRUB supports such buttons with the ‘GRUB_TIMEOUT_BUTTON’, ‘GRUB_TIMEOUT_STYLE_BUTTON’, ‘GRUB_DEFAULT_BUTTON’, and ‘GRUB_BUTTON_CMOS_ADDRESS’ variables in default/grub (see Simple configuration). ‘GRUB_TIMEOUT_BUTTON’, ‘GRUB_TIMEOUT_STYLE_BUTTON’, and ‘GRUB_DEFAULT_BUTTON’ are used instead of the corresponding variables without the ‘_BUTTON’ suffix when powered on using the special button. ‘GRUB_BUTTON_CMOS_ADDRESS’ is vendor-specific and partially model-specific. Values known to the GRUB team are:

Dell XPS M1330M: 121:3
Dell XPS M1530: 85:3
Dell Latitude E4300: 85:3
Asus EeePC 1005PE: 84:1 (unconfirmed)

To take full advantage of this function, install GRUB into the MBR (see Installing GRUB using grub-install).

If you have a laptop which has a similar feature and not in the above list could you figure your address and contribute? To discover the address do the following:

boot normally

sudo modprobe nvram
sudo cat /dev/nvram | xxd > normal_button.txt

boot using vendor button

sudo modprobe nvram
sudo cat /dev/nvram | xxd > normal_vendor.txt

Then compare these text files and find where a bit was toggled. E.g. in case of Dell XPS it was:

byte 0x47: 20 --> 28

It’s a bit number 3 as seen from following table:

0	01
1	02
2	04
3	08
4	10
5	20
6	40
7	80

0x47 is decimal 71. Linux nvram implementation cuts first 14 bytes of CMOS. So the real byte address in CMOS is 71+14=85 So complete address is 85:3

11 GRUB image files

GRUB consists of several images: a variety of bootstrap images for starting GRUB in various ways, a kernel image, and a set of modules which are combined with the kernel image to form a core image. Here is a short overview of them.

boot.img

On PC BIOS systems, this image is the first part of GRUB to start. It is written to a master boot record (MBR) or to the boot sector of a partition. Because a PC boot sector is 512 bytes, the size of this image is exactly 512 bytes.

The sole function of boot.img is to read the first sector of the core image from a local disk and jump to it. Because of the size restriction, boot.img cannot understand any file system structure, so grub-install hardcodes the location of the first sector of the core image into boot.img when installing GRUB.

diskboot.img

This image is used as the first sector of the core image when booting from a hard disk. It reads the rest of the core image into memory and starts the kernel. Since file system handling is not yet available, it encodes the location of the core image using a block list format.

cdboot.img

This image is used as the first sector of the core image when booting from a CD-ROM drive. It performs a similar function to diskboot.img.

pxeboot.img

This image is used as the start of the core image when booting from the network using PXE. See Network.

lnxboot.img

This image may be placed at the start of the core image in order to make GRUB look enough like a Linux kernel that it can be booted by LILO using an ‘image=’ section.

kernel.img

This image contains GRUB’s basic run-time facilities: frameworks for device and file handling, environment variables, the rescue mode command-line parser, and so on. It is rarely used directly, but is built into all core images.

core.img

This is the core image of GRUB. It is built dynamically from the kernel image and an arbitrary list of modules by the grub-mkimage program. Usually, it contains enough modules to access /boot/grub, and loads everything else (including menu handling, the ability to load target operating systems, and so on) from the file system at run-time. The modular design allows the core image to be kept small, since the areas of disk where it must be installed are often as small as 32KB.

See BIOS installation, for details on where the core image can be installed on PC systems.

*.mod

Everything else in GRUB resides in dynamically loadable modules. These are often loaded automatically, or built into the core image if they are essential, but may also be loaded manually using the insmod command (see insmod).

For GRUB Legacy users

GRUB 2 has a different design from GRUB Legacy, and so correspondences with the images it used cannot be exact. Nevertheless, GRUB Legacy users often ask questions in the terms they are familiar with, and so here is a brief guide to how GRUB 2’s images relate to that.

stage1

Stage 1 from GRUB Legacy was very similar to boot.img in GRUB 2, and they serve the same function.

*_stage1_5

In GRUB Legacy, Stage 1.5’s function was to include enough filesystem code to allow the much larger Stage 2 to be read from an ordinary filesystem. In this respect, its function was similar to core.img in GRUB 2. However, core.img is much more capable than Stage 1.5 was; since it offers a rescue shell, it is sometimes possible to recover manually in the event that it is unable to load any other modules, for example if partition numbers have changed. core.img is built in a more flexible way, allowing GRUB 2 to support reading modules from advanced disk types such as LVM and RAID.

GRUB Legacy could run with only Stage 1 and Stage 2 in some limited configurations, while GRUB 2 requires core.img and cannot work without it.

stage2

GRUB 2 has no single Stage 2 image. Instead, it loads modules from /boot/grub at run-time.

stage2_eltorito

In GRUB 2, images for booting from CD-ROM drives are now constructed using cdboot.img and core.img, making sure that the core image contains the ‘iso9660’ module. It is usually best to use the grub-mkrescue program for this.

nbgrub

There is as yet no equivalent for nbgrub in GRUB 2; it was used by Etherboot and some other network boot loaders.

pxegrub

In GRUB 2, images for PXE network booting are now constructed using pxeboot.img and core.img, making sure that the core image contains the ‘pxe’ and ‘pxecmd’ modules. See Network.

12 Core image size limitation

Heavily limited platforms:

i386-pc (normal and PXE): the core image size (compressed) is limited by 458240 bytes. kernel.img (.text + .data + .bss, uncompressed) is limited by 392704 bytes. module size (uncompressed) + kernel.img (.text + .data, uncompressed) is limited by the size of contiguous chunk at 1M address.
sparc64-ieee1275: kernel.img (.text + .data + .bss) + modules + 256K (stack) + 2M (heap) is limited by space available at 0x4400. On most platforms it’s just 3 or 4M since ieee1275 maps only so much.
i386-ieee1275: kernel.img (.text + .data + .bss) + modules is limited by memory available at 0x10000, at most 596K

Lightly limited platforms:

*-xen: limited only by adress space and RAM size.
i386-qemu: kernel.img (.text + .data + .bss) is limited by 392704 bytes. (core.img would be limited by ROM size but it’s unlimited on qemu
All EFI platforms: limited by contiguous RAM size and possibly firmware bugs
Coreboot and multiboot. kernel.img (.text + .data + .bss) is limited by 392704 bytes. module size is limited by the size of contiguous chunk at 1M address.
mipsel-loongson (ELF), mips(el)-qemu_mips (ELF): if uncompressed: kernel.img (.text + .data) + modules is limited by the space from 80200000 forward if compressed: kernel.img (.text + .data, uncompressed) + modules (uncompressed) + (modules + kernel.img (.text + .data)) (compressed) + decompressor is limited by the space from 80200000 forward
mipsel-loongson (Flash), mips(el)-qemu_mips (Flash): kernel.img (.text + .data) + modules is limited by the space from 80200000 forward core.img (final) is limited by flash size (512K on yeeloong and fulooong)
mips-arc: if uncompressed: kernel.img (.text + .data) is limited by the space from 8bd00000 forward modules + dummy decompressor is limited by the space from 8bd00000 backward if compressed: kernel.img (.text + .data, uncompressed) is limited by the space from 8bd00000 forward modules (uncompressed) + (modules + kernel.img (.text + .data)) (compressed, aligned to 1M) + 1M (decompressor + scratch space) is limited by the space from 8bd00000 backward
powerpc-ieee1275: kernel.img (.text + .data + .bss) + modules is limited by space available at 0x200000

13 Filesystem syntax and semantics

GRUB uses a special syntax for specifying disk drives which can be accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish between IDE, ESDI, SCSI, or others. You must know yourself which BIOS device is equivalent to which OS device. Normally, that will be clear if you see the files in a device or use the command search (see search).

13.1 How to specify devices

The device syntax is like this:

(device[,partmap-name1part-num1[,partmap-name2part-num2[,...]]])

‘[]’ means the parameter is optional. device depends on the disk driver in use. BIOS and EFI disks use either ‘fd’ or ‘hd’ followed by a digit, like ‘fd0’, or ‘cd’. AHCI, PATA (ata), crypto, USB use the name of driver followed by a number. Memdisk and host are limited to one disk and so it’s refered just by driver name. RAID (md), ofdisk (ieee1275 and nand), LVM (lvm), LDM, virtio (vdsk) and arcdisk (arc) use intrinsic name of disk prefixed by driver name. Additionally just “nand” refers to the disk aliased as “nand”. Conflicts are solved by suffixing a number if necessarry. Commas need to be escaped. Loopback uses whatever name specified to loopback command. Hostdisk uses names specified in device.map as long as it’s of the form [fhc]d[0-9]* or hostdisk/<OS DEVICE>. For crypto and RAID (md) additionally you can use the syntax <driver name>uuid/<uuid>. For LVM additionally you can use the syntax lvmid/<volume-group-uuid>/<volume-uuid>.

(fd0)
(hd0)
(cd)
(ahci0)
(ata0)
(crypto0)
(usb0)
(cryptouuid/123456789abcdef0123456789abcdef0)
(mduuid/123456789abcdef0123456789abcdef0)
(lvm/system-root)
(lvmid/F1ikgD-2RES-306G-il9M-7iwa-4NKW-EbV1NV/eLGuCQ-L4Ka-XUgR-sjtJ-ffch-bajr-fCNfz5)
(md/myraid)
(md/0)
(ieee1275/disk2)
(ieee1275//pci@1f\,0/ide@d/disk@2)
(nand)
(memdisk)
(host)
(myloop)
(hostdisk//dev/sda)

part-num represents the partition number of device, starting from one. partname is optional but is recommended since disk may have several top-level partmaps. Specifying third and later component you can access to subpartitions.

The syntax ‘(hd0)’ represents using the entire disk (or the MBR when installing GRUB), while the syntax ‘(hd0,1)’ represents using the first partition of the disk (or the boot sector of the partition when installing GRUB).

(hd0,msdos1)
(hd0,msdos1,msdos5)
(hd0,msdos1,bsd3)
(hd0,netbsd1)
(hd0,gpt1)
(hd0,1,3)

If you enabled the network support, the special drives (protocol[,server]) are also available. Supported protocols are ‘http’ and ‘tftp’. If server is omitted, value of environment variable ‘net_default_server’ is used. Before using the network drive, you must initialize the network. See Network, for more information.

If you boot GRUB from a CD-ROM, ‘(cd)’ is available. See Making a GRUB bootable CD-ROM, for details.

13.2 How to specify files

There are two ways to specify files, by absolute file name and by block list.

An absolute file name resembles a Unix absolute file name, using ‘/’ for the directory separator (not ‘\’ as in DOS). One example is ‘(hd0,1)/boot/grub/grub.cfg’. This means the file /boot/grub/grub.cfg in the first partition of the first hard disk. If you omit the device name in an absolute file name, GRUB uses GRUB’s root device implicitly. So if you set the root device to, say, ‘(hd1,1)’ by the command ‘set root=(hd1,1)’ (see set), then /boot/kernel is the same as (hd1,1)/boot/kernel.

On ZFS filesystem the first path component must be volume‘@’[snapshot]. So ‘/rootvol@snap-129/boot/grub/grub.cfg’ refers to file ‘/boot/grub/grub.cfg’ in snapshot of volume ‘rootvol’ with name ‘snap-129’. Trailing ‘@’ after volume name is mandatory even if snapshot name is omitted.

13.3 How to specify block lists

A block list is used for specifying a file that doesn’t appear in the filesystem, like a chainloader. The syntax is [offset]+length[,[offset]+length]…. Here is an example:

0+100,200+1,300+300

This represents that GRUB should read blocks 0 through 99, block 200, and blocks 300 through 599. If you omit an offset, then GRUB assumes the offset is zero.

Like the file name syntax (see File name syntax), if a blocklist does not contain a device name, then GRUB uses GRUB’s root device. So (hd0,2)+1 is the same as +1 when the root device is ‘(hd0,2)’.

14 GRUB’s user interface

GRUB has both a simple menu interface for choosing preset entries from a configuration file, and a highly flexible command-line for performing any desired combination of boot commands.

GRUB looks for its configuration file as soon as it is loaded. If one is found, then the full menu interface is activated using whatever entries were found in the file. If you choose the command-line menu option, or if the configuration file was not found, then GRUB drops to the command-line interface.

14.1 The flexible command-line interface

The command-line interface provides a prompt and after it an editable text area much like a command-line in Unix or DOS. Each command is immediately executed after it is entered⁸. The commands (see Command-line and menu entry commands) are a subset of those available in the configuration file, used with exactly the same syntax.

Cursor movement and editing of the text on the line can be done via a subset of the functions available in the Bash shell:

C-f
PC right key: Move forward one character.
C-b
PC left key: Move back one character.
C-a
HOME: Move to the start of the line.
C-e
END: Move the the end of the line.
C-d
DEL: Delete the character underneath the cursor.
C-h
BS: Delete the character to the left of the cursor.
C-k: Kill the text from the current cursor position to the end of the line.
C-u: Kill backward from the cursor to the beginning of the line.
C-y: Yank the killed text back into the buffer at the cursor.
C-p
PC up key: Move up through the history list.
C-n
PC down key: Move down through the history list.

When typing commands interactively, if the cursor is within or before the first word in the command-line, pressing the TAB key (or C-i) will display a listing of the available commands, and if the cursor is after the first word, the TAB will provide a completion listing of disks, partitions, and file names depending on the context. Note that to obtain a list of drives, one must open a parenthesis, as root (.

Note that you cannot use the completion functionality in the TFTP filesystem. This is because TFTP doesn’t support file name listing for the security.

14.2 The simple menu interface

The menu interface is quite easy to use. Its commands are both reasonably intuitive and described on screen.

Basically, the menu interface provides a list of boot entries to the user to choose from. Use the arrow keys to select the entry of choice, then press RET to run it. An optional timeout is available to boot the default entry (the first one if not set), which is aborted by pressing any key.

Commands are available to enter a bare command-line by pressing c (which operates exactly like the non-config-file version of GRUB, but allows one to return to the menu if desired by pressing ESC) or to edit any of the boot entries by pressing e.

If you protect the menu interface with a password (see Security), all you can do is choose an entry by pressing RET, or press p to enter the password.

14.3 Editing a menu entry

The menu entry editor looks much like the main menu interface, but the lines in the menu are individual commands in the selected entry instead of entry names.

If an ESC is pressed in the editor, it aborts all the changes made to the configuration entry and returns to the main menu interface.

Each line in the menu entry can be edited freely, and you can add new lines by pressing RET at the end of a line. To boot the edited entry, press Ctrl-x.

Although GRUB unfortunately does not support undo, you can do almost the same thing by just returning to the main menu using ESC.

15 GRUB environment variables

GRUB supports environment variables which are rather like those offered by all Unix-like systems. Environment variables have a name, which is unique and is usually a short identifier, and a value, which is an arbitrary string of characters. They may be set (see set), unset (see unset), or looked up (see Shell-like scripting) by name.

A number of environment variables have special meanings to various parts of GRUB. Others may be used freely in GRUB configuration files.

15.1 Special environment variables

These variables have special meaning to GRUB.

15.1.1 biosnum

When chain-loading another boot loader (see Chain-loading), GRUB may need to know what BIOS drive number corresponds to the root device (see root) so that it can set up registers properly. If the biosnum variable is set, it overrides GRUB’s own means of guessing this.

For an alternative approach which also changes BIOS drive mappings for the chain-loaded system, see drivemap.

15.1.2 check_signatures

This variable controls whether GRUB enforces digital signature validation on loaded files. See Using digital signatures.

15.1.3 chosen

When executing a menu entry, GRUB sets the chosen variable to the title of the entry being executed.

If the menu entry is in one or more submenus, then chosen is set to the titles of each of the submenus starting from the top level followed by the title of the menu entry itself, separated by ‘>’.

15.1.4 cmdpath

The location from which core.img was loaded as an absolute directory name (see File name syntax). This is set by GRUB at startup based on information returned by platform firmware. Not every platform provides this information and some may return only device without path name.

15.1.5 color_highlight

This variable contains the “highlight” foreground and background terminal colors, separated by a slash (‘/’). Setting this variable changes those colors. For the available color names, see color_normal.

The default is ‘black/light-gray’.

15.1.6 color_normal

This variable contains the “normal” foreground and background terminal colors, separated by a slash (‘/’). Setting this variable changes those colors. Each color must be a name from the following list:

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

The default is ‘light-gray/black’.

The color support support varies from terminal to terminal.

‘morse’ has no color support at all.

‘mda_text’ color support is limited to highlighting by black/white reversal.

‘console’ on ARC, EMU and IEEE1275, ‘serial_*’ and ‘spkmodem’ are governed by terminfo and support only 8 colors if in modes ‘vt100-color’ (default for console on emu), ‘arc’ (default for console on ARC), ‘ieee1275’ (default for console on IEEE1275). When in mode ‘vt100’ then the color support is limited to highlighting by black/white reversal. When in mode ‘dumb’ there is no color support.

When console supports no colors this setting is ignored. When console supports 8 colors, then the colors from the second half of the previous list are mapped to the matching colors of first half.

‘console’ on EFI and BIOS and ‘vga_text’ support all 16 colors.

‘gfxterm’ supports all 16 colors and would be theoretically extendable to support whole rgb24 palette but currently there is no compelling reason to go beyond the current 16 colors.

15.1.7 debug

This variable may be set to enable debugging output from various components of GRUB. The value is a list of debug facility names separated by whitespace or ‘,’, or ‘all’ to enable all available debugging output. The facility names are the first argument to grub_dprintf. Consult source for more details.

15.1.8 default

If this variable is set, it identifies a menu entry that should be selected by default, possibly after a timeout (see timeout). The entry may be identified by number or by id.

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:

default=example-gnu-linux

If the entry is in a submenu, then it must be identified using the titles of each of the submenus starting from the top level followed by the number or title of the menu entry itself, separated by ‘>’. For example, take the following menu structure:

Submenu 1
  Menu Entry 1
  Menu Entry 2
Submenu 2
  Submenu 3
    Menu Entry 3
    Menu Entry 4
  Menu Entry 5

“Menu Entry 3” would then be identified as ‘Submenu 2>Submenu 3>Menu Entry 3’.

This variable is often set by ‘GRUB_DEFAULT’ (see Simple configuration), grub-set-default, or grub-reboot.

15.1.9 fallback

If this variable is set, it identifies a menu entry that should be selected if the default menu entry fails to boot. Entries are identified in the same way as for ‘default’ (see default).

15.1.10 gfxmode

If this variable is set, it sets 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 selects a platform-specific default that should look reasonable. Supported modes can be listed by ‘videoinfo’ command in GRUB.

The resolution may be specified as a sequence of one or more modes, separated by commas (‘,’) or semicolons (‘;’); each will be tried in turn until one is found. Each mode should be either ‘auto’, ‘widthxheight’, or ‘widthxheightxdepth’.

15.1.11 gfxpayload

If this variable is set, it controls the video mode in which the Linux kernel starts up, replacing the ‘vga=’ boot option (see linux). It may be set to ‘text’ to force the Linux kernel to boot in normal text mode, ‘keep’ to preserve the graphics mode set using ‘gfxmode’, or any of the permitted values for ‘gfxmode’ to set a particular graphics mode (see gfxmode).

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 variable to ‘text’ and GRUB will tell Linux to boot in normal text mode.

The default is platform-specific. On platforms with a native text mode (such as PC BIOS platforms), the default is ‘text’. Otherwise the default may be ‘auto’ or a specific video mode.

This variable is often set by ‘GRUB_GFXPAYLOAD_LINUX’ (see Simple configuration).

15.1.12 gfxterm_font

If this variable is set, it names a font to use for text on the ‘gfxterm’ graphical terminal. Otherwise, ‘gfxterm’ may use any available font.

15.1.13 grub_cpu

In normal mode (see normal), GRUB sets the ‘grub_cpu’ variable to the CPU type for which GRUB was built (e.g. ‘i386’ or ‘powerpc’).

15.1.14 grub_platform

In normal mode (see normal), GRUB sets the ‘grub_platform’ variable to the platform for which GRUB was built (e.g. ‘pc’ or ‘efi’).

15.1.15 icondir

If this variable is set, it names a directory in which the GRUB graphical menu should look for icons after looking in the theme’s ‘icons’ directory. See Theme file format.

15.1.16 lang

If this variable is set, it names the language code that the gettext command (see gettext) uses to translate strings. For example, French would be named as ‘fr’, and Simplified Chinese as ‘zh_CN’.

grub-mkconfig (see Simple configuration) will try to set a reasonable default for this variable based on the system locale.

15.1.17 locale_dir

If this variable is set, it names the directory where translation files may be found (see gettext), usually /boot/grub/locale. Otherwise, internationalization is disabled.

grub-mkconfig (see Simple configuration) will set a reasonable default for this variable if internationalization is needed and any translation files are available.

15.1.18 menu_color_highlight

This variable contains the foreground and background colors to be used for the highlighted menu entry, separated by a slash (‘/’). Setting this variable changes those colors. For the available color names, see color_normal.

The default is the value of ‘color_highlight’ (see color_highlight).

15.1.19 menu_color_normal

This variable contains the foreground and background colors to be used for non-highlighted menu entries, separated by a slash (‘/’). Setting this variable changes those colors. For the available color names, see color_normal.

The default is the value of ‘color_normal’ (see color_normal).

15.1.32 pager

If set to ‘1’, pause output after each screenful and wait for keyboard input. The default is not to pause output.

15.1.33 prefix

The location of the ‘/boot/grub’ directory as an absolute file name (see File name syntax). This is normally set by GRUB at startup based on information provided by grub-install. GRUB modules are dynamically loaded from this directory, so it must be set correctly in order for many parts of GRUB to work.

15.1.34 pxe_blksize

See Network.

15.1.35 pxe_default_gateway

See Network.

15.1.36 pxe_default_server

See Network.

15.1.37 root

The root device name (see Device syntax). Any file names that do not specify an explicit device name are read from this device. The default is normally set by GRUB at startup based on the value of ‘prefix’ (see prefix).

For example, if GRUB was installed to the first partition of the first hard disk, then ‘prefix’ might be set to ‘(hd0,msdos1)/boot/grub’ and ‘root’ to ‘hd0,msdos1’.

15.1.38 superusers

This variable may be set to a list of superuser names to enable authentication support. See Security.

15.1.39 theme

This variable may be set to a directory containing a GRUB graphical menu theme. See Theme file format.

This variable is often set by ‘GRUB_THEME’ (see Simple configuration).

15.1.40 timeout

If this variable is set, it specifies the time in seconds to wait for keyboard input before booting the default menu entry. A timeout of ‘0’ means to boot the default entry immediately without displaying the menu; a timeout of ‘-1’ (or unset) means to wait indefinitely.

If ‘timeout_style’ (see timeout_style) is set to ‘countdown’ or ‘hidden’, the timeout is instead counted before the menu is displayed.

This variable is often set by ‘GRUB_TIMEOUT’ (see Simple configuration).

15.1.41 timeout_style

This variable may be set to ‘menu’, ‘countdown’, or ‘hidden’ to control the way in which the timeout (see timeout) interacts with displaying the menu. See the documentation of ‘GRUB_TIMEOUT_STYLE’ (see Simple configuration) for details.

15.2 The GRUB environment block

It is often useful to be able to remember a small amount of information from one boot to the next. For example, you might want to set the default menu entry based on what was selected the last time. GRUB deliberately does not implement support for writing files in order to minimise the possibility of the boot loader being responsible for file system corruption, so a GRUB configuration file cannot just create a file in the ordinary way. However, GRUB provides an “environment block” which can be used to save a small amount of state.

The environment block is a preallocated 1024-byte file, which normally lives in /boot/grub/grubenv (although you should not assume this). At boot time, the load_env command (see load_env) loads environment variables from it, and the save_env (see save_env) command saves environment variables to it. From a running system, the grub-editenv utility can be used to edit the environment block.

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).

grub-mkconfig uses this facility to implement ‘GRUB_SAVEDEFAULT’ (see Simple configuration).

16 The list of available commands

In this chapter, we list all commands that are available in GRUB.

Commands belong to different groups. A few can only be used in the global section of the configuration file (or “menu”); most of them can be entered on the command-line and can be used either anywhere in the menu or specifically in the menu entries.

In rescue mode, only the insmod (see insmod), ls (see ls), set (see set), and unset (see unset) commands are normally available. If you end up in rescue mode and do not know what to do, then see GRUB only offers a rescue shell.

16.1 The list of commands for the menu only

The semantics used in parsing the configuration file are the following:

The files must be in plain-text format.
‘#’ at the beginning of a line in a configuration file means it is only a comment.
Options are separated by spaces.
All numbers can be either decimal or hexadecimal. A hexadecimal number must be preceded by ‘0x’, and is case-insensitive.

These commands can only be used in the menu:

16.1.1 menuentry

Command: menuentry title [--class=class …] [--users=users] [--unrestricted] [--hotkey=key] [--id=id] [arg …] { command; … }

This defines a GRUB menu entry named title. When this entry is selected from the menu, GRUB will set the chosen environment variable to value of --id if --id is given, execute the list of commands given within braces, and if the last command in the list returned successfully and a kernel was loaded it will execute the boot command.

The --class option may be used any number of times to group menu entries into classes. Menu themes may display different classes using different styles.

The --users option grants specific users access to specific menu entries. See Security.

The --unrestricted option grants all users access to specific menu entries. See Security.

The --hotkey option associates a hotkey with a menu entry. key may be a single letter, or one of the aliases ‘backspace’, ‘tab’, or ‘delete’.

The --id may be used to associate unique identifier with a menu entry. id is string of ASCII aphanumeric characters, underscore and hyphen and should not start with a digit.

All other arguments including title are passed as positional parameters when list of commands is executed with title always assigned to $1.

16.1.2 submenu

Command: submenu title [--class=class …] [--users=users] [--unrestricted] [--hotkey=key] [--id=id] { menu entries … }

This defines a submenu. An entry called title will be added to the menu; when that entry is selected, a new menu will be displayed showing all the entries within this submenu.

All options are the same as in the menuentry command (see menuentry).

16.2 The list of general commands

Commands usable anywhere in the menu and in the command-line.

16.2.1 serial

Command: serial [--unit=unit] [--port=port] [--speed=speed] [--word=word] [--parity=parity] [--stop=stop]

Initialize a serial device. unit is a number in the range 0-3 specifying which serial port to use; default is 0, which corresponds to the port often called COM1. port is the I/O port where the UART is to be found; if specified it takes precedence over unit. speed is the transmission speed; default is 9600. word and stop are the number of data bits and stop bits. Data bits must be in the range 5-8 and stop bits must be 1 or 2. Default is 8 data bits and one stop bit. parity is one of ‘no’, ‘odd’, ‘even’ and defaults to ‘no’.

The serial port is not used as a communication channel unless the terminal_input or terminal_output command is used (see terminal_input, see terminal_output).

16.2.2 terminal_input

Command: terminal_input [--append|--remove] [terminal1] [terminal2] …

List or select an input terminal.

With no arguments, list the active and available input terminals.

With --append, add the named terminals to the list of active input terminals; any of these may be used to provide input to GRUB.

With --remove, remove the named terminals from the active list.

With no options but a list of terminal names, make only the listed terminal names active.

16.2.3 terminal_output

Command: terminal_output [--append|--remove] [terminal1] [terminal2] …

List or select an output terminal.

With no arguments, list the active and available output terminals.

With --append, add the named terminals to the list of active output terminals; all of these will receive output from GRUB.

With --remove, remove the named terminals from the active list.

With no options but a list of terminal names, make only the listed terminal names active.

16.2.4 terminfo

Command: terminfo [-a|-u|-v] [term]

Define the capabilities of your terminal by giving the name of an entry in the terminfo database, which should correspond roughly to a ‘TERM’ environment variable in Unix.

The currently available terminal types are ‘vt100’, ‘vt100-color’, ‘ieee1275’, and ‘dumb’. If you need other terminal types, please contact us to discuss the best way to include support for these in GRUB.

The -a (--ascii), -u (--utf8), and -v (--visual-utf8) options control how non-ASCII text is displayed. -a specifies an ASCII-only terminal; -u specifies logically-ordered UTF-8; and -v specifies "visually-ordered UTF-8" (in other words, arranged such that a terminal emulator without bidirectional text support will display right-to-left text in the proper order; this is not really proper UTF-8, but a workaround).

If no option or terminal type is specified, the current terminal type is printed.

16.3 The list of command-line and menu entry commands

These commands are usable in the command-line and in menu entries. If you forget a command, you can run the command help (see help).

• [:		Check file types and compare values
• acpi:		Load ACPI tables
• authenticate:		Check whether user is in user list
• background_color:		Set background color for active terminal
• background_image:		Load background image for active terminal
• badram:		Filter out bad regions of RAM
• blocklist:		Print a block list
• boot:		Start up your operating system
• cat:		Show the contents of a file
• chainloader:		Chain-load another boot loader
• clear:		Clear the screen
• cmosclean:		Clear bit in CMOS
• cmosdump:		Dump CMOS contents
• cmostest:		Test bit in CMOS
• cmp:		Compare two files
• configfile:		Load a configuration file
• cpuid:		Check for CPU features
• crc:		Compute or check CRC32 checksums
• cryptomount:		Mount a crypto device
• date:		Display or set current date and time
• devicetree:		Load a device tree blob
• distrust:		Remove a pubkey from trusted keys
• drivemap:		Map a drive to another
• echo:		Display a line of text
• eval:		Evaluate agruments as GRUB commands
• export:		Export an environment variable
• false:		Do nothing, unsuccessfully
• gettext:		Translate a string
• gptsync:		Fill an MBR based on GPT entries
• halt:		Shut down your computer
• hashsum:		Compute or check hash checksum
• help:		Show help messages
• initrd:		Load a Linux initrd
• initrd16:		Load a Linux initrd (16-bit mode)
• insmod:		Insert a module
• keystatus:		Check key modifier status
• linux:		Load a Linux kernel
• linux16:		Load a Linux kernel (16-bit mode)
• list_env:		List variables in environment block
• list_trusted:		List trusted public keys
• load_env:		Load variables from environment block
• loadfont:		Load font files
• loopback:		Make a device from a filesystem image
• ls:		List devices or files
• lsfonts:		List loaded fonts
• lsmod:		Show loaded modules
• md5sum:		Compute or check MD5 hash
• module:		Load module for multiboot kernel
• multiboot:		Load multiboot compliant kernel
• nativedisk:		Switch to native disk drivers
• normal:		Enter normal mode
• normal_exit:		Exit from normal mode
• parttool:		Modify partition table entries
• password:		Set a clear-text password
• password_pbkdf2:		Set a hashed password
• play:		Play a tune
• probe:		Retrieve device info
• pxe_unload:		Unload the PXE environment
• read:		Read user input
• reboot:		Reboot your computer
• regexp:		Test if regular expression matches string
• rmmod:		Remove a module
• save_env:		Save variables to environment block
• search:		Search devices by file, label, or UUID
• sendkey:		Emulate keystrokes
• set:		Set an environment variable
• sha1sum:		Compute or check SHA1 hash
• sha256sum:		Compute or check SHA256 hash
• sha512sum:		Compute or check SHA512 hash
• sleep:		Wait for a specified number of seconds
• source:		Read a configuration file in same context
• test:		Check file types and compare values
• true:

• biosnum:
• check_signatures:
• chosen:
• cmdpath:
• color_highlight:
• color_normal:
• debug:
• default:
• fallback:
• gfxmode:
• gfxpayload:
• gfxterm_font:
• grub_cpu:
• grub_platform:
• icondir:
• lang:
• locale_dir:
• menu_color_highlight:
• menu_color_normal:
• net_`<interface>`_boot_file:
• net_`<interface>`_dhcp_server_name:
• net_`<interface>`_domain:
• net_`<interface>`_extensionspath:
• net_`<interface>`_hostname:
• net_`<interface>`_ip:
• net_`<interface>`_mac:
• net_`<interface>`_rootpath:
• net_default_interface:
• net_default_ip:
• net_default_mac:
• net_default_server:
• pager:
• prefix:
• pxe_blksize:
• pxe_default_gateway:
• pxe_default_server:
• root:
• superusers:
• theme:
• timeout:
• timeout_style:

• Menu-specific commands:
• General commands:
• Command-line and menu entry commands:
• Networking commands:

• menuentry:		Start a menu entry
• submenu:		Group menu entries

• serial:		Set up a serial device
• terminal_input:		Manage input terminals
• terminal_output:		Manage output terminals
• terminfo:		Define terminal type

• Device syntax:		How to specify devices
• File name syntax:		How to specify files
• Block list syntax:		How to specify block lists

• Command-line interface:		The flexible command-line interface
• Menu interface:		The simple menu interface
• Menu entry editor:		Editing a menu entry

7 Theme file format

7.1 Introduction

7.2 Theme Elements

7.2.1 Colors

7.2.2 Fonts

7.2.3 Progress Bar

7.2.4 Circular Progress Indicator

7.2.5 Labels

7.2.6 Boot Menu

7.2.7 Styled Boxes

7.2.8 Creating Styled Box Images

7.3 Theme File Manual

7.3.1 Global Properties

7.3.2 Format

7.3.3 Global Property List

7.3.4 Component Construction

7.3.5 Component List

7.3.6 Common properties

8 Booting GRUB from the network

9 Using GRUB via a serial line

10 Using GRUB with vendor power-on keys

11 GRUB image files

For GRUB Legacy users

12 Core image size limitation

13 Filesystem syntax and semantics

13.1 How to specify devices

13.2 How to specify files

13.3 How to specify block lists

14 GRUB’s user interface

14.1 The flexible command-line interface

14.2 The simple menu interface

14.3 Editing a menu entry

15 GRUB environment variables

15.1 Special environment variables

15.1.1 biosnum

15.1.2 check_signatures

15.1.3 chosen

15.1.4 cmdpath

15.1.5 color_highlight

15.1.6 color_normal

15.1.7 debug

15.1.8 default

15.1.9 fallback

15.1.10 gfxmode

15.1.11 gfxpayload

15.1.12 gfxterm_font

15.1.13 grub_cpu

15.1.14 grub_platform

15.1.15 icondir

15.1.16 lang

15.1.17 locale_dir

15.1.18 menu_color_highlight

15.1.19 menu_color_normal

15.1.20 net_<interface>_boot_file

15.1.21 net_<interface>_dhcp_server_name

15.1.22 net_<interface>_domain

15.1.23 net_<interface>_extensionspath

15.1.24 net_<interface>_hostname

15.1.25 net_<interface>_ip

15.1.26 net_<interface>_mac

15.1.27 net_<interface>_rootpath

15.1.28 net_default_interface

15.1.29 net_default_ip

15.1.30 net_default_mac

15.1.31 net_default_server

15.1.32 pager

15.1.33 prefix

15.1.34 pxe_blksize

15.1.35 pxe_default_gateway

15.1.36 pxe_default_server

15.1.37 root

15.1.38 superusers

15.1.39 theme

15.1.40 timeout

15.1.41 timeout_style

15.2 The GRUB environment block

16 The list of available commands

16.1 The list of commands for the menu only

16.1.1 menuentry

16.1.2 submenu

15.1.20 net_`<interface>`_boot_file

15.1.21 net_`<interface>`_dhcp_server_name

15.1.22 net_`<interface>`_domain

15.1.23 net_`<interface>`_extensionspath

15.1.24 net_`<interface>`_hostname

15.1.25 net_`<interface>`_ip

15.1.26 net_`<interface>`_mac

15.1.27 net_`<interface>`_rootpath