Difference between revisions of "GRUB2"

From coreboot
Jump to: navigation, search
(Status)
m (formatting)
 
(131 intermediate revisions by 13 users not shown)
Line 1: Line 1:
'''[http://grub.enbug.org/ GRUB2]''' is a modular, multiboot-capable bootloader for many operating systems that can be used as a payload for coreboot.  
+
'''[https://www.gnu.org/software/grub/grub.html GRUB 2]''' is a modular, multiboot-capable bootloader for many operating systems that can be used as a payload for coreboot.  
  
 
== Status ==
 
== Status ==
 +
GRUB 2 can be launched...
 +
* Directly by coreboot as a payload
 +
* Directly by SeaBIOS as a payload
 +
* By SeaBIOS, on disk, as it would with a normal BIOS.
  
* A significant amount of work has been put into GRUB2 in our [[Monotone Repository|monotone repository]], which also provides snapshots.
+
Recent git versions have improved memory management that removes the memory limitations when run as a payload.
* The mainline version of GRUB2 has a [http://grub.enbug.org/CoreBoot wiki page on the coreboot port].
 
* There is currently no work going on in our GRUB2 repository, not even synchronization to the upstream repository. If you require the additional features of our branch below, go ahead. Otherwise, upstream might serve you better. Or not.
 
  
== How to build GRUB2 as a payload ==
+
== Coreboot-related Features ==
  
It's recommended to use a recent snapshot of the '''allpatches''' branch in the [[Monotone Repository|GRUB2 monotone repository]]
+
Apart from what a typical bootloader supports GRUB implements various features especially helpful in the context of coreboot:
(you can also just download http://coreboot.org/viewmtn/branch/head/tar/org.coreboot.grub2.allpatches - which resolves to the latest revision on that branch; the top level directory in the resulting tarball represents the revision ID, which is a SHA-1 value over revision data, and thus varies wildly).
 
  
$ wget http://coreboot.org/viewmtn/revision/tar/edae9d3e3d999c07b2d8a99f04f258586eb79297 -O grub2.tar
+
* Booting from encrypted LUKS partitions
$ tar xfv grub2.tar
+
* Verifying signatures of files (interesting for initramfs and kernels)
$ cd edae9d3e3d999c07b2d8a99f04f258586eb79297
+
* Printing the contents of [[Cbmem_console|cbmem]] with its <code>cbmemc</code> command
$ sh autogen.sh
+
* Displaying the UI using the coreboot framebuffer
$ ./configure --with-platform=coreboot --prefix=$PWD/installed
+
* Interacting with the nvram/cmos with its <code>cmos*</code> commands
$ chmod 755 mkinstalldirs
+
* Running other coreboot payloads from [[CBFS]] (both compressed and uncompressed)
$ make && make install
 
$ $PWD/installed/bin/grub-mkimage -o core.img normal fat iso9660 pc ata memdisk lar ls cat cmp hello help serial terminal test configfile multiboot boot loopback
 
  
== GRUB2 modules ==
+
See [[#Advanced Features]] for more detailed descriptions and tutorials how to use these.
  
GRUB2 is a modular system, you can include whichever modules you need into the image.
+
== grub.cfg ==
  
In addition to the [http://grub.enbug.org/CommandList full list of available modules in upstream GRUB2] the coreboot version of GRUB2 also adds a few more custom modules.
+
When GRUB is built for coreboot it looks for its runtime configuration in the file <code>etc/grub.cfg</code> within the [[CBFS]].
 +
If this is missing it will provide a limited console only.
  
=== Suggested modules ===
+
The file is an ordinary GRUB configuration file as specified in its [https://www.gnu.org/software/grub/manual/grub.html#Configuration|GRUB's documentation].
 +
It specifies menu entries and allows for quite some scripting.
  
We suggest that you use the following modules:
+
=== Chain-loading another GRUB ===
  
{| border="0" style="font-size: smaller" valign="top"
+
Normally, one would write a custom configuration file that is embedded as described above and completely configures GRUB.
|- bgcolor="#6699dd"
+
However, one could also provide a minimal configuration only and read the remainder from a file system.
! align="left" | Modules
+
This can simply be done by adding something like <code>configfile (ahci0,0)/grub/grub.cfg</code> to the mentioned file.
! align="left" | Reason
+
This would try to load an additional configuration file from the path <code>/grub/grub.cfg</code> of the first partition of the first AHCI device.
  
|- bgcolor="#eeeeee" valign="top"
+
Note however, that this merely reads in the configuration file and '''does not chain-load''' another GRUB instance.
| serial, terminal, terminfo
+
The latter is not feasible unless that other instance is also built with coreboot as target.
| serial console support
+
Ordinary GRUBs however rely on the BIOS interfaces that a coreboot GRUB does not provide.
 +
For such cases running SeaBIOS as payload makes more sense.
  
|- bgcolor="#dddddd" valign="top"
+
=== Most basic config statements ===
| coreboot
 
| change to console automatically
 
  
|- bgcolor="#eeeeee" valign="top"
+
# Printing text
| digest
+
echo 'Hello world!'
| crypto (incl. signature checking)
+
# Play a beep
 +
play 480 440 1
 +
# Paginate GRUB's output. Very useful for long outputs (help texts!) when working interactively
 +
set pager=1
 +
# Timeout in seconds before loading the default entry
 +
set timeout=1
 +
# Set the path root (/) to the 5th parition of the first AHCI (SATA) device
 +
set root='ahci0,msdos5'
  
|- bgcolor="#dddddd" valign="top"
+
Here's an example that creates a menu entry to load a Linux kernel with serial output.
| memdisk, lar or cpio
+
insmod ahci
| filesystem in rom
+
insmod part_msdos
 +
menuentry 'GNU/Linux [Serial]' {
 +
echo 'Loading Linux librepae kernel ...'
 +
linux /vmlinuz-linux-libre-pae root=/dev/sda6 console=ttyS0,115200
 +
echo 'Loading initial ramdisk ...'
 +
initrd /initramfs-linux-libre-pae.img
 +
}
  
|}
+
=== Scanning for grub.cfg on local hard drives ===
  
During development, we used the following list of modules:
+
As mentioned above, chain-loading GRUB is seldom feasible, but loading configuration files from hard disks might work.
 +
The code below creates an entry that searches for a config file in two typical directories on all partitions of the first AHCI device and loads it (or them if there are multiple matches).
  
  coreboot hello cat cmp fat iso9660 help lspci lsusb serial terminal lar terminfo memdisk atadisk ls
+
  menuentry 'Scan for OS on internal HDD' {
configfile boot hexdump digest linux multiboot pc
+
insmod regexp
 +
insmod ahci
 +
insmod part_msdos
 +
for x in (ahci0,*) ; do
 +
if [ -f "$x/grub/grub.cfg" ] ; then
 +
menuentry "Load Config from $x" $x {
 +
root=$2
 +
configfile /grub/grub.cfg
 +
}
 +
fi
 +
if [ -f "$x/boot/grub/grub.cfg" ] ; then
 +
menuentry "Load Config from $x" $x {
 +
root=$2
 +
configfile /boot/grub/grub.cfg
 +
}
 +
fi
 +
done
 +
}
  
=== Modules specific to coreboot ===
+
=== Serial ===
  
The following modules are specific to coreboot, or to the coreboot version of GRUB2:
+
If native graphics initialization is not available one will most likely want to interact with GRUB via a serial connection.
 +
The following subsections show how to enable that in <code>grub.cfg</code>.
  
{| border="0" style="font-size: smaller" valign="top"
+
==== On a real serial port ====
|- bgcolor="#6699dd"
 
! align="left" | Module name
 
! align="left" | Description
 
  
|- bgcolor="#eeeeee" valign="top"
+
To enable serial, add the following on top of your grub.cfg:
| atadisk
 
| ATA disk driver based on the OpenBIOS driver
 
  
|- bgcolor="#dddddd" valign="top"
+
serial --speed=115200 --word=8 --parity=no --stop=1
| coreboot
+
terminal_input --append  serial
| load serial console information from coreboot table
+
terminal_output --append serial
  
|- bgcolor="#eeeeee" valign="top"
+
==== On a USB serial or USB debug adapter ====
| lar
 
| archive format ("filesystem") driver for LAR files (such as coreboot v3 images)
 
  
|- bgcolor="#dddddd" valign="top"
+
To enable serial, first find out the name of your usb serial port trough:
| lsusb
 
| in the .usb branch, provides an uhci driver and usb storage support. highly experimental at this time
 
  
|}
+
insmod nativedisk # needed not to get the disk disapearing when insmoding the *hci
 +
insmod ehci
 +
insmod ohci
 +
insmod uhci
 +
insmod usb
 +
insmod usbserial_pl2303
 +
insmod usbserial_ftdi
 +
insmod usbserial_usbdebug
 +
terminal_output
 +
The terminal_output command should print it:
 +
grub> terminal_output
 +
Active output terminals:
 +
serial_usb1 gfxterm
 +
Available output terminals:
 +
console vga_text serial
 +
Here we can see "serial_usb1" so we now know that its name is usb1
  
=== Building a diskimage ===
+
Then add the following on top of your grub.cfg:
 +
insmod nativedisk
 +
insmod ehci
 +
insmod ohci
 +
insmod uhci
 +
insmod usb
 +
insmod usbserial_pl2303
 +
insmod usbserial_ftdi
 +
insmod usbserial_usbdebug
 +
serial --speed=115200 --word=8 --parity=no --stop=1 usb1
 +
terminal_output --append serial_usb1
 +
terminal_input --append serial_usb1
  
If you are using coreboot v2, the firmware image is not a LAR archive, as in coreboot v3. If you want to place files in the coreboot+grub2 image, you can still create a diskimage and include it in your payload.
+
The following chips/protocols are supported:
 +
* usbdebug
 +
* ftdi
 +
* pl2303
  
# create a lar/cpio/tar file (cpio must be gnu cpio. files created by other cpios might not be compatible)
+
=== Less useful things ===
# add <code>-m lar/cpio-file</code> to your grub-mkimage command line
 
  
Per default GRUB2 looks for a configuration file [http://grub.enbug.org/grub.cfg grub.cfg] in the disk image. The path is
+
(Some of) these might be obsolete by now:
(memdisk)/grub.cfg
 
  
== Checking Signatures ==
+
# Change the path to the GRUB directory so that it can load its modules/commands
 +
set prefix=(memdisk)/boot/grub
  
Currently the tools for crypto signature verification are not built automatically. To build them, run
+
# Add keyboard support
 +
terminal_input --append at_keyboard
  
  $ cd libs/sigtools
+
In case of native graphics you may want the following:
  $ make
+
  gfxpayload=keep
 +
  terminal_output --append gfxterm
  
=== Using sigtools ===
+
=== Chain-loading other Payloads ===
  
Create a key pair filename.pub and filename.sec with
+
Here is how to load another payload.
  
  $ genkeypair filename
+
  menuentry 'SeaBios' {
 +
set root='memdisk'
 +
echo    'Loading SeaBios ...'
 +
chainloader /bios.bin.elf
 +
}
  
Create a signature of candidate using keyfile.sec and save it as candidate.sig:
+
== Compilation ==
 +
=== Setup within coreboot's tree ===
  
$ gensig keyfile candidate
+
The coreboot repository contains a GRUB2 submodule that can directly be selected in coreboot's Kconfig.
 +
Additionally, the config file has to be added, e.g. via the following command.
  
=== Verification in GRUB2 ===
+
  build/cbfstool build/coreboot.rom add -f grub.cfg -n etc/grub.cfg -t raw
  
Load /key.pub as public key and block access to all unsigned files with
+
=== Out of tree compilation ===
  
$ load-pubkey /key.pub
+
In case you want to compile GRUB outside coreboot's directory follow the guide below.
  
Verify foo using the signature foo.sig, reporting success or failure and grant access to the file foo with:
+
Retrieve the source code, compile it and install the resulting utilities:
  
  $ validate /foo /foo.sig
+
  git clone git://git.savannah.gnu.org/grub.git grub
 +
cd grub
 +
./autogen.sh
 +
./configure --with-platform=coreboot
 +
make
 +
sudo make install
  
Example:
+
Create target directories:
 +
mkdir -p memdisk/boot/grub/
  
multiboot grub-invaders # fails
+
Then copy your grub.cfg into it:
  validate grub-invaders grub-invaders.sig
+
  memdisk/boot/grub/grub.cfg
multiboot grub-invaders # this time it succeeds
 
  
== Hints and Tricks ==
+
Then adapt and run the following lines if need be.
  
=== Loading grub.cfg from disk ===
+
rm -f grub2.elf
 +
# Copy the payloads and other required files into the target dir.
 +
cd memdisk
 +
cp ../../seabios/out/bios.bin.elf .
 +
cp ../../coreboot-qemu/payloads/nvramcui/nvramcui.elf .
 +
cp ../../coreboot/payloads/coreinfo/build/coreinfo.elf .
 +
cp ../../memtest86+-4.20/memtest memtest.elf
 +
cp ../../coreboot/bootsplash.jpg  .
 +
grub-mkstandalone -O i386-coreboot -o ../grub2.elf $(find -type f)
  
It is suggested that grub.cfg is contained in a memdisk/lar image. This grub.cfg can be used to load other configuration files from any mass storage media. If you want to load a grub.cfg from the first device that contains one, your in-flash grub.cfg can look like this:
+
The resulting <code>.elf</code> can then be run as payload directly by coreboot or SeaBIOS.
 +
Also, grub2.elf can be tested in qemu.
  
search -f -s /grub.cfg
+
To make it available in SeaBIOS add it to CBFS as follows:
configfile /grub.cfg
 
  
 +
build/cbfstool build/coreboot.rom add-payload -n img/grub2 -f grub2.elf -t raw
  
== To Do ==
+
That way it is possible to run GRUB as a payload after SeaBIOS.
  
* USB stack integration (in progress).
+
Alternatively, the <code>.elf</code> can also be added via Kconfig by setting its path.
* See more information in the "[http://tracker.coreboot.org/trac/coreboot/milestone/Port%20GRUB2%20to%20coreboot Porting GRUB2 to coreboot]" milestone in the coreboot issue tracker.
 
  
== History ==
+
In any case, make sure you have some kinds of output such as VGA or serial (it needs to be activated in both coreboot and GRUB)!
  
[[User:PatrickGeorgi|Patrick Georgi]] has been working on GRUB2 for coreboot during the Google Summer of Code 2007. He made an [http://coreboot.org/~oxygene/lbgrub2-20070820-1.tar.bz2 original code submission] on August 20th 2007. If you care, there is [http://coreboot.org/~oxygene/lbgrub2-instructions.txt documentation on how to use it], but that work is based on a very old version of GRUB2.
+
== Advanced Features ==
 +
=== Security ===
 +
==== Signed kernels ====
 +
GRUB is capable of running only trusted(signed) kernels.
 +
It supports both RSA and DSA gpg keys.
  
For various reasons, Robert Millan of the GRUB project did another original implementation, which got merged, so we moved our effort to their new code base and continued from there.
+
Here's a HOWTO:
  
== How to help? ==
+
First generate a key:
 +
$ gpg --gen-key
 +
gpg (GnuPG) 2.0.19; Copyright (C) 2012 Free Software Foundation, Inc.
 +
This is free software: you are free to change and redistribute it.
 +
There is NO WARRANTY, to the extent permitted by law.
 +
 +
Please select what kind of key you want:
 +
    (1) RSA and RSA (default)
 +
    (2) DSA and Elgamal
 +
    (3) DSA (sign only)
 +
    (4) RSA (sign only)
 +
Your selection? 3
 +
DSA keys may be between 1024 and 3072 bits long.
 +
What keysize do you want? (2048) 3072
 +
Requested keysize is 3072 bits
 +
Please specify how long the key should be valid.
 +
          0 = key does not expire
 +
      <n>  = key expires in n days
 +
      <n>w = key expires in n weeks
 +
      <n>m = key expires in n months
 +
      <n>y = key expires in n years
 +
Key is valid for? (0)
 +
Key does not expire at all
 +
Is this correct? (y/N) y
 +
 +
GnuPG needs to construct a user ID to identify your key.
 +
 +
Real name: Denis 'GNUtoo' Carikli
 +
Email address: GNUtoo@no-log.org
 +
Comment: Kernel signing key
 +
You selected this USER-ID:
 +
    "Denis 'GNUtoo' Carikli (Kernel signing key) <GNUtoo@no-log.org>"
 +
 +
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
 +
You need a Passphrase to protect your secret key.
 +
 +
We need to generate a lot of random bytes. It is a good idea to perform
 +
some other action (type on the keyboard, move the mouse, utilize the
 +
disks) during the prime generation; this gives the random number
 +
generator a better chance to gain enough entropy.
 +
gpg: WARNING: some OpenPGP programs can't handle a DSA key with this digest
 +
size
 +
gpg: key C86D4C64 marked as ultimately trusted
 +
public and secret key created and signed.
 +
 +
gpg: checking the trustdb
 +
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
 +
gpg: depth: 0  valid:  2  signed:  0  trust: 0-, 0q, 0n, 0m, 0f, 2u
 +
pub  3072D/C86D4C64 2013-03-13
 +
      Key fingerprint = 7244 AC33 F9A7 9AE8 30DE  8996 9097 B48D C86D 4C64
 +
uid                  Denis 'GNUtoo' Carikli (Kernel signing key)
 +
<GNUtoo@no-log.org>
 +
 +
Note that this key cannot be used for encryption.  You may want to use
 +
the command "--edit-key" to generate a subkey for this purpose.
 +
Then sign the kernels and initramfs:
 +
cd /boot
 +
sudo -E gpg --detach-sign vmlinuz-linux-libre-pae
 +
sudo -E gpg --detach-sign initramfs-linux-libre-pae.img
  
Contact [mailto:stepan@coresystems.de Stefan Reinauer], [mailto:oxygene@coresystems.de Patrick Georgi] or the [[Mailinglist|coreboot mailing list]] for more information.
+
gpg --export  > boot.key
 +
 +
Then you can put the key on the memdisk (advised) or the boot partition for test purposes only.
 +
Then in GRUB do (for testing purposes):
 +
trust boot.key
 +
set check_signatures=enforce
 +
to only boot correctly signed kernels and initramfs.
 +
 
 +
Then load kernel and initramfs as usual.
 +
 
 +
==== Trisquel, Ubuntu, Debian ====
 +
 
 +
We want automatics hooks to sign our kernel so we don't have to do it manually each time.
 +
 
 +
The following howto was tested on trisquel 6.
 +
Generate the key as root(sudo su) like we just explained, but without a password
 +
In debian based distributions you can hook the kernel build to sign the result:
 +
Add the following to /etc/kernel/postinst.d/yy-update-signatures
 +
#! /bin/sh
 +
set -e
 +
 +
version="$1"
 +
 +
rm -f /boot/vmlinuz-${version}.sig
 +
gpg --detach-sign /boot/vmlinuz-${version}
 +
rm -f /boot/initrd.img-${version}.sig
 +
gpg --detach-sign /boot/initrd.img-${version}
 +
Then do:
 +
chmod +x /etc/kernel/postinst.d/yy-update-signatures
 +
Then do:
 +
gpg --export  > /boot/boot.key
 +
 
 +
Then modify /etc/grub.d/10_linux to use bash instead of sh like that:
 +
#! /bin/bash
 +
And also modify to that:
 +
<pre>
 +
case x`uname -m` in
 +
    xi?86 | xx86_64)
 +
list=`for i in /boot/vmlinuz-* /vmlinuz-* /boot/kernel-* ; do
 +
                  if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
 +
              done` ;;
 +
    *)
 +
list=`for i in /boot/vmlinuz-* /boot/vmlinux-* /vmlinuz-* /vmlinux-* /boot/kernel-* ; do
 +
                  if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
 +
    done` ;;
 +
esac
 +
</pre>
 +
To look like that:
 +
<pre>
 +
case x`uname -m` in
 +
    xi?86 | xx86_64)
 +
list=`for i in /boot/vmlinuz-* /vmlinuz-* /boot/kernel-* ; do
 +
                  if [[ "$i" != /boot/*.sig ]] ; then
 +
                      if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
 +
                  fi
 +
              done` ;;
 +
    *)
 +
list=`for i in /boot/vmlinuz-* /boot/vmlinux-* /vmlinuz-* /vmlinux-* /boot/kernel-* ; do
 +
                  if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
 +
    done` ;;
 +
esac
 +
</pre>
 +
 
 +
==== LUKS ====
 +
 
 +
GRUB is capable of opening LUKS disks like that:
 +
grub> ls
 +
(ata2) (ata2,msdos3) (ata2,msdos2) (ata2,msdos1) (usb0) (usb0,msdos1) (ata6) (memdisk)
 +
grub> cryptomount (ata2,msdos3)
 +
Attempting to decrypt master key...
 +
Enter passphrase for ata2,msdos3 (431439b0870f40a3bfe8f3ca3aa7072a):
 +
Slot 0 opened
 +
grub> ls
 +
(crypto0) (ata2) (ata2,msdos3) (ata2,msdos2) (ata2,msdos1) (usb0) (usb0,msdos1) (ata6) (memdisk)
 +
grub> set root=crypto0
 +
grub> ls /
 +
lost+found/ boot/ var/ dev/ run/ etc/ tmp/ sys/ proc/ usr/ lib/ sbin/ bin/ home/ mnt/ opt/ root/ srv/ media/
 +
 
 +
Note that you have to type the password, so it's better to have some kind of output (VGA, Serial etc...)

Latest revision as of 17:24, 8 January 2017

GRUB 2 is a modular, multiboot-capable bootloader for many operating systems that can be used as a payload for coreboot.

Status

GRUB 2 can be launched...

  • Directly by coreboot as a payload
  • Directly by SeaBIOS as a payload
  • By SeaBIOS, on disk, as it would with a normal BIOS.

Recent git versions have improved memory management that removes the memory limitations when run as a payload.

Coreboot-related Features

Apart from what a typical bootloader supports GRUB implements various features especially helpful in the context of coreboot:

  • Booting from encrypted LUKS partitions
  • Verifying signatures of files (interesting for initramfs and kernels)
  • Printing the contents of cbmem with its cbmemc command
  • Displaying the UI using the coreboot framebuffer
  • Interacting with the nvram/cmos with its cmos* commands
  • Running other coreboot payloads from CBFS (both compressed and uncompressed)

See #Advanced Features for more detailed descriptions and tutorials how to use these.

grub.cfg

When GRUB is built for coreboot it looks for its runtime configuration in the file etc/grub.cfg within the CBFS. If this is missing it will provide a limited console only.

The file is an ordinary GRUB configuration file as specified in its documentation. It specifies menu entries and allows for quite some scripting.

Chain-loading another GRUB

Normally, one would write a custom configuration file that is embedded as described above and completely configures GRUB. However, one could also provide a minimal configuration only and read the remainder from a file system. This can simply be done by adding something like configfile (ahci0,0)/grub/grub.cfg to the mentioned file. This would try to load an additional configuration file from the path /grub/grub.cfg of the first partition of the first AHCI device.

Note however, that this merely reads in the configuration file and does not chain-load another GRUB instance. The latter is not feasible unless that other instance is also built with coreboot as target. Ordinary GRUBs however rely on the BIOS interfaces that a coreboot GRUB does not provide. For such cases running SeaBIOS as payload makes more sense.

Most basic config statements

# Printing text
echo 'Hello world!'
# Play a beep
play 480 440 1
# Paginate GRUB's output. Very useful for long outputs (help texts!) when working interactively
set pager=1
# Timeout in seconds before loading the default entry
set timeout=1
# Set the path root (/) to the 5th parition of the first AHCI (SATA) device
set root='ahci0,msdos5'

Here's an example that creates a menu entry to load a Linux kernel with serial output.

insmod ahci
insmod part_msdos
menuentry 'GNU/Linux [Serial]' {
	echo	'Loading Linux librepae kernel ...'
	linux	/vmlinuz-linux-libre-pae root=/dev/sda6 console=ttyS0,115200
	echo	'Loading initial ramdisk ...'
	initrd	/initramfs-linux-libre-pae.img
}

Scanning for grub.cfg on local hard drives

As mentioned above, chain-loading GRUB is seldom feasible, but loading configuration files from hard disks might work. The code below creates an entry that searches for a config file in two typical directories on all partitions of the first AHCI device and loads it (or them if there are multiple matches).

menuentry 'Scan for OS on internal HDD' {
	insmod regexp
	insmod ahci
	insmod part_msdos
	for x in (ahci0,*) ; do
		if [ -f "$x/grub/grub.cfg" ] ; then
			menuentry "Load Config from $x" $x { 
				root=$2
				configfile /grub/grub.cfg
			}
		fi
		if [ -f "$x/boot/grub/grub.cfg" ] ; then
			menuentry "Load Config from $x" $x {
				root=$2
				configfile /boot/grub/grub.cfg
			}
		fi
	done
}

Serial

If native graphics initialization is not available one will most likely want to interact with GRUB via a serial connection. The following subsections show how to enable that in grub.cfg.

On a real serial port

To enable serial, add the following on top of your grub.cfg:

serial --speed=115200 --word=8 --parity=no --stop=1
terminal_input --append  serial
terminal_output --append serial

On a USB serial or USB debug adapter

To enable serial, first find out the name of your usb serial port trough:

insmod nativedisk # needed not to get the disk disapearing when insmoding the *hci
insmod ehci
insmod ohci
insmod uhci
insmod usb
insmod usbserial_pl2303
insmod usbserial_ftdi
insmod usbserial_usbdebug
terminal_output

The terminal_output command should print it:

grub> terminal_output 
Active output terminals:
serial_usb1 gfxterm 
Available output terminals:
console vga_text serial 

Here we can see "serial_usb1" so we now know that its name is usb1

Then add the following on top of your grub.cfg:

insmod nativedisk
insmod ehci
insmod ohci
insmod uhci
insmod usb
insmod usbserial_pl2303
insmod usbserial_ftdi
insmod usbserial_usbdebug
serial --speed=115200 --word=8 --parity=no --stop=1 usb1
terminal_output --append serial_usb1
terminal_input --append serial_usb1

The following chips/protocols are supported:

  • usbdebug
  • ftdi
  • pl2303

Less useful things

(Some of) these might be obsolete by now:

# Change the path to the GRUB directory so that it can load its modules/commands
set prefix=(memdisk)/boot/grub
# Add keyboard support
terminal_input --append at_keyboard

In case of native graphics you may want the following:

gfxpayload=keep
terminal_output --append gfxterm

Chain-loading other Payloads

Here is how to load another payload.

menuentry 'SeaBios' {
	set root='memdisk'
	echo    'Loading SeaBios ...'
	chainloader /bios.bin.elf
}

Compilation

Setup within coreboot's tree

The coreboot repository contains a GRUB2 submodule that can directly be selected in coreboot's Kconfig. Additionally, the config file has to be added, e.g. via the following command.

 build/cbfstool build/coreboot.rom add -f grub.cfg -n etc/grub.cfg -t raw

Out of tree compilation

In case you want to compile GRUB outside coreboot's directory follow the guide below.

Retrieve the source code, compile it and install the resulting utilities:

git clone git://git.savannah.gnu.org/grub.git grub
cd grub
./autogen.sh
./configure --with-platform=coreboot
make
sudo make install

Create target directories:

mkdir -p memdisk/boot/grub/

Then copy your grub.cfg into it:

memdisk/boot/grub/grub.cfg

Then adapt and run the following lines if need be.

rm -f grub2.elf
# Copy the payloads and other required files into the target dir.
cd memdisk
cp ../../seabios/out/bios.bin.elf .
cp ../../coreboot-qemu/payloads/nvramcui/nvramcui.elf .
cp ../../coreboot/payloads/coreinfo/build/coreinfo.elf .
cp ../../memtest86+-4.20/memtest memtest.elf
cp ../../coreboot/bootsplash.jpg  .
grub-mkstandalone -O i386-coreboot -o ../grub2.elf $(find -type f)

The resulting .elf can then be run as payload directly by coreboot or SeaBIOS. Also, grub2.elf can be tested in qemu.

To make it available in SeaBIOS add it to CBFS as follows:

build/cbfstool build/coreboot.rom add-payload -n img/grub2 -f grub2.elf -t raw

That way it is possible to run GRUB as a payload after SeaBIOS.

Alternatively, the .elf can also be added via Kconfig by setting its path.

In any case, make sure you have some kinds of output such as VGA or serial (it needs to be activated in both coreboot and GRUB)!

Advanced Features

Security

Signed kernels

GRUB is capable of running only trusted(signed) kernels. It supports both RSA and DSA gpg keys.

Here's a HOWTO:

First generate a key:

$ gpg --gen-key
gpg (GnuPG) 2.0.19; Copyright (C) 2012 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 3
DSA keys may be between 1024 and 3072 bits long.
What keysize do you want? (2048) 3072
Requested keysize is 3072 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Denis 'GNUtoo' Carikli
Email address: GNUtoo@no-log.org
Comment: Kernel signing key
You selected this USER-ID:
    "Denis 'GNUtoo' Carikli (Kernel signing key) <GNUtoo@no-log.org>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
You need a Passphrase to protect your secret key.

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: WARNING: some OpenPGP programs can't handle a DSA key with this digest 
size
gpg: key C86D4C64 marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   2  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 2u
pub   3072D/C86D4C64 2013-03-13
      Key fingerprint = 7244 AC33 F9A7 9AE8 30DE  8996 9097 B48D C86D 4C64
uid                  Denis 'GNUtoo' Carikli (Kernel signing key) 
<GNUtoo@no-log.org>

Note that this key cannot be used for encryption.  You may want to use
the command "--edit-key" to generate a subkey for this purpose.

Then sign the kernels and initramfs:

cd /boot
sudo -E gpg --detach-sign vmlinuz-linux-libre-pae
sudo -E gpg --detach-sign initramfs-linux-libre-pae.img
gpg --export  > boot.key

Then you can put the key on the memdisk (advised) or the boot partition for test purposes only. Then in GRUB do (for testing purposes):

trust boot.key
set check_signatures=enforce

to only boot correctly signed kernels and initramfs.

Then load kernel and initramfs as usual.

Trisquel, Ubuntu, Debian

We want automatics hooks to sign our kernel so we don't have to do it manually each time.

The following howto was tested on trisquel 6. Generate the key as root(sudo su) like we just explained, but without a password In debian based distributions you can hook the kernel build to sign the result: Add the following to /etc/kernel/postinst.d/yy-update-signatures

#! /bin/sh
set -e

version="$1"

rm -f /boot/vmlinuz-${version}.sig
gpg --detach-sign /boot/vmlinuz-${version}
rm -f /boot/initrd.img-${version}.sig
gpg --detach-sign /boot/initrd.img-${version}

Then do:

chmod +x /etc/kernel/postinst.d/yy-update-signatures

Then do:

gpg --export  > /boot/boot.key

Then modify /etc/grub.d/10_linux to use bash instead of sh like that:

#! /bin/bash

And also modify to that:

 case x`uname -m` in
     xi?86 | xx86_64)
 	list=`for i in /boot/vmlinuz-* /vmlinuz-* /boot/kernel-* ; do
                   if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
               done` ;;
     *) 
 	list=`for i in /boot/vmlinuz-* /boot/vmlinux-* /vmlinuz-* /vmlinux-* /boot/kernel-* ; do
                   if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
 	     done` ;;
 esac

To look like that:

 case x`uname -m` in
     xi?86 | xx86_64)
 	list=`for i in /boot/vmlinuz-* /vmlinuz-* /boot/kernel-* ; do
                   if [[ "$i" != /boot/*.sig ]] ; then 
                       if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
                   fi
               done` ;;
     *) 
 	list=`for i in /boot/vmlinuz-* /boot/vmlinux-* /vmlinuz-* /vmlinux-* /boot/kernel-* ; do
                   if grub_file_is_not_garbage "$i" ; then echo -n "$i " ; fi
 	     done` ;;
 esac

LUKS

GRUB is capable of opening LUKS disks like that:

grub> ls 
(ata2) (ata2,msdos3) (ata2,msdos2) (ata2,msdos1) (usb0) (usb0,msdos1) (ata6) (memdisk)
grub> cryptomount (ata2,msdos3)
Attempting to decrypt master key...
Enter passphrase for ata2,msdos3 (431439b0870f40a3bfe8f3ca3aa7072a):
Slot 0 opened
grub> ls
(crypto0) (ata2) (ata2,msdos3) (ata2,msdos2) (ata2,msdos1) (usb0) (usb0,msdos1) (ata6) (memdisk) 
grub> set root=crypto0
grub> ls /
lost+found/ boot/ var/ dev/ run/ etc/ tmp/ sys/ proc/ usr/ lib/ sbin/ bin/ home/ mnt/ opt/ root/ srv/ media/

Note that you have to type the password, so it's better to have some kind of output (VGA, Serial etc...)