Translate string into the current language.
The current language code is stored in the ‘lang’ variable in GRUB’s environment (see lang). Translation files in MO format are read from ‘locale_dir’ (see locale_dir), usually /boot/grub/locale.
Next: halt, Previous: gettext, Up: Command-line and menu entry commands [Contents][Index]
Disks using the GUID Partition Table (GPT) also have a legacy Master Boot Record (MBR) partition table for compatibility with the BIOS and with older operating systems. The legacy MBR can only represent a limited subset of GPT partition entries.
This command populates the legacy MBR with the specified partition entries on device. Up to three partitions may be used.
type is an MBR partition type code; prefix with ‘0x’ if you want to enter this in hexadecimal. The separator between partition and type may be ‘+’ to make the partition active, or ‘-’ to make it inactive; only one partition may be active. If both the separator and type are omitted, then the partition will be inactive.
Next: hashsum, Previous: gptsync, Up: Command-line and menu entry commands [Contents][Index]
The command halts the computer. If the --no-apm option is specified, no APM BIOS call is performed. Otherwise, the computer is shut down using APM.
Next: help, Previous: halt, Up: Command-line and menu entry commands [Contents][Index]
Compute or verify file hashes. Hash type is selected with option --hash. Supported hashes are: ‘adler32’, ‘crc64’, ‘crc32’, ‘crc32rfc1510’, ‘crc24rfc2440’, ‘md4’, ‘md5’, ‘ripemd160’, ‘sha1’, ‘sha224’, ‘sha256’, ‘sha512’, ‘sha384’, ‘tiger192’, ‘tiger’, ‘tiger2’, ‘whirlpool’. Option --uncompress uncompresses files before computing hash.
When list of files is given, hash of each file is computed and printed, followed by file name, each file on a new line.
When option --check is given, it points to a file that contains
list of hash name pairs in the same format as used by UNIX
md5sum command. Option --prefix
may be used to give directory where files are located. Hash verification
stops after the first mismatch was found unless option --keep-going
was given. The exit code $? is set to 0 if hash verification
is successful. If it fails, $? is set to a nonzero value.
Next: initrd, Previous: hashsum, Up: Command-line and menu entry commands [Contents][Index]
Display helpful information about builtin commands. If you do not specify pattern, this command shows short descriptions of all available commands.
If you specify any patterns, it displays longer information about each of the commands whose names begin with those patterns.
Next: initrd16, Previous: help, Up: Command-line and menu entry commands [Contents][Index]
Load an initial ramdisk for a Linux kernel image, and set the appropriate
parameters in the Linux setup area in memory. This may only be used after
the linux command (see linux) has been run. See also
GNU/Linux.
Next: insmod, Previous: initrd, Up: Command-line and menu entry commands [Contents][Index]
Load an initial ramdisk for a Linux kernel image to be booted in 16-bit
mode, and set the appropriate parameters in the Linux setup area in memory.
This may only be used after the linux16 command (see linux16)
has been run. See also GNU/Linux.
This command is only available on x86 systems.
Next: keystatus, Previous: initrd16, Up: Command-line and menu entry commands [Contents][Index]
Next: linux, Previous: insmod, Up: Command-line and menu entry commands [Contents][Index]
Return true if the Shift, Control, or Alt modifier keys are held down, as requested by options. This is useful in scripting, to allow some user control over behaviour without having to wait for a keypress.
Checking key modifier status is only supported on some platforms. If invoked
without any options, the keystatus command returns true if and
only if checking key modifier status is supported.
Next: linux16, Previous: keystatus, Up: Command-line and menu entry commands [Contents][Index]
Load a Linux kernel image from file. The rest of the line is passed verbatim as the kernel command-line. Any initrd must be reloaded after using this command (see initrd).
On x86 systems, the kernel will be booted using the 32-bit boot protocol.
Note that this means that the ‘vga=’ boot option will not work; if you
want to set a special video mode, you will need to use GRUB commands such as
‘set gfxpayload=1024x768’ or ‘set gfxpayload=keep’ (to keep the
same mode as used in GRUB) instead. GRUB can automatically detect some uses
of ‘vga=’ and translate them to appropriate settings of
‘gfxpayload’. The linux16 command (see linux16) avoids
this restriction.
Next: list_env, Previous: linux, Up: Command-line and menu entry commands [Contents][Index]
Load a Linux kernel image from file in 16-bit mode. The rest of the line is passed verbatim as the kernel command-line. Any initrd must be reloaded after using this command (see initrd16).
The kernel will be booted using the traditional 16-bit boot protocol. As well as bypassing problems with ‘vga=’ described in linux, this permits booting some other programs that implement the Linux boot protocol for the sake of convenience.
This command is only available on x86 systems.
Next: list_trusted, Previous: linux16, Up: Command-line and menu entry commands [Contents][Index]
List all variables in the environment block file. See Environment block.
The --file option overrides the default location of the environment block.
Next: load_env, Previous: list_env, Up: Command-line and menu entry commands [Contents][Index]
List all public keys trusted by GRUB for validating signatures.
The output is in GPG’s v4 key fingerprint format (i.e., the output of
gpg --fingerprint). The least significant four bytes (last
eight hexadecimal digits) can be used as an argument to
distrust (see distrust).
See Using digital signatures, for more information about uses for
these keys.
Next: loadfont, Previous: list_trusted, Up: Command-line and menu entry commands [Contents][Index]
Load all variables from the environment block file into the environment. See Environment block.
The --file option overrides the default location of the environment block.
The --skip-sig option skips signature checking even when the
value of environment variable check_signatures is set to
enforce (see check_signatures).
If one or more variable names are provided as arguments, they are interpreted as a whitelist of variables to load from the environment block file. Variables set in the file but not present in the whitelist are ignored.
The --skip-sig option should be used with care, and should
always be used in concert with a whitelist of acceptable variables
whose values should be set. Failure to employ a carefully constructed
whitelist could result in reading a malicious value into critical
environment variables from the file, such as setting
check_signatures=no, modifying prefix to boot from an
unexpected location or not at all, etc.
When used with care, --skip-sig and the whitelist enable an administrator to configure a system to boot only signed configurations, but to allow the user to select from among multiple configurations, and to enable “one-shot” boot attempts and “savedefault” behavior. See Using digital signatures, for more information.
Next: loopback, Previous: load_env, Up: Command-line and menu entry commands [Contents][Index]
Load specified font files. Unless absolute pathname is given, file is assumed to be in directory ‘$prefix/fonts’ with suffix ‘.pf2’ appended. See Fonts.
Next: ls, Previous: loadfont, Up: Command-line and menu entry commands [Contents][Index]
Make the device named device correspond to the contents of the filesystem image in file. For example:
loopback loop0 /path/to/image ls (loop0)/
With the -d option, delete a device previously created using this command.
Next: lsfonts, Previous: loopback, Up: Command-line and menu entry commands [Contents][Index]
List devices or files.
With no arguments, print all devices known to GRUB.
If the argument is a device name enclosed in parentheses (see Device syntax), then print the name of the filesystem of that device.
If the argument is a directory given as an absolute file name (see File name syntax), then list the contents of that directory.
Next: lsmod, Previous: ls, Up: Command-line and menu entry commands [Contents][Index]
Next: md5sum, Previous: lsfonts, Up: Command-line and menu entry commands [Contents][Index]
Next: module, Previous: lsmod, Up: Command-line and menu entry commands [Contents][Index]
Alias for hashsum --hash md5 arg …. See command hashsum
(see hashsum) for full description.
Next: multiboot, Previous: md5sum, Up: Command-line and menu entry commands [Contents][Index]
Load a module for multiboot kernel image. The rest of the line is passed verbatim as the module command line.
Next: nativedisk, Previous: module, Up: Command-line and menu entry commands [Contents][Index]
Load a multiboot kernel image from file. The rest of the line is passed verbatim as the kernel command-line. Any module must be reloaded after using this command (see module).
Some kernels have known problems. You need to specify –quirk-* for those. –quirk-bad-kludge is a problem seen in several products that they include loading kludge information with invalid data in ELF file. GRUB prior to 0.97 and some custom builds prefered ELF information while 0.97 and GRUB 2 use kludge. Use this option to ignore kludge. Known affected systems: old Solaris, SkyOS.
–quirk-modules-after-kernel is needed for kernels which load at relatively high address e.g. 16MiB mark and can’t cope with modules stuffed between 1MiB mark and beginning of the kernel. Known afftected systems: VMWare.
Next: normal, Previous: multiboot, Up: Command-line and menu entry commands [Contents][Index]
Switch from firmware disk drivers to native ones. Really useful only on platforms where both firmware and native disk drives are available. Currently i386-pc, i386-efi, i386-ieee1275 and x86_64-efi.
Next: normal_exit, Previous: nativedisk, Up: Command-line and menu entry commands [Contents][Index]
Enter normal mode and display the GRUB menu.
In normal mode, commands, filesystem modules, and cryptography modules are
automatically loaded, and the full GRUB script parser is available. Other
modules may be explicitly loaded using insmod (see insmod).
If a file is given, then commands will be read from that file. Otherwise, they will be read from $prefix/grub.cfg if it exists.
normal may be called from within normal mode, creating a nested
environment. It is more usual to use configfile
(see configfile) for this.
Next: parttool, Previous: normal, Up: Command-line and menu entry commands [Contents][Index]
Exit normal mode (see normal). If this instance of normal mode was not nested within another one, then return to rescue mode.
Next: password, Previous: normal_exit, Up: Command-line and menu entry commands [Contents][Index]
Make various modifications to partition table entries.
Each command is either a boolean option, in which case it must be followed with ‘+’ or ‘-’ (with no intervening space) to enable or disable that option, or else it takes a value in the form ‘command=value’.
Currently, parttool is only useful on DOS partition tables (also
known as Master Boot Record, or MBR). On these partition tables, the
following commands are available:
When enabled, this makes the selected partition be the active (bootable) partition on its disk, clearing the active flag on all other partitions. This command is limited to primary partitions.
Change the type of an existing partition. The value must be a number in the range 0-0xFF (prefix with ‘0x’ to enter it in hexadecimal).
When enabled, this hides the selected partition by setting the hidden bit in its partition type code; when disabled, unhides the selected partition by clearing this bit. This is useful only when booting DOS or Wwindows and multiple primary FAT partitions exist in one disk. See also DOS/Windows.
Next: password_pbkdf2, Previous: parttool, Up: Command-line and menu entry commands [Contents][Index]
Define a user named user with password clear-password. See Security.
Next: play, Previous: password, Up: Command-line and menu entry commands [Contents][Index]
Define a user named user with password hash hashed-password.
Use grub-mkpasswd-pbkdf2 (see Invoking grub-mkpasswd-pbkdf2)
to generate password hashes. See Security.
Next: probe, Previous: password_pbkdf2, Up: Command-line and menu entry commands [Contents][Index]
Plays a tune
If the argument is a file name (see File name syntax), play the tune recorded in it. The file format is first the tempo as an unsigned 32bit little-endian number, then pairs of unsigned 16bit little-endian numbers for pitch and duration pairs.
If the arguments are a series of numbers, play the inline tune.
The tempo is the base for all note durations. 60 gives a 1-second base, 120 gives a half-second base, etc. Pitches are Hz. Set pitch to 0 to produce a rest.
Next: pxe_unload, Previous: play, Up: Command-line and menu entry commands [Contents][Index]
Retrieve device information. If option --set is given, assign result to variable var, otherwise print information on the screen.
Next: read, Previous: probe, Up: Command-line and menu entry commands [Contents][Index]
Unload the PXE environment (see Network).
This command is only available on PC BIOS systems.
Next: reboot, Previous: pxe_unload, Up: Command-line and menu entry commands [Contents][Index]
Read a line of input from the user. If an environment variable var is given, set that environment variable to the line of input that was read, with no terminating newline.
Next: regexp, Previous: read, Up: Command-line and menu entry commands [Contents][Index]
Next: rmmod, Previous: reboot, Up: Command-line and menu entry commands [Contents][Index]
Test if regular expression regexp matches string. Supported regular expressions are POSIX.2 Extended Regular Expressions. If option --set is given, store numberth matched subexpression in variable var. Subexpressions are numbered in order of their opening parentheses starting from ‘1’. number defaults to ‘1’.
Next: save_env, Previous: regexp, Up: Command-line and menu entry commands [Contents][Index]
Next: search, Previous: rmmod, Up: Command-line and menu entry commands [Contents][Index]
Save the named variables from the environment to the environment block file. See Environment block.
The --file option overrides the default location of the environment block.
This command will operate successfully even when environment variable
check_signatures is set to enforce
(see check_signatures), since it writes to disk and does not alter
the behavior of GRUB based on any contents of disk that have been
read. It is possible to modify a digitally signed environment block
file from within GRUB using this command, such that its signature will
no longer be valid on subsequent boots. Care should be taken in such
advanced configurations to avoid rendering the system
unbootable. See Using digital signatures, for more information.
Next: sendkey, Previous: save_env, Up: Command-line and menu entry commands [Contents][Index]
Search devices by file (-f, --file), filesystem label (-l, --label), or filesystem UUID (-u, --fs-uuid).
If the --set option is used, the first device found is set as the value of environment variable var. The default variable is ‘root’.
The --no-floppy option prevents searching floppy devices, which can be slow.
The ‘search.file’, ‘search.fs_label’, and ‘search.fs_uuid’ commands are aliases for ‘search --file’, ‘search --label’, and ‘search --fs-uuid’ respectively.
Next: set, Previous: search, Up: Command-line and menu entry commands [Contents][Index]
Insert keystrokes into the keyboard buffer when booting. Sometimes an operating system or chainloaded boot loader requires particular keys to be pressed: for example, one might need to press a particular key to enter "safe mode", or when chainloading another boot loader one might send keystrokes to it to navigate its menu.
You may provide up to 16 keystrokes (the length of the BIOS keyboard buffer). Keystroke names may be upper-case or lower-case letters, digits, or taken from the following table:
| Name | Key |
|---|---|
| escape | Escape |
| exclam | ! |
| at | @ |
| numbersign | # |
| dollar | $ |
| percent | % |
| caret | ^ |
| ampersand | & |
| asterisk | * |
| parenleft | ( |
| parenright | ) |
| minus | - |
| underscore | _ |
| equal | = |
| plus | + |
| backspace | Backspace |
| tab | Tab |
| bracketleft | [ |
| braceleft | { |
| bracketright | ] |
| braceright | } |
| enter | Enter |
| control | press and release Control |
| semicolon | ; |
| colon | : |
| quote | ’ |
| doublequote | " |
| backquote | ‘ |
| tilde | ~ |
| shift | press and release left Shift |
| backslash | \ |
| bar | | |
| comma | , |
| less | < |
| period | . |
| greater | > |
| slash | / |
| question | ? |
| rshift | press and release right Shift |
| alt | press and release Alt |
| space | space bar |
| capslock | Caps Lock |
| F1 | F1 |
| F2 | F2 |
| F3 | F3 |
| F4 | F4 |
| F5 | F5 |
| F6 | F6 |
| F7 | F7 |
| F8 | F8 |
| F9 | F9 |
| F10 | F10 |
| F11 | F11 |
| F12 | F12 |
| num1 | 1 (numeric keypad) |
| num2 | 2 (numeric keypad) |
| num3 | 3 (numeric keypad) |
| num4 | 4 (numeric keypad) |
| num5 | 5 (numeric keypad) |
| num6 | 6 (numeric keypad) |
| num7 | 7 (numeric keypad) |
| num8 | 8 (numeric keypad) |
| num9 | 9 (numeric keypad) |
| num0 | 0 (numeric keypad) |
| numperiod | . (numeric keypad) |
| numend | End (numeric keypad) |
| numdown | Down (numeric keypad) |
| numpgdown | Page Down (numeric keypad) |
| numleft | Left (numeric keypad) |
| numcenter | 5 with Num Lock inactive (numeric keypad) |
| numright | Right (numeric keypad) |
| numhome | Home (numeric keypad) |
| numup | Up (numeric keypad) |
| numpgup | Page Up (numeric keypad) |
| numinsert | Insert (numeric keypad) |
| numdelete | Delete (numeric keypad) |
| numasterisk | * (numeric keypad) |
| numminus | - (numeric keypad) |
| numplus | + (numeric keypad) |
| numslash | / (numeric keypad) |
| numenter | Enter (numeric keypad) |
| delete | Delete |
| insert | Insert |
| home | Home |
| end | End |
| pgdown | Page Down |
| pgup | Page Up |
| down | Down |
| up | Up |
| left | Left |
| right | Right |
As well as keystrokes, the sendkey command takes various options
that affect the BIOS keyboard status flags. These options take an ‘on’
or ‘off’ parameter, specifying that the corresponding status flag be
set or unset; omitting the option for a given status flag will leave that
flag at its initial state at boot. The --num, --caps,
--scroll, and --insert options emulate setting the
corresponding mode, while the --numkey, --capskey,
--scrollkey, and --insertkey options emulate pressing and
holding the corresponding key. The other status flag options are
self-explanatory.
If the --no-led option is given, the status flag options will have no effect on keyboard LEDs.
If the sendkey command is given multiple times, then only the last
invocation has any effect.
Since sendkey manipulates the BIOS keyboard buffer, it may cause
hangs, reboots, or other misbehaviour on some systems. If the operating
system or boot loader that runs after GRUB uses its own keyboard driver
rather than the BIOS keyboard functions, then sendkey will have no
effect.
This command is only available on PC BIOS systems.
Next: sha1sum, Previous: sendkey, Up: Command-line and menu entry commands [Contents][Index]
Set the environment variable envvar to value. If invoked with no arguments, print all environment variables with their values.
Next: sha256sum, Previous: set, Up: Command-line and menu entry commands [Contents][Index]
Alias for hashsum --hash sha1 arg …. See command hashsum
(see hashsum) for full description.
Next: sha512sum, Previous: sha1sum, Up: Command-line and menu entry commands [Contents][Index]
Alias for hashsum --hash sha256 arg …. See command hashsum
(see hashsum) for full description.
Next: sleep, Previous: sha256sum, Up: Command-line and menu entry commands [Contents][Index]
Alias for hashsum --hash sha512 arg …. See command hashsum
(see hashsum) for full description.
Next: source, Previous: sha512sum, Up: Command-line and menu entry commands [Contents][Index]
Sleep for count seconds. If option --interruptible is given, allow ESC to interrupt sleep. With --verbose show countdown of remaining seconds. Exit code is set to 0 if timeout expired and to 1 if timeout was interrupted by ESC.
Next: test, Previous: sleep, Up: Command-line and menu entry commands [Contents][Index]
Read file as a configuration file, as if its contents had been
incorporated directly into the sourcing file. Unlike configfile
(see configfile), this executes the contents of file without
changing context: any environment variable changes made by the commands in
file will be preserved after source returns, and the menu
will not be shown immediately.
Next: true, Previous: source, Up: Command-line and menu entry commands [Contents][Index]
Evaluate expression and return zero exit status if result is true, non zero status otherwise.
expression is one of:
== string2the strings are equal
!= string2the strings are not equal
< string2string1 is lexicographically less than string2
<= string2string1 is lexicographically less or equal than string2
> string2string1 is lexicographically greater than string2
>= string2string1 is lexicographically greater or equal than string2
-eq integer2integer1 is equal to integer2
-ge integer2integer1 is greater than or equal to integer2
-gt integer2integer1 is greater than integer2
-le integer2integer1 is less than or equal to integer2
-lt integer2integer1 is less than integer2
-ne integer2integer1 is not equal to integer2
-pgt prefixinteger2integer1 is greater than integer2 after stripping off common non-numeric prefix.
-plt prefixinteger2integer1 is less than integer2 after stripping off common non-numeric prefix.
-nt file2file1 is newer than file2 (modification time). Optionally numeric bias may be directly appended to -nt in which case it is added to the first file modification time.
-ot file2file1 is older than file2 (modification time). Optionally numeric bias may be directly appended to -ot in which case it is added to the first file modification time.
-d filefile exists and is a directory
-e filefile exists
-f filefile exists and is not a directory
-s filefile exists and has a size greater than zero
-n stringthe length of string is nonzero
string is equivalent to -n string
-z stringthe length of string is zero
( expression )expression is true
! expressionexpression is false
-a expression2both expression1 and expression2 are true
-o expression2either expression1 or expression2 is true
Next: trust, Previous: test, Up: Command-line and menu entry commands [Contents][Index]
Do nothing, successfully. This is mainly useful in control constructs such
as if and while (see Shell-like scripting).
Next: unset, Previous: true, Up: Command-line and menu entry commands [Contents][Index]
Read public key from pubkey_file and add it to GRUB’s internal
list of trusted public keys. These keys are used to validate digital
signatures when environment variable check_signatures is set to
enforce. Note that if check_signatures is set to
enforce when trust executes, then pubkey_file
must itself be properly signed. The --skip-sig option can be
used to disable signature-checking when reading pubkey_file
itself. It is expected that --skip-sig is useful for testing
and manual booting. See Using digital signatures, for more
information.
Next: uppermem, Previous: trust, Up: Command-line and menu entry commands [Contents][Index]
Next: verify_detached, Previous: unset, Up: Command-line and menu entry commands [Contents][Index]
This command is not yet implemented for GRUB 2, although it is planned.
Next: videoinfo, Previous: uppermem, Up: Command-line and menu entry commands [Contents][Index]
Verifies a GPG-style detached signature, where the signed file is
file, and the signature itself is in file signature_file.
Optionally, a specific public key to use can be specified using
pubkey_file. When environment variable check_signatures
is set to enforce, then pubkey_file must itself be
properly signed by an already-trusted key. An unsigned
pubkey_file can be loaded by specifying --skip-sig.
If pubkey_file is omitted, then public keys from GRUB’s trusted keys
(see list_trusted, see trust, and see distrust) are
tried.
Exit code $? is set to 0 if the signature validates
successfully. If validation fails, it is set to a non-zero value.
See Using digital signatures, for more information.
Previous: verify_detached, Up: Command-line and menu entry commands [Contents][Index]
List available video modes. If resolution is given, show only matching modes.
Previous: Command-line and menu entry commands, Up: Commands [Contents][Index]
| • net_add_addr: | Add a network address | |
| • net_add_dns: | Add a DNS server | |
| • net_add_route: | Add routing entry | |
| • net_bootp: | Perform a bootp autoconfiguration | |
| • net_bootp6: | Perform a DHCPv6 autoconfiguration | |
| • net_del_addr: | Remove IP address from interface | |
| • net_del_dns: | Remove a DNS server | |
| • net_del_route: | Remove a route entry | |
| • net_get_dhcp_option: | Retrieve DHCP options | |
| • net_ipv6_autoconf: | Perform IPv6 autoconfiguration | |
| • net_ls_addr: | List interfaces | |
| • net_ls_cards: | List network cards | |
| • net_ls_dns: | List DNS servers | |
| • net_ls_routes: | List routing entries | |
| • net_nslookup: | Perform a DNS lookup |
Next: net_add_dns, Up: Networking commands [Contents][Index]
Configure additional network interface with address on a network card. address can be either IP in dotted decimal notation, or symbolic name which is resolved using DNS lookup. If successful, this command also adds local link routing entry to the default subnet of address with name interface‘:local’ via interface.
Next: net_add_route, Previous: net_add_addr, Up: Networking commands [Contents][Index]
Resolve server IP address and add to the list of DNS servers used during name lookup.
Next: net_bootp, Previous: net_add_dns, Up: Networking commands [Contents][Index]
Add route to network with address ip as modified by prefix via either local interface or gateway. prefix is optional and defaults to 32 for IPv4 address and 128 for IPv6 address. Route is identified by shortname which can be used to remove it (see net_del_route).
Next: net_bootp6, Previous: net_add_route, Up: Networking commands [Contents][Index]
Perform configuration of card using DHCP protocol. If no card name is specified, try to configure all existing cards. If configuration was successful, interface with name card‘:dhcp’ and configured address is added to card. Additionally the following DHCP options are recognized and processed:
Used to calculate network local routing entry for interface card‘:dhcp’.
Adds default route entry with the name card‘:dhcp:default’ via gateway from DHCP option. Note that only option with single route is accepted.
Adds all servers from option value to the list of servers used during name resolution.
Sets environment variable ‘net_’<card>‘_dhcp_hostname’ (see net_<interface>_hostname) to the value of option.
Sets environment variable ‘net_’<card>‘_dhcp_domain’ (see net_<interface>_domain) to the value of option.
Sets environment variable ‘net_’<card>‘_dhcp_rootpath’ (see net_<interface>_rootpath) to the value of option.
Sets environment variable ‘net_’<card>‘_dhcp_extensionspath’ (see net_<interface>_extensionspath) to the value of option.
Next: net_del_addr, Previous: net_bootp, Up: Networking commands [Contents][Index]
Perform configuration of card using DHCPv6 protocol. If no card name is specified, try to configure all existing cards. If configuration was successful, interface with name card‘:dhcp6’ and configured address is added to card.
Adds all servers from option value to the list of servers used during name resolution.
Next: net_del_dns, Previous: net_bootp6, Up: Networking commands [Contents][Index]
Next: net_del_route, Previous: net_del_addr, Up: Networking commands [Contents][Index]
Next: net_get_dhcp_option, Previous: net_del_dns, Up: Networking commands [Contents][Index]
Next: net_ipv6_autoconf, Previous: net_del_route, Up: Networking commands [Contents][Index]
Request DHCP option number of type via interface. type can be one of ‘string’, ‘number’ or ‘hex’. If option is found, assign its value to variable var. Values of types ‘number’ and ‘hex’ are converted to string representation.
Next: net_ls_addr, Previous: net_get_dhcp_option, Up: Networking commands [Contents][Index]
Perform IPv6 autoconfiguration by adding to the card interface with name card‘:link’ and link local MAC-based address. If no card is specified, perform autoconfiguration for all existing cards.
Next: net_ls_cards, Previous: net_ipv6_autoconf, Up: Networking commands [Contents][Index]
Next: net_ls_dns, Previous: net_ls_addr, Up: Networking commands [Contents][Index]
Next: net_ls_routes, Previous: net_ls_cards, Up: Networking commands [Contents][Index]
Next: net_nslookup, Previous: net_ls_dns, Up: Networking commands [Contents][Index]
Previous: net_ls_routes, Up: Networking commands [Contents][Index]
Resolve address of name using DNS server server. If no server is given, use default list of servers.
GRUB uses UTF-8 internally other than in rendering where some GRUB-specific appropriate representation is used. All text files (including config) are assumed to be encoded in UTF-8.
NTFS, JFS, UDF, HFS+, exFAT, long filenames in FAT, Joliet part of ISO9660 are treated as UTF-16 as per specification. AFS and BFS are read as UTF-8, again according to specification. BtrFS, cpio, tar, squash4, minix, minix2, minix3, ROMFS, ReiserFS, XFS, ext2, ext3, ext4, FAT (short names), RockRidge part of ISO9660, nilfs2, UFS1, UFS2 and ZFS are assumed to be UTF-8. This might be false on systems configured with legacy charset but as long as the charset used is superset of ASCII you should be able to access ASCII-named files. And it’s recommended to configure your system to use UTF-8 to access the filesystem, convmv may help with migration. ISO9660 (plain) filenames are specified as being ASCII or being described with unspecified escape sequences. GRUB assumes that the ISO9660 names are UTF-8 (since any ASCII is valid UTF-8). There are some old CD-ROMs which use CP437 in non-compliant way. You’re still able to access files with names containing only ASCII characters on such filesystems though. You’re also able to access any file if the filesystem contains valid Joliet (UTF-16) or RockRidge (UTF-8). AFFS, SFS and HFS never use unicode and GRUB assumes them to be in Latin1, Latin1 and MacRoman respectively. GRUB handles filesystem case-insensitivity however no attempt is performed at case conversion of international characters so e.g. a file named lowercase greek alpha is treated as different from the one named as uppercase alpha. The filesystems in questions are NTFS (except POSIX namespace), HFS+ (configurable at mkfs time, default insensitive), SFS (configurable at mkfs time, default insensitive), JFS (configurable at mkfs time, default sensitive), HFS, AFFS, FAT, exFAT and ZFS (configurable on per-subvolume basis by property “casesensitivity”, default sensitive). On ZFS subvolumes marked as case insensitive files containing lowercase international characters are inaccessible. Also like all supported filesystems except HFS+ and ZFS (configurable on per-subvolume basis by property “normalization”, default none) GRUB makes no attempt at check of canonical equivalence so a file name u-diaresis is treated as distinct from u+combining diaresis. This however means that in order to access file on HFS+ its name must be specified in normalisation form D. On normalized ZFS subvolumes filenames out of normalisation are inaccessible.
Firmware output console “console” on ARC and IEEE1275 are limited to ASCII.
BIOS firmware console and VGA text are limited to ASCII and some pseudographics.
None of above mentioned is appropriate for displaying international and any unsupported character is replaced with question mark except pseudographics which we attempt to approximate with ASCII.
EFI console on the other hand nominally supports UTF-16 but actual language coverage depends on firmware and may be very limited.
The encoding used on serial can be chosen with terminfo as
either ASCII, UTF-8 or “visual UTF-8”. Last one is against the specification
but results in correct rendering of right-to-left on some readers which don’t
have own bidi implementation.
On emu GRUB checks if charset is UTF-8 and uses it if so and uses ASCII otherwise.
When using gfxterm or gfxmenu GRUB itself is responsible for rendering the text. In this case GRUB is limited by loaded fonts. If fonts contain all required characters then bidirectional text, cursive variants and combining marks other than enclosing, half (e.g. left half tilde or combining overline) and double ones. Ligatures aren’t supported though. This should cover European, Middle Eastern (if you don’t mind lack of lam-alif ligature in Arabic) and East Asian scripts. Notable unsupported scripts are Brahmic family and derived as well as Mongolian, Tifinagh, Korean Jamo (precomposed characters have no problem) and tonal writing (2e5-2e9). GRUB also ignores deprecated (as specified in Unicode) characters (e.g. tags). GRUB also doesn’t handle so called “annotation characters” If you can complete either of two lists or, better, propose a patch to improve rendering, please contact developer team.
Firmware console on BIOS, IEEE1275 and ARC doesn’t allow you to enter non-ASCII characters. EFI specification allows for such but author is unaware of any actual implementations. Serial input is currently limited for latin1 (unlikely to change). Own keyboard implementations (at_keyboard and usb_keyboard) supports any key but work on one-char-per-keystroke. So no dead keys or advanced input method. Also there is no keymap change hotkey. In practice it makes difficult to enter any text using non-Latin alphabet. Moreover all current input consumers are limited to ASCII.
GRUB supports being translated. For this you need to have language *.mo files in $prefix/locale, load gettext module and set “lang” variable.
Regexps work on unicode characters, however no attempt at checking cannonical equivalence has been made. Moreover the classes like [:alpha:] match only ASCII subset.
Currently GRUB always uses YEAR-MONTH-DAY HOUR:MINUTE:SECOND [WEEKDAY] 24-hour
datetime format but weekdays are translated.
GRUB always uses the decimal number format with [0-9] as digits and . as
descimal separator and no group separator.
IEEE1275 aliases are matched case-insensitively except non-ASCII which is
matched as binary. Similar behaviour is for matching OSBundleRequired.
Since IEEE1275 aliases and OSBundleRequired don’t contain any non-ASCII it
should never be a problem in practice.
Case-sensitive identifiers are matched as raw strings, no canonical
equivalence check is performed. Case-insenstive identifiers are matched
as RAW but additionally [a-z] is equivalent to [A-Z]. GRUB-defined
identifiers use only ASCII and so should user-defined ones.
Identifiers containing non-ASCII may work but aren’t supported.
Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and
LF U+000a) are recognised. Other unicode space characters aren’t a valid
field separator.
test (see test) tests <, >, <=, >=, -pgt and -plt compare the strings in the
lexicographical order of unicode codepoints, replicating the behaviour of
test from coreutils.
environment variables and commands are listed in the same order.
Next: Platform limitations, Previous: Internationalisation, Up: Top [Contents][Index]
| • Authentication and authorisation: | Users and access control | |
| • Using digital signatures: | Booting digitally signed code |
Next: Using digital signatures, Up: Security [Contents][Index]
By default, the boot loader interface is accessible to anyone with physical access to the console: anyone can select and edit any menu entry, and anyone can get direct access to a GRUB shell prompt. For most systems, this is reasonable since anyone with direct physical access has a variety of other ways to gain full access, and requiring authentication at the boot loader level would only serve to make it difficult to recover broken systems.
However, in some environments, such as kiosks, it may be appropriate to lock down the boot loader to require authentication before performing certain operations.
The ‘password’ (see password) and ‘password_pbkdf2’
(see password_pbkdf2) commands can be used to define users, each of
which has an associated password. ‘password’ sets the password in
plain text, requiring grub.cfg to be secure; ‘password_pbkdf2’
sets the password hashed using the Password-Based Key Derivation Function
(RFC 2898), requiring the use of grub-mkpasswd-pbkdf2
(see Invoking grub-mkpasswd-pbkdf2) to generate password hashes.
In order to enable authentication support, the ‘superusers’ environment variable must be set to a list of usernames, separated by any of spaces, commas, semicolons, pipes, or ampersands. Superusers are permitted to use the GRUB command line, edit menu entries, and execute any menu entry. If ‘superusers’ is set, then use of the command line is automatically restricted to superusers.
Other users may be given access to specific menu entries by giving a list of usernames (as above) using the --users option to the ‘menuentry’ command (see menuentry). If the --unrestricted option is used for a menu entry, then that entry is unrestricted. If the --users option is not used for a menu entry, then that only superusers are able to use it.
Putting this together, a typical grub.cfg fragment might look like this:
set superusers="root"
password_pbkdf2 root grub.pbkdf2.sha512.10000.biglongstring
password user1 insecure
menuentry "May be run by any user" --unrestricted {
set root=(hd0,1)
linux /vmlinuz
}
menuentry "Superusers only" --users "" {
set root=(hd0,1)
linux /vmlinuz single
}
menuentry "May be run by user1 or a superuser" --users user1 {
set root=(hd0,2)
chainloader +1
}
The grub-mkconfig program does not yet have built-in support for
generating configuration files with authentication. You can use
/etc/grub.d/40_custom to add simple superuser authentication, by
adding set superusers= and password or password_pbkdf2
commands.
Previous: Authentication and authorisation, Up: Security [Contents][Index]
GRUB’s core.img can optionally provide enforcement that all files subsequently read from disk are covered by a valid digital signature. This document does not cover how to ensure that your platform’s firmware (e.g., Coreboot) validates core.img.
If environment variable check_signatures
(see check_signatures) is set to enforce, then every
attempt by the GRUB core.img to load another file foo
implicitly invokes verify_detached foo foo.sig
(see verify_detached). foo.sig must contain a valid
digital signature over the contents of foo, which can be
verified with a public key currently trusted by GRUB
(see list_trusted, see trust, and see distrust). If
validation fails, then file foo cannot be opened. This failure
may halt or otherwise impact the boot process.
GRUB uses GPG-style detached signatures (meaning that a file foo.sig will be produced when file foo is signed), and currently supports the DSA and RSA signing algorithms. A signing key can be generated as follows:
gpg --gen-key
An individual file can be signed as follows:
gpg --detach-sign /path/to/file
For successful validation of all of GRUB’s subcomponents and the
loaded OS kernel, they must all be signed. One way to accomplish this
is the following (after having already produced the desired
grub.cfg file, e.g., by running grub-mkconfig
(see Invoking grub-mkconfig):
# Edit /dev/shm/passphrase.txt to contain your signing key's passphrase
for i in `find /boot -name "*.cfg" -or -name "*.lst" -or \
-name "*.mod" -or -name "vmlinuz*" -or -name "initrd*" -or \
-name "grubenv"`;
do
gpg --batch --detach-sign --passphrase-fd 0 $i < \
/dev/shm/passphrase.txt
done
shred /dev/shm/passphrase.txt
See also: check_signatures, verify_detached, trust, list_trusted, distrust, load_env, save_env.
Note that internally signature enforcement is controlled by setting
the environment variable check_signatures equal to
enforce. Passing one or more --pubkey options to
grub-mkimage implicitly defines check_signatures
equal to enforce in core.img prior to processing any
configuration files.
Note that signature checking does not prevent an attacker with (serial, physical, ...) console access from dropping manually to the GRUB console and executing:
set check_signatures=no
To prevent this, password-protection (see Authentication and authorisation) is essential. Note that even with GRUB password protection, GRUB itself cannot prevent someone with physical access to the machine from altering that machine’s firmware (e.g., Coreboot or BIOS) configuration to cause the machine to boot from a different (attacker-controlled) device. GRUB is at best only one link in a secure boot chain.
Next: Platform-specific operations, Previous: Security, Up: Top [Contents][Index]
GRUB2 is designed to be portable and is actually ported across platforms. We try to keep all platforms at the level. Unfortunately some platforms are better supported than others. This is detailed in current and 2 following sections.
ARC platform is unable to change datetime (firmware doesn’t seem to provide a function for it). EMU has similar limitation.
On EMU platform no serial port is available.
Console charset refers only to firmware-assisted console. gfxterm is always Unicode (see Internationalisation section for its limitations). Serial is configurable to UTF-8 or ASCII (see Internationalisation). In case of qemu and coreboot ports the refered console is vga_text. Loongson always uses gfxterm.
Most limited one is ASCII. CP437 provides additionally pseudographics. GRUB2 doesn’t use any language characters from CP437 as often CP437 is replaced by national encoding compatible only in pseudographics. Unicode is the most versatile charset which supports many languages. However the actual console may be much more limited depending on firmware
On BIOS network is supported only if the image is loaded through network. On sparc64 GRUB is unable to determine which server it was booted from.
Direct ATA/AHCI support allows to circumvent various firmware limitations but isn’t needed for normal operation except on baremetal ports.
AT keyboard support allows keyboard layout remapping and support for keys not available through firmware. It isn’t needed for normal operation except baremetal ports.
Speaker allows morse and spkmodem communication.
USB support provides benefits similar to ATA (for USB disks) or AT (for USB keyboards). In addition it allows USBserial.
Chainloading refers to the ability to load another bootloader through the same protocol
Hints allow faster disk discovery by already knowing in advance which is the disk in question. On some platforms hints are correct unless you move the disk between boots. On other platforms it’s just an educated guess. Note that hint failure results in just reduced performance, not a failure
BadRAM is the ability to mark some of the RAM as “bad”. Note: due to protocol limitations mips-loongson (with Linux protocol) and mips-qemu_mips can use only memory up to first hole.
| BIOS | Coreboot | Multiboot | Qemu | |
| video | yes | yes | yes | yes |
| console charset | CP437 | CP437 | CP437 | CP437 |
| network | yes (*) | no | no | no |
| ATA/AHCI | yes | yes | yes | yes |
| AT keyboard | yes | yes | yes | yes |
| Speaker | yes | yes | yes | yes |
| USB | yes | yes | yes | yes |
| chainloader | local | yes | yes | no |
| cpuid | partial | partial | partial | partial |
| hints | guess | guess | guess | guess |
| PCI | yes | yes | yes | yes |
| badram | yes | yes | yes | yes |
| compression | always | pointless | no | no |
| exit | yes | no | no | no |
| ia32 EFI | amd64 EFI | ia32 IEEE1275 | Itanium | |
| video | yes | yes | no | no |
| console charset | Unicode | Unicode | ASCII | Unicode |
| network | yes | yes | yes | yes |
| ATA/AHCI | yes | yes | yes | no |
| AT keyboard | yes | yes | yes | no |
| Speaker | yes | yes | yes | no |
| USB | yes | yes | yes | no |
| chainloader | local | local | no | local |
| cpuid | partial | partial | partial | no |
| hints | guess | guess | good | guess |
| PCI | yes | yes | yes | no |
| badram | yes | yes | no | yes |
| compression | no | no | no | no |
| exit | yes | yes | yes | yes |
| Loongson | sparc64 | Powerpc | ARC | |
| video | yes | no | yes | no |
| console charset | N/A | ASCII | ASCII | ASCII |
| network | no | yes (*) | yes | no |
| ATA/AHCI | yes | no | no | no |
| AT keyboard | yes | no | no | no |
| Speaker | no | no | no | no |
| USB | yes | no | no | no |
| chainloader | yes | no | no | no |
| cpuid | no | no | no | no |
| hints | good | good | good | no |
| PCI | yes | no | no | no |
| badram | yes (*) | no | no | no |
| compression | configurable | no | no | configurable |
| exit | no | yes | yes | yes |
| MIPS qemu | emu | |
| video | no | yes |
| console charset | CP437 | Unicode (*) |
| network | no | yes |
| ATA/AHCI | yes | no |
| AT keyboard | yes | no |
| Speaker | no | no |
| USB | N/A | yes |
| chainloader | yes | no |
| cpuid | no | no |
| hints | guess | no |
| PCI | no | no |
| badram | yes (*) | no |
| compression | configurable | no |
| exit | no | yes |
Next: Supported kernels, Previous: Platform limitations, Up: Top [Contents][Index]
Some platforms have features which allows to implement some commands useless or not implementable on others.
Quick summary:
Information retrieval:
Workarounds for platform-specific issues:
Advanced operations for power users:
Miscelaneous:
Next: Troubleshooting, Previous: Platform-specific operations, Up: Top [Contents][Index]
X86 support is summarised in the following table. “Yes” means that the kernel works on the given platform, “crashes” means an early kernel crash which we hope will be fixed by concerned kernel developers. “no” means GRUB doesn’t load the given kernel on a given platform. “headless” means that the kernel works but lacks console drivers (you can still use serial or network console). In case of “no” and “crashes” the reason is given in footnote.
| BIOS | Coreboot | |
| BIOS chainloading | yes | no (1) |
| NTLDR | yes | no (1) |
| Plan9 | yes | no (1) |
| Freedos | yes | no (1) |
| FreeBSD bootloader | yes | crashes (1) |
| 32-bit kFreeBSD | yes | crashes (5) |
| 64-bit kFreeBSD | yes | crashes (5) |
| 32-bit kNetBSD | yes | crashes (1) |
| 64-bit kNetBSD | yes | crashes |
| 32-bit kOpenBSD | yes | yes |
| 64-bit kOpenBSD | yes | yes |
| Multiboot | yes | yes |
| Multiboot2 | yes | yes |
| 32-bit Linux (legacy protocol) | yes | no (1) |
| 64-bit Linux (legacy protocol) | yes | no (1) |
| 32-bit Linux (modern protocol) | yes | yes |
| 64-bit Linux (modern protocol) | yes | yes |
| 32-bit XNU | yes | ? |
| 64-bit XNU | yes | ? |
| 32-bit EFI chainloader | no (2) | no (2) |
| 64-bit EFI chainloader | no (2) | no (2) |
| Appleloader | no (2) | no (2) |
| Multiboot | Qemu | |
| BIOS chainloading | no (1) | no (1) |
| NTLDR | no (1) | no (1) |
| Plan9 | no (1) | no (1) |
| FreeDOS | no (1) | no (1) |
| FreeBSD bootloader | crashes (1) | crashes (1) |
| 32-bit kFreeBSD | crashes (5) | crashes (5) |
| 64-bit kFreeBSD | crashes (5) | crashes (5) |
| 32-bit kNetBSD | crashes (1) | crashes (1) |
| 64-bit kNetBSD | yes | yes |
| 32-bit kOpenBSD | yes | yes |
| 64-bit kOpenBSD | yes | yes |
| Multiboot | yes | yes |
| Multiboot2 | yes | yes |
| 32-bit Linux (legacy protocol) | no (1) | no (1) |
| 64-bit Linux (legacy protocol) | no (1) | no (1) |
| 32-bit Linux (modern protocol) | yes | yes |
| 64-bit Linux (modern protocol) | yes | yes |
| 32-bit XNU | ? | ? |
| 64-bit XNU | ? | ? |
| 32-bit EFI chainloader | no (2) | no (2) |
| 64-bit EFI chainloader | no (2) | no (2) |
| Appleloader | no (2) | no (2) |
| ia32 EFI | amd64 EFI | |
| BIOS chainloading | no (1) | no (1) |
| NTLDR | no (1) | no (1) |
| Plan9 | no (1) | no (1) |
| FreeDOS | no (1) | no (1) |
| FreeBSD bootloader | crashes (1) | crashes (1) |
| 32-bit kFreeBSD | headless | headless |
| 64-bit kFreeBSD | headless | headless |
| 32-bit kNetBSD | crashes (1) | crashes (1) |
| 64-bit kNetBSD | yes | yes |
| 32-bit kOpenBSD | headless | headless |
| 64-bit kOpenBSD | headless | headless |
| Multiboot | yes | yes |
| Multiboot2 | yes | yes |
| 32-bit Linux (legacy protocol) | no (1) | no (1) |
| 64-bit Linux (legacy protocol) | no (1) | no (1) |
| 32-bit Linux (modern protocol) | yes | yes |
| 64-bit Linux (modern protocol) | yes | yes |
| 32-bit XNU | yes | yes |
| 64-bit XNU | yes (4) | yes |
| 32-bit EFI chainloader | yes | no (3) |
| 64-bit EFI chainloader | no (3) | yes |
| Appleloader | yes | yes |
| ia32 IEEE1275 | |
| BIOS chainloading | no (1) |
| NTLDR | no (1) |
| Plan9 | no (1) |
| FreeDOS | no (1) |
| FreeBSD bootloader | crashes (1) |
| 32-bit kFreeBSD | crashes (5) |
| 64-bit kFreeBSD | crashes (5) |
| 32-bit kNetBSD | crashes (1) |
| 64-bit kNetBSD | ? |
| 32-bit kOpenBSD | ? |
| 64-bit kOpenBSD | ? |
| Multiboot | ? |
| Multiboot2 | ? |
| 32-bit Linux (legacy protocol) | no (1) |
| 64-bit Linux (legacy protocol) | no (1) |
| 32-bit Linux (modern protocol) | ? |
| 64-bit Linux (modern protocol) | ? |
| 32-bit XNU | ? |
| 64-bit XNU | ? |
| 32-bit EFI chainloader | no (2) |
| 64-bit EFI chainloader | no (2) |
| Appleloader | no (2) |
PowerPC, IA64 and Sparc64 ports support only Linux. MIPS port supports Linux and multiboot2.
As you have seen in previous chapter the support matrix is pretty big and some of the configurations are only rarely used. To ensure the quality bootchecks are available for all x86 targets except EFI chainloader, Appleloader and XNU. All x86 platforms have bootcheck facility except ieee1275. Multiboot, multiboot2, BIOS chainloader, ntldr and freebsd-bootloader boot targets are tested only with a fake kernel images. Only Linux is tested among the payloads using Linux protocols.
Following variables must be defined:
| GRUB_PAYLOADS_DIR | directory containing the required kernels |
| GRUB_CBFSTOOL | cbfstoll from Coreboot package (for coreboot platform only) |
| GRUB_COREBOOT_ROM | empty Coreboot ROM |
| GRUB_QEMU_OPTS | additional options to be supplied to QEMU |
Required files are:
| kfreebsd_env.i386 | 32-bit kFreeBSD device hints |
| kfreebsd.i386 | 32-bit FreeBSD kernel image |
| kfreebsd.x86_64, kfreebsd_env.x86_64 | same from 64-bit kFreeBSD |
| knetbsd.i386 | 32-bit NetBSD kernel image |
| knetbsd.miniroot.i386 | 32-bit kNetBSD miniroot.kmod. |
| knetbsd.x86_64, knetbsd.miniroot.x86_64 | same from 64-bit kNetBSD |
| kopenbsd.i386 | 32-bit OpenBSD kernel bsd.rd image |
| kopenbsd.x86_64 | same from 64-bit kOpenBSD |
| linux.i386 | 32-bit Linux |
| linux.x86_64 | 64-bit Linux |
Next: Invoking grub-install, Previous: Supported kernels, Up: Top [Contents][Index]
| • GRUB only offers a rescue shell: |
Up: Troubleshooting [Contents][Index]
GRUB’s normal start-up procedure involves setting the ‘prefix’
environment variable to a value set in the core image by
grub-install, setting the ‘root’ variable to match, loading
the ‘normal’ module from the prefix, and running the ‘normal’
command (see normal). This command is responsible for reading
/boot/grub/grub.cfg, running the menu, and doing all the useful
things GRUB is supposed to do.
If, instead, you only get a rescue shell, this usually means that GRUB failed to load the ‘normal’ module for some reason. It may be possible to work around this temporarily: for instance, if the reason for the failure is that ‘prefix’ is wrong (perhaps it refers to the wrong device, or perhaps the path to /boot/grub was not correctly made relative to the device), then you can correct this and enter normal mode manually:
# Inspect the current prefix (and other preset variables): set # Find out which devices are available: ls # Set to the correct value, which might be something like this: set prefix=(hd0,1)/grub set root=(hd0,1) insmod normal normal
However, any problem that leaves you in the rescue shell probably means that GRUB was not correctly installed. It may be more useful to try to reinstall it properly using grub-install device (see Invoking grub-install). When doing this, there are a few things to remember:
grub-install to install GRUB
to a partition but GRUB has already been installed in the master boot
record, then the GRUB installation in the partition will be ignored.
Next: Invoking grub-mkconfig, Previous: Troubleshooting, Up: Top [Contents][Index]
The program grub-install generates a GRUB core image using
grub-mkimage and installs it on your system. You must specify the
device name on which you want to install GRUB, like this:
grub-install install_device
The device name install_device is an OS device name or a GRUB device name.
grub-install accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
Install GRUB images under the directory dir/grub/ This option is useful when you want to install GRUB into a separate partition or a removable disk. If this option is not specified then it defaults to /boot, so
grub-install /dev/sda
is equivalent to
grub-install --boot-directory=/boot/ /dev/sda
Here is an example in which you have a separate boot partition which is mounted on /mnt/boot:
grub-install --boot-directory=/mnt/boot /dev/sdb
Recheck the device map, even if /boot/grub/device.map already exists. You should use this option whenever you add/remove a disk into/from your computer.
By default on x86 BIOS systems, grub-install will use some
extra space in the bootloader embedding area for Reed-Solomon
error-correcting codes. This enables GRUB to still boot successfully
if some blocks are corrupted. The exact amount of protection offered
is dependent on available space in the embedding area. R sectors of
redundancy can tolerate up to R/2 corrupted sectors. This
redundancy may be cumbersome if attempting to cryptographically
validate the contents of the bootloader embedding area, or in more
modern systems with GPT-style partition tables (see BIOS installation) where GRUB does not reside in any unpartitioned space
outside of the MBR. Disable the Reed-Solomon codes with this option.
Next: Invoking grub-mkpasswd-pbkdf2, Previous: Invoking grub-install, Up: Top [Contents][Index]
The program grub-mkconfig generates a configuration file for GRUB
(see Simple configuration).
grub-mkconfig -o /boot/grub/grub.cfg
grub-mkconfig accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
Send the generated configuration file to file. The default is to send it to standard output.
Next: Invoking grub-mkrelpath, Previous: Invoking grub-mkconfig, Up: Top [Contents][Index]
The program grub-mkpasswd-pbkdf2 generates password hashes for
GRUB (see Security).
grub-mkpasswd-pbkdf2
grub-mkpasswd-pbkdf2 accepts the following options:
Number of iterations of the underlying pseudo-random function. Defaults to 10000.
Length of the generated hash. Defaults to 64.
Length of the salt. Defaults to 64.
Next: Invoking grub-mkrescue, Previous: Invoking grub-mkpasswd-pbkdf2, Up: Top [Contents][Index]
The program grub-mkrelpath makes a file system path relative to
the root of its containing file system. For instance, if /usr is a
mount point, then:
$ grub-mkrelpath /usr/share/grub/unicode.pf2 ‘/share/grub/unicode.pf2’
This is mainly used internally by other GRUB utilities such as
grub-mkconfig (see Invoking grub-mkconfig), but may
occasionally also be useful for debugging.
grub-mkrelpath accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
Next: Invoking grub-mount, Previous: Invoking grub-mkrelpath, Up: Top [Contents][Index]
The program grub-mkrescue generates a bootable GRUB rescue image
(see Making a GRUB bootable CD-ROM).
grub-mkrescue -o grub.iso
All arguments not explicitly listed as grub-mkrescue options are
passed on directly to xorriso in mkisofs emulation mode.
Options passed to xorriso will normally be interpreted as
mkisofs options; if the option ‘--’ is used, then anything
after that will be interpreted as native xorriso options.
Non-option arguments specify additional source directories. This is commonly used to add extra files to the image:
mkdir -p disk/boot/grub
(add extra files to disk/boot/grub)
grub-mkrescue -o grub.iso disk
grub-mkrescue accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
Save output in file. This "option" is required.
Pre-load the named GRUB modules in the image. Multiple entries in modules should be separated by whitespace (so you will probably need to quote this for your shell).
If generating images for the QEMU or Coreboot platforms, copy the resulting qemu.img or coreboot.elf files respectively to the dir directory as well as including them in the image.
Use file as the xorriso program, rather than the built-in
default.
Use file as the grub-mkimage program, rather than the
built-in default.
Next: Invoking grub-probe, Previous: Invoking grub-mkrescue, Up: Top [Contents][Index]
The program grub-mount performs a read-only mount of any file
system or file system image that GRUB understands, using GRUB’s file system
drivers via FUSE. (It is only available if FUSE development files were
present when GRUB was built.) This has a number of uses:
Using grub-mount is normally as simple as:
grub-mount /dev/sda1 /mnt
grub-mount must be given one or more images and a mount point as
non-option arguments (if it is given more than one image, it will treat them
as a RAID set), and also accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
Mount encrypted devices, prompting for a passphrase if necessary.
Show debugging output for conditions matching string.
Load a ZFS encryption key. If you use ‘prompt’ as the argument,
grub-mount will read a passphrase from the terminal; otherwise, it
will read key material from the specified file.
Set the GRUB root device to device. You do not normally need to set
this; grub-mount will automatically set the root device to the
root of the supplied file system.
If device is just a number, then it will be treated as a partition number within the supplied image. This means that, if you have an image of an entire disk in disk.img, then you can use this command to mount its second partition:
grub-mount -r 2 disk.img mount-point
Print verbose messages.
Next: Invoking grub-script-check, Previous: Invoking grub-mount, Up: Top [Contents][Index]
The program grub-probe probes device information for a given path
or device.
grub-probe --target=fs /boot/grub grub-probe --target=drive --device /dev/sda1
grub-probe must be given a path or device as a non-option
argument, and also accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
If this option is given, then the non-option argument is a system device
name (such as ‘/dev/sda1’), and grub-probe will print
information about that device. If it is not given, then the non-option
argument is a filesystem path (such as ‘/boot/grub’), and
grub-probe will print information about the device containing that
part of the filesystem.
Use file as the device map (see Device map) rather than the default, usually ‘/boot/grub/device.map’.
Print information about the given path or device as defined by target. The available targets and their meanings are:
GRUB filesystem module.
Filesystem Universally Unique Identifier (UUID).
Filesystem label.
GRUB device name.
System device name.
GRUB partition map module.
GRUB abstraction module (e.g. ‘lvm’).
Crypto device UUID.
MBR partition type code (two hexadecimal digits).
A string of platform search hints suitable for passing to the
search command (see search).
Search hints for the PC BIOS platform.
Search hints for the IEEE1275 platform.
Search hints for platforms where disks are addressed directly rather than via firmware.
Search hints for the EFI platform.
Search hints for the ARC platform.
A guess at a reasonable GRUB drive name for this device, which may be
used as a fallback if the search command fails.
System device name for the whole disk.
Print verbose messages.
Next: Obtaining and Building GRUB, Previous: Invoking grub-probe, Up: Top [Contents][Index]
The program grub-script-check takes a GRUB script file
(see Shell-like scripting) and checks it for syntax errors, similar to
commands such as sh -n. It may take a path as a non-option
argument; if none is supplied, it will read from standard input.
grub-script-check /boot/grub/grub.cfg
grub-script-check accepts the following options:
Print a summary of the command-line options and exit.
Print the version number of GRUB and exit.
Print each line of input after reading it.
Next: Reporting bugs, Previous: Invoking grub-script-check, Up: Top [Contents][Index]
Caution: GRUB requires binutils-2.9.1.0.23 or later because the GNU assembler has been changed so that it can produce real 16bits machine code between 2.9.1 and 2.9.1.0.x. See http://sources.redhat.com/binutils/, to obtain information on how to get the latest version.
GRUB is available from the GNU alpha archive site ftp://ftp.gnu.org/gnu/grub or any of its mirrors. The file will be named grub-version.tar.gz. The current version is 2.02~beta2, so the file you should grab is:
ftp://ftp.gnu.org/gnu/grub/grub-2.02~beta2.tar.gz
To unbundle GRUB use the instruction:
zcat grub-2.02~beta2.tar.gz | tar xvf -
which will create a directory called grub-2.02~beta2 with all the sources. You can look at the file INSTALL for detailed instructions on how to build and install GRUB, but you should be able to just do:
cd grub-2.02~beta2 ./configure make install
Also, the latest version is available using Git. See http://www.gnu.org/software/grub/grub-download.html for more information.
Next: Future, Previous: Obtaining and Building GRUB, Up: Top [Contents][Index]
These are the guideline for how to report bugs. Take a look at this list below before you submit bugs:
The information on your hardware is also essential. These are especially important: the geometries and the partition tables of your hard disk drives and your BIOS.
When you attach a patch, make the patch in unified diff format, and write ChangeLog entries. But, even when you make a patch, don’t forget to explain the problem, so that we can understand what your patch is for.
If you follow the guideline above, submit a report to the Bug Tracking System. Alternatively, you can submit a report via electronic mail to bug-grub@gnu.org, but we strongly recommend that you use the Bug Tracking System, because e-mail can be passed over easily.
Once we get your report, we will try to fix the bugs.
Next: Copying This Manual, Previous: Reporting bugs, Up: Top [Contents][Index]
GRUB 2 is now quite stable and used in many production systems. We are currently working towards a 2.0 release.
If you are interested in the development of GRUB 2, take a look at the homepage.
| • GNU Free Documentation License: | License for copying this manual. |
Up: Copying This Manual [Contents][Index]
Copyright © 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
Previous: Copying This Manual, Up: Top [Contents][Index]
| Jump to: | [
A B C D E F G H I K L M N P R S T U V |
|---|
| Jump to: | [
A B C D E F G H I K L M N P R S T U V |
|---|
chain-load is the mechanism for loading unsupported operating systems by loading another boot loader. It is typically used for loading DOS or Windows.
The NetBSD/i386 kernel is Multiboot-compliant, but lacks support for Multiboot modules.
Only CRC32 data integrity check is supported (xz default is CRC64 so one should use –check=crc32 option). LZMA BCJ filters are supported.
There are a few pathological cases where loading a very badly organized ELF kernel might take longer, but in practice this never happen.
The LInux LOader, a boot loader that everybody uses, but nobody likes.
El Torito is a specification for bootable CD using BIOS functions.
Currently a backslash-newline pair within a variable name is not handled properly, so use this feature with some care.
However, this behavior will be changed in the future version, in a user-invisible way.