GNU GRUB 2 Manual
GNU GRUB 2
Copyright and License
This manual is for GNU GRUB 2 (version 142, 20091230), a software system for booting computers flexibly. This work is (c) Copyright 2008, 2009, 2010 Free Software Foundation, Inc. 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, with the Front-Cover Texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is available at [http://www.gnu.org/licenses/fdl.html GNU FDL]. (a) The FSF’s Back-Cover Text is: “You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom." Published by the Free Software Foundation 51 Franklin St, Fifth Floor Boston, MA 02110-1301 USA
Authors
Authorship is listed according to the info log for the page at GRUB Manual info. The authors are referred collectively herein as "GRUB Document Contributors". Your contributions are valuable. Please contribute, and list your name in the Contributors section. All contributions presume perpetual assignment of ownership and copyright to the FSF, Inc.
Contents
Introduction to GRUB 2
GRUB 2 is a bootloader, and the related utilities that configure and write it. Although there are variations, a bootloader works like this: If GRUB 2 is the first thing your computer runs when it is turned on or rebooted, it allows you to make choices about what to do next, like load an operating system (from all the OSes available) from disk or over the network. This contrasts with a very common boot method, whereby the computer is directed by a simpler bootloader to only load one OS, without offering choices about what OS to use and/or how to boot it. Many versions of proprietary operating systems boot this way, and their users may never be aware a bootloader was a necessary part of the process that makes their OS available after power on or reboot.
GRUB would likely benefit system users who desire greater control over the boot process via activities such as:
- keeping multiple operating systems installed and choosing to use one at boot time
- this includes ability to boot a proprietary OS
- password protection at boot
- invocation of other bootloaders, such as encrypting bootloaders
- altering drive mapping at boot
This manual is targeted to users of GRUB. Moreover, this manual is really for GRUB 2 (version 1.x). The previous version, GRUB 1, is now called GRUB legacy (version 0.x), is described at GRUB 1 Manual. Some items here will likely duplicate (briefly) items on the GRUB Wiki, in the event this manual is read from a source that is different than the original Wiki page (i.e. a pdf).
If you're reading this because something bad happened, please see the Panic! section at the end.
Scary commands that commit writes to disk/partition headers (i.e. can render a system more/less bootable) or actions that are not immediately reversible are tagged by a
. This should be interpreted as a prompt to read the Pre-Boot Checklist.
I'm Feeling Lucky
This responds to "I don't want to read the whole manual, I've been warned, I just want to be reminded of the one command I should run to write GRUB 2 to my hard drive."
That command is grub-install
.
When "I want to be reminded of the one command I should run after updating my kernel"
That command is update-grub
.
I'm A Developer
Developers should definitely consult the GRUB Wiki.
I'm a User
Then read on...
Work In Progress
Some items will seem incomplete, while others have more detail than a user manual needs. Over time, some items will be migrated to better places on the Wiki (or the reverse). The spirit of Wiki prevails here. Your help is important and appreciated. Please don't hesitate to add/change/remove anything that makes this manual helpful to GRUB 2 users. See Contributors.
Project Resources
The GRUB 2 main project web page is hosted at GNU GRUB, which also hosts GRUB legacy.
The development mailing list is at grub-devel.
- Source Code
bzr repo - http://bzr.savannah.gnu.org/r/grub/trunk/grub/ is the canonical place for source.
git - Git repo is at GRUB 2 Git.
svn (superceded by bzr) - The subversion repos were at GRUB svn but have been shut down.
Installation
Note the term 'installation' can mean two things. Installation of the grub software onto a host (to allow preparation and configuration of the bootloader), and installation of a bootloader onto a target ( placing the loader at the start of a disk/partition to make GRUB really work when the machine boots). To help differentiate these, the term 'write' will be used when possible to describe the second kind of installation.
Considering Installation
GRUB 1 works great for most things, and will for some time to come. This version is called GRUB 2 because you should think twice about upgrading (because it's in development), and twice about rebooting (because it has a new config system).
(2009 Spring) GRUB 2 is currently in a state of high developmental flux (from a production user perspective). Testing is occurring for various platforms, new platform support is being added, bugs are being fixed. Meanwhile, major features can be (and are) added at anytime. Moreover, downstream distro maintainers are adapting package management installation and upgrade scripts to deal with GRUB 2 installations and GRUB 1 to GRUB 2 upgrades. For example, an entirely new scripting subsystem was recently added (Lua) to the svn repo, while many distros are still shipping packages from many months back in their repositories. They all have the same version number, 1.96. It's not an indictment of either the speed of updates or volatility of development, merely an indication of the wide variance of the state of the GRUB 2 beta software as it propagates downstream (and the ability of GRUB 2's new architecture to accomodate such development).
As of right now, installation of GRUB 2, and upgrades of related items that trigger GRUB 2 actions (kernel upgrades) can sometimes cause annoying lack of access to certain types of operating system installations (see Caveats). Any lack of access is generally temporary and fixable, so use of GRUB 2 can be characterized as "best experienced from the perspective of evaluating or testing the current state of development on a non-production server."
Differences From GRUB 1
This is not complete. Here is a list of major differences going from GRUB 1 to GRUB 2:
menu.lst no longer controls the menu.
- 'grub.cfg` is now in control of the menu.
grub.cfg is automatically generated by one of the GRUB 2 scripts.
- The partition numbering is different.
Stanzas are phrased slightly differently and can't be copied directly from a GRUB 1 menu.lst to grub.cfg. They are pretty close and easy to change, though.
Caveats
automated kernel upgrades - may have a post-install script that triggers a GRUB 2 configuration/installation session. Do a Pre-Boot checklist before you reboot.
lvm root - detection of existing LVM should be checked before overwriting a bootloader or the menu it wants to find.
lvm+crypto root - ditto.
UUID entries - Test these first. They are automatically generated by some grub.d scripts. Sometimes they don't work.
deb upgrades - In the Debian 5.x and Ubuntu 9.x series, upgrading to GRUB 2 after an an LVM/LVM+crypto installation (under GRUB legacy) will leave you unhappy.
i386 vs. x86_64 - the bootloaders (target) are always built with 32-bit libs (with perhaps some real mode asm to start), even on x86_64 hosted builds. The bootloader images will build according to the target specified in the makefile, while the utilities will build according to the host. It's not really a caveat, unless your compile isn't working on 64-bit, although it should.
Therefore, it may actually be desirable to manually make some additional entry to the menu, then test it, knowing it could/would be overwritten later.
Installation via Package Management
This method is listed first because some users may apt-get/yum install grub-pc and skip the next section. Over time, it will likely become the most popular installation method for GRUB 2 when it becomes production quality.
However, N.B.:
- Your package manager may want to remove GRUB when upgrading to GRUB 2.
Your package manager may add a number of GRUB 2 files into /boot when upgrading from GRUB.
- Your package manager may/not install a bootloader by default when installing GRUB 2.
Your package manager may (will) make some assumption about where the /boot configuration files do/will/were go.
If there's a single /boot, and separate installations of GRUB on different partitions that all point to it, wierd things will happen if you don't keep track of what's going on.
- Some bizarre combination of the above.
Building / Installation from Source
Installing GRUB 2 is as simple as a few commands. There are as few external dependencies as reasonably (but not minimally) necessary. Bootloaders don't generally have the luxury of dynamic libraries, unless you count GRUB 2 modules as such, or a shell...all these ship and compile with the GRUB 2 source (...but then is it really a whole OS when you just wanted to it boot an OS?....that's another conversation, but a quick answer is 'no', compared to what's about to be loaded).
Build Prerequisites
- autoconf (likely required when source was obtained via bzr or git)
- bison
- GNU C compiler for your host and target (usually you're ok here)
- ruby
Building
To build:
obtain the sources (get a version >1.0) from ftp://alpha.gnu.org/gnu/grub/ (or http://alpha.gnu.org/gnu/grub/),
extract to a directory (perhaps with something like tar -C /usr/src -xzvf grub-1*),
cd into the top level of this extracted directory,
prepare for the build by running ./autogen.sh,
configure the build using ./configure,
compile make (takes less than 1 minute on a multicore x86_64)
then make install (only make install requires you to be a superuser).
N.B.: The bootloader is not ready for use. Do not reboot yet. The make install copied utilities to their final places on the host, not a bootloader on a target disk header. BTW, If you are running on x86_64 when you build, you're now an embedded developer, in some sense, as a partial cross-build is performed. The bootloader images will build according to the target specified in the makefile, while the utilities will build according to the host.
Configuration
Before you edit some file/entry in /boot/grub that mysteriously disappears, please read on a minute...
The configuration resides (generally) in three places:
in /etc/default/grub - where a set of general configuration options reside, created by grub-set-default, that you may not want to change much.
in /etc/grub.d - where a set of sh scripts are sequentially used to do useful things that generate the actual bootloader's config file, much like init scripts.
in /boot/grub - where the bootloader itself looks for configuration ( /boot/grub/grub.conf ). This file is written from the /etc/grub.d files, so changes here will be overwritten by some commands.
Debian configuration file: /etc/default/grub
Configuration for GRUB 2 is much different than the original GRUB. Noticeably, the start of partition numbering has changed (like the version numbering, GRUB is always off-by-one somewhere
). (todo: maybe someone can write a GRUB 1 to GRUB 2 converter, for the people who already have GRUB Legacy installed?)
A multistep configuration creation process (i.e. a configuration for creating the configuration) might seem convoluted. The notion is that the /boot partition can be stripped down to what's only required after testing, while the GRUB 2 package ships with as much utility as possible in /bin and /etc to create the testable /boot full of menu-fied modular fun. An embedded developer (on the other 9 or so GRUB arch targets) might notice this separation, but it just so happens on x86 (arch number 10: everybody's PC) that both the target config, /boot/grub (in the embedded sense), and the host configuration, /etc-files (that build it), are on the same PC, the same disk, and maybe the same partition. As much work as possible is put into the utilities and configuration that happen before the reboot, because very little may be available after (re)boot.
/boot/grub, and the volatility thereof
This directory is a bridge over the netherworld of a reboot. It is a target for the utilities, and then a source for the bootloader. In keeping with the carefulness of the utilities, the contents of this directory are subject to any changes required to ensure bootability. This is punctuated a bit by the fact that a user can now delete all of /boot/grub (or at least move it aside), and all the necessary ingredients (modules,etc.) will be detected, built, and written there by a run of grub-install (as well as a write of an image to the bootable location for appropriate architectures). This procedure isn't a bad way to check what grub is seeing. Note that a missing /boot/grub can/will create serious problems on mainstream architectures in re/boot.
The grub.d scripts are designed to automate creating a menu, like finding existing operating systems, creating menu entries for them, theming the menu, and adding a memtest86 entry. Edits should be performed carefully enough that duplicate entries are not created (which work fine, but may annoy you).
Be careful when declaring where the GRUB 2 bootloader shall be installed. For now, many GRUB 2 installations will be on systems with GRUB legacy installed. It is easily possible to overwrite the GRUB legacy bootloader, and/or overwrite the /boot/grub targets. It's even possible to have the (different) bootloaders point to each other's /boot/grub, across partitions, have menu.conf and/or grub.cfg end up in either (or both) /boot, have them create entries for each other, chain load each other, etc. Fortunately, all these combinations are known to work (at least to me, but it took a while to sort out).
Also, when using GRUB 2 after booting from a live CD, notice that /boot may not be especially writable. You must adjust.
Special Configuration Items
Until a better title for this section comes along, this is it. Certain items embed configuration information in a non-obvious way (by design necessity),and are described here. These descriptions may become advanced enough to move into a developer section, but they do assist with user understanding.
device.map
grub-install:device_map=${grubdir}/device.map
grub-mkconfig:if test -e ${grub_prefix}/device.map ; then : ; else
include/grub/util/misc.h:#define DEFAULT_DEVICE_MAP DEFAULT_DIRECTORY "/device.map"
.img files
These images (core.img, multiboot.img) contain configuration in the sense that they are specially built based on the requirements of the target configuration. The main job of these files is to be small enough to load something else, and that's about it. Because of size constraints, the internal configuration can be opaque. Users must depend on the configurations fed to the utilities that generate these images to inferwhat they will try to do on reboot. This is one reason that Pre-Boot checking is important, as a misconfiguration here won't allow the grub menu or shell to be accessedat all. Thus, the utilities that generate these are carefully designed (at least by default) to avoid creating images that point to truly unbootable situations.
.lst files
Helper files in/boot.
A typical set on an i386 PC includes command.lst fs.lst handler.lst moddep.lst partmap.lst parttool.lst
moddep.lst
Describes what modules need to be pulled in to support each module. For example, the entry "lua: setjmp" indicates the lua module needs the setjmp module.
Utilities
These are what are used to get things done before a boot/reboot. There are also some sub-utilities that are called by the scripts. these culminate in a master script, grub-install that is the preferred single method to do all the work involved in successfully writing a bootable image to a bootable device.
grub-probe
- You tell it where to look, what modules to use for looking with, and it tells you what it can see there.
grub-mkconfig
A script to generate a grub runtime config file, grub.cfg.
grub-probe: error: cannot find a device for /
grub-mkimage
- binary executable that creates .img files use for bootstraps
grub-setup
- Set up images to boot from a GRUB device (e.g. (hd0,1)).
grub-install
- A script that performs the main sequence of commands involved in making a system bootable, creating files when necessary
- Performs some basic sanity checks to ensure the sequence could complete successfully
check if grub-setup, grub-mkimage and grub-mkdevicemap dry-run successfully
creates a grub dir if not present, and populate it
- creates a device map if not present
Invoke grub-probe (using modules in /boot/grub) to generate core.img (according to --root-directory=)
detect fs on write target (install_device).
- detect partition map on write target
- detect other fs-type abstractions (lvm, raid, related UUIDs) on write target
- use a BIOSdisk probe setting, if necessary.
grub-mkimage is run with these detections to create core.img (i386)or multiboot.img (other archs)
(i386 only) it invokes grub-setup, which does a write to a bootable sector
grub-emu
There may be some variance in the utilities that are in your version. Some examples are below.
file `dpkg -L grub-pc | grep bin` (grub-pc 1.96+20080512-1ubuntu2 )
/usr/bin/grub-mkimage: ELF 64-bit LSB executable /usr/bin/grub-mkrescue: POSIX shell script text executable /usr/sbin/grub-setup: ELF 64-bit LSB executable /usr/sbin/grub-set-default: POSIX shell script text executable /usr/sbin/grub-emu: ELF 64-bit LSB executable /usr/sbin/update-grub2: POSIX shell script text executable /usr/sbin/grub-install: POSIX shell script text executable /usr/sbin/update-grub: POSIX shell script text executable /usr/sbin/upgrade-from-grub-legacy: Bourne-Again shell script text executable
find /usr/local -type f -executable -print (grub2-1.96+20080512 compile/install)
/usr/local/sbin/grub-dumpbios: POSIX shell script text executable /usr/local/sbin/grub-mkconfig: POSIX shell script text executable /usr/local/sbin/grub-install: POSIX shell script text executable /usr/local/sbin/grub-probe: ELF 64-bit LSB executable, x86-64, /usr/local/sbin/grub-mkdevicemap: ELF 64-bit LSB executable, x86-64, /usr/local/sbin/grub-setup: ELF 64-bit LSB executable, x86-64, /usr/local/bin/grub-mkrescue: POSIX shell script text executable /usr/local/bin/grub-editenv: ELF 64-bit LSB executable, x86-64, /usr/local/bin/grub-mkelfimage: ELF 64-bit LSB executable, x86-64, /usr/local/bin/grub-mkimage: ELF 64-bit LSB executable, x86-64,
The Write
After GRUB 2 is constructed, you need to install it (write the bootloader somewhere useful) to get any effect. You can do this by running the grub-install
command. It will make a default choice for you. Make sure you're happy with it (see Pre-Boot).
Special Write Targets
- Write grub to USB drive
The example command # grub-install --root-directory=~/usbdrive/ /dev/sdb installs to a USB drive enumerated at sdb, and which was also mounted at usbdrive. It was taken from UseCases/Ubuntu.
Pre-Boot
At this point, it is assumed a bootloader install was attempted by some command. Therefore, some final checks can be done before actually rebooting. This section also appears before the Configuration section because Installation via Package Management frequently invokes some kind of bootloader install.
Here are commands to run to ensure the desired result will occur upon reboot. This is written for a disk-based boot.
- Where will the BIOS go first?
- GRUB 2 doesn't know.
OK, well there is the BIOS_Boot_Partition
- but there is this business of swapping disks in GRUB
- What's on the MBR?
Maybe GRUB, GRUB 2, or even TrueCrypt.
- Where does the MBR point to?
- A partition header?
grub-probe -d /dev/yourpartitionN
did you create a fresh device map (that didn't overwrite your favorite [default=/boot/grub/device.map]?)
are you using the fresh device.map?
- which may point to a header yet somewhere else (see above)
- Perhaps a kernel
- is the kernel where the config points?
- Now we're cooking, a little
- Did that automatically-built kernel match that automatically-generated GRUB 2 config that followed?
- There may be a secondary item to be loaded (like an initramfs).
- Will it be loaded?
- Is it any good? (not a GRUB 2 problem, but mentioned for completeness)
- is the kernel where the config points?
- A partition header?
Where's the /boot?
- May not be same place as anything else (last os, initramfs, its own partition)
- I.e. last chance to ensure the menu config you just used to check all the above is the same one GRUB will see.
Use grub-emu. Perhaps a little bit about when/if GRUB 2 cares about differences between i386 and x86_64 code.
Re/Booting
Think. Think again. Reboot.
Menu Usage and Editing
The menu is pretty much self explanatory. Up-arrow and down-arrow choose a stanza. Enter attempts to boot it. Other keys are available to edit (modify) an entry or drop to the grub shell.
Using the Command Shell
What You Boot Is What You Get. Also note that there are multiple shells/modes available, as indicated by the prompt.
grub>
The sh:grub> prompt indicates the the computer has found grub, and on a PC, that generally means it has found the hard disk. If something is wrong with the menu, it drops to this shell. Although it looks unhelpful to see this, there are a number of commands available to locate, load, and boot a kernel and related files (such as an early userspace).
Here are some commands (regular grub shell, not the cool lua one):
help - a command that annoyingly scrolls all the useful commands past your screen size.
ls / - this command does two things at once. First, it shows you what grub is using for /boot. Second, you see what files are there. Some of these are likely to be kernels and initrd. Hmmm....maybe we can load one of those....
ls - by itself this command is really handy to let you know what devices can be seen by grub's drivers.
cat /grub/grub.cfg - Even though the /boot partition has a /grub/ dir there, grub itself see this as / so this is the path you'll use to see what's in grub. This command lets you see what grub was trying to use. You can permute one of these stanzas into some bootability.
cat /boot/grub/grub.cfg - maybe you don't have a separate boot partition. In that case, you really do use a full path.
linux /vmlinuz<-your_version_here> [root=/dev/<something>] [some_other_kernel_option] [...] will actually load the kernel into RAM. If you see something similar to [Linux-bzImage, setup=0x3000, size=0x3593e0] then grub found the kernel and loaded it. Note the root= item passed here is just a string to grub, it is neither an env var nor the root command.
linux (hd0,2)/boot/vmlinuz-<alternate_version> root=/dev/sda2 is a more complicated example of how to boot a kernel from the second partition.
linux16 /memtest86+.bin 16-bit (b)zImage images such as Memtest86+ require "linux16" rather than "linux"
initrd /initrd-<your_initrd> loads the initrd (if you need one).
boot - as Picard would say, "Engage."
Some commands you wish were there, but aren't:
load - after you declare a kernel image, and try to boot, boot complains about it not being loaded. Well, this command doesn't do anything. Maybe you tried linux=<something>. The = sets a environment variable instead of invoking the linux command, which declares and loads.
env and printenv - if you've entered some items, want to check them, and expect one of these commands to dump the environment to the screen, you'll be disappointed.
less and more - sorry, that menu.lst you cat'ed just scolls on by. You'll be looking at the last two stanzas or so.
grub-rescue>
The grub-rescue> mode is a more restricted subset of the grub> shell. Some commands are phrased differently here for easier use. Try help to start.
Useful tip: try to load normal mode: insmod /boot/grub/normal.mod
After this command help will show normal as possible command. Try it. Normal mode will be loaded. Now try to load ls (insmod /boot/grub/ls.mod), help and so on.
Lua Shell
A Lua alternative script engine is available in grub-extras. Note it is only mentioned here to give direction in the event the user observes the Lua prompt.
lua:grub > is the prompt that indicates this shell is in effect.
Further guidance is available in LUASupport.
Panic!
Step 1: Please do not panic, cry, yell, reinstall, reboot, kill power, etc., ....at least just yet.
A failed bootloader install is an especially frustrating moment that can trigger a hind-brain (medullar) prompt for immediate action. Reading that advice from some online manual that had to be retrieved "from another PC that still works" may not seem like a great start.
Although hard to believe, the good news is that any attempt to install GRUB 2 has likely left the OS intact, and likely in a more flexible situation than before (from a bootloader command perspective), even though one or more operating systems seem to be missing. The technically simplest scenario to fix (an MBR overwrite) looks the scariest, but has not really affected any OS originally on the machine. In these days of GRUB 2, a common worst-case scenario (needing a bootloader from another source) generally (and counterintuitively to the more ancient brain parts) involves using the same installation media that seemed to cause the trouble.
"Falling back" to a previous OS installation disk may not help, or be as helpful. "Going back" may really mean "going forward to get to what was always there". Press on.
Although the manual is not especially meant to be a troubleshooting guide to boot problems, this is where users can end up when something bad happens, and it seems like GRUB 2's fault. Or it's not GRUB 2's fault, the original OS/bootloader flaked out, a rescue disk is being tried that has GRUB 2 on it, and the user came here for more information.
It's arranged according to the stages that happen during boot, and then later when things are changed.
Machine sees drive, but nothing loads
Symptom(s):
- My machine came with another OS installed, I tried to install Linux/HURD/L4, and now it "won't boot at all", aka
- My BIOS can't seem to find an OS on the drive, aka
- My machine can't seem to find a bootloader
Cause(s):
- An early stage loader was written that points to nothing useful. This is rare.
- Menu suppressed and its default choice is erroneous (bizarre).
Solution(s):
- Break into the menu.
- Boot from a LiveCD.
Boots an OS but GRUB was never seen
Symptom(s):
- I'm supposed to see a GRUB menu, but it goes straight into an OS
Cause(s):
- Menu off/suppressed?
- Did an OS on another partition (re)install a bootloader for some reason and overwrite the GRUB 2 boot sector?
Solution(s):
- Try to break into the GRUB menu/shell.
- Boot from a LiveCD.
Stops at `grub>`
Symptom(s):
- All I get is a grub prompt
- Welcome to GRUB!
grub>
grub rescue>
Cause(s):
GRUB 2 could not find a grub.cfg.
The grub.cfg was completely unworkable.
Solution(s):
cat /grub/grub.cfg. If the word 'title' appears anywhere in the stanzas, then someone copied a menu.cfg directly.
Try some grub shell commands to see how the drive looks to GRUB 2, look at the configuration, find some file(s) that will boot.
Menu failures / Stanza Problems
Symptom(s):
- I see a menu, but it just sits there, aka
- A menu appears for a few seconds, it tries to load something, but complains and drops back to the menu.
I briefly see some kind of complaint (such as what) and it kicks me into GRUB
Cause(s):
- The more subtle items, like the caveats above.
- Also end up here when utilities don't guess/create menu entries correctly.
- UUID problems
- path/drive differences between what was seen at write and what is seen now.
Solution(s):
- Use 'e' to edit an entry to something that will boot.
Nothing Works
In case something goes wrong and you may need to install GRUB 2 from a Live CD, instructions can be found here: Grub2LiveCdInstallGuide
Restore Windows boot-menu entry
Sometimes upgrading to grub2 removes your windows partition from the grub menu.
Follow this to get your gaming platform back: ChainLoadWindows
Contributors
The following persons, in alphabetical order, have contributed to this document:
Bruce O. Benson, chernomor, Chris Kandle, Karl Kashofer, Julian Salazar, Vladimir 'φ-coder/phcoder' Serbinenko, Felix Zielcke, and others.
Comments / Suggestions / Apocrypha
Maybe this should actually get started? Just a thought. -- JulianSalazar
Maybe someone should make an autoprobe like anaconda does in fedora for the installer. Anyway, I'll work on this later, once I finish some work. I think that after finishing this work you should write a custom essay or so to let other people know about the results of work.