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

  1. GNU GRUB 2 Manual
  • GNU GRUB 2
    1. Copyright and License
    2. Authors
    3. Introduction to GRUB 2
      1. I'm Feeling Lucky
      2. I'm A Developer
      3. I'm a User
      4. Work In Progress
      5. Project Resources
    4. Installation
      1. Considering Installation
      2. Differences From GRUB 1
      3. Caveats
      4. Installation via Package Management
      5. Building / Installation from Source
      6. Build Prerequisites
      7. Building
    5. Configuration
      1. /boot/grub, and the volatility thereof
      2. Special Configuration Items
    6. Utilities
    7. The Write
      1. Special Write Targets
    8. Pre-Boot
    9. Re/Booting
      1. Menu Usage and Editing
      2. Using the Command Shell
        1. grub>
        2. grub-rescue>
        3. Lua Shell
    10. Panic!
      1. Machine sees drive, but nothing loads
      2. Boots an OS but GRUB was never seen
      3. Stops at `grub>`
      4. Menu failures / Stanza Problems
      5. Nothing Works
      6. Restore Windows boot-menu entry
    11. Contributors
    12. Comments / Suggestions / Apocrypha

    • 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:

    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

    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:

    Caveats

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

    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

    Building

    To build:

    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:

    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.

    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.

    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.

    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

    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.

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

    Some commands you wish were there, but aren't:

    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.

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

    Cause(s):

    Solution(s):

    Boots an OS but GRUB was never seen

    Symptom(s):

    Cause(s):

    Solution(s):

    Stops at `grub>`

    Symptom(s):

    Cause(s):

    Solution(s):

    Menu failures / Stanza Problems

    Symptom(s):

    Cause(s):

    Solution(s):

    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.

    GrubWiki: Manual (last edited 2010-01-21 05:00:34 by TAYLOR)