Zerocat’s Coreboot Machines  v0.9.0
How to create Zerocat’s Coreboot Machines like the ZC-X200 and others...
GRUB How-To

Main Page | Related Pages | List of Files

Todo:
This file needs to get reviewed and updated. All steps listed here (except authentication support) are understood by the toolchain scripts. Please don't apply these steps manually but use the scripts instead! See Toolchain for most recent documentation.

This tutorial hopefully helps to understand how to pack a GRUB executable elf payload file for the coreboot project. It further shows how to add Zerocat’s GRUB Configuration File into the generated coreboot.rom to make your machine boot with a nice GRUB Boot Loader Menu.

Points of Interest

Short Basics about GRUB

During boot, GRUB starts loading the 'normal' module and its dependencies 'terminal', 'crypto', 'extcmd', 'boot' and 'gettext'. It then looks for its configuration file and loads additional modules as required by occurring statements. However, modules that are not loaded as required by the dependencies have to be loaded explicitly using the insmod command or have to be packed as pre-loaded modules within the executable *.elf payload file. Examples for the latter case are modules 'luks' and 'geli' which will make the cryptomount statement work with encrypted disks and LUKS containers.

Basically, three files form a complete GRUB arrangement:

GRUB File System

After boot, all packed files of the executable GRUB payload file will be accessible within GRUB’s (memdisk)/boot/grub/ default file system. On GRUB’s command line, you may use ls and cat to check folder and file contents, and insmod to extend GRUB’s functionality.

Important Files within the GRUB File System

Coreboot’s GRUB Configuration File

Note the content of GRUB’s first configuration file grub-2.02_coreboot.cfg as provided by Zerocat.

This file will be packed into GRUB’s file system (memdisk)/boot/grub/ as grub.cfg. Please verify that its first line contains the “set prefix” statement, otherwise GRUB will issue error messages during boot. The advantage of referencing a custom grub.cfg outside the GRUB file system – i.e.: (cbfsdisk)/etc/zerocat.cfg – is that you needn't generate the executable GRUB payload file again once your are updating your GRUB configuration.

Get GRUB Sources

$ git clone git://git.savannah.gnu.org/grub grub-2.02
$ cd grub-2.02

Let’s use a tagged version: 2.02

$ git checkout 2.02

Then configure and compile:

$ ./autogen.sh
$ ./configure --with-platform=coreboot
$ make

This will also generate some *.pf2 font files as like ascii.pf2 or unicode.pf2 for example. Or like dejavu_14.pf2 in case the DejaVu Fonts are installed on your system. Play around with grub-mkfont in case you want to generate your custom *.pf2 font. Note we choose unicode.pf2 as default when it comes to pack the elf executable payload file in next section.

Finally, install GRUB locally in order to put all files in place before you proceed:

$ sudo make install

(You might uninstall GRUB with $ sudo make uninstall later on.)

Pack Your GRUB Payload File

A dedicated shell script with rich keyboard layout support is part of the toolchain: gen-payload-grub.sh.

This script generates a bunch of layout files and creates a code snippet for Zerocat’s GRUB Configuration File, for instance:

---------8<-------------cut here cut here cut here----------------->8---------
# Keymap --- several options available, adapt to your needs:
# us gb fi dk se hu cz pl bg ro tr fr pt es it nl be de
# ca_fr tr_f ch_de ch_fr
# us_intl us_dvorak fr_latin9 de_nodeadkeys sk_qwerty
keymap us
---------8<-------------cut here cut here cut here----------------->8---------

Another code snippet is generated and will be picked by the script when it comes to pack the payload file with the bunch of layout files amoung others.

Adding SeaBIOS Payload

GRUB is able to chainload other payloads, so we suggest to add SeaBIOS as well. This will allow you to run the Qubes OS Installer while having GRUB’s authentication support still available as an option. Furthermore, SeaBIOS provides basic access to TPM chips, if available.

The SeaBIOS executable elf payload file has to be built externally. Sources can be downloaded and configured like this:

$ git clone https://git.seabios.org/seabios.git
$ cd seabios

Let's use a tagged version:

$ git checkout rel-1.12.0
$ make menuconfig
$ make

General Features —>

In case you selected “Devices –> Graphics initialization = ‘Run VGA Option ROMs’” within the coreboot configuration, configure SeaBIOS with “VGA Rom –> VGA Hardware Type (None)”.

In case you selected “Devices –> Graphics initialization = ‘Use native graphics init’” within the coreboot configuration, configure SeaBIOS with “VGA Rom –> VGA Hardware Type (Coreboot linear framebuffer)”. Examples given: ThinkPad X200, X230, T430. A VGA wrapper called out/vgabios.bin will be created by SeaBIOS and this file has to be added to your coreboot.rom later on:

$ cd coreboot/
$ build/cbfstool build/coreboot.rom add -t raw -n vgaroms/vgabios.bin -f path/to/your/seabios/out/vgabios.bin
$ build/cbfstool build/coreboot.rom print

In any case, add the SeaBIOS executable payload file to the coreboot.rom:

$ build/cbfstool build/coreboot.rom add-payload -n seabios.elf -f path/to/your/seabios/out/bios.bin.elf
$ build/cbfstool build/coreboot.rom print

Done.

Zerocat’s GRUB Configuration File

Let’s use Zerocat’s GRUB Configuration File (with code snippets copied from the libreboot project) to start with. Note we use this file on ThinkPad Laptops – in case you want to use it for Desktop Boards, it should work just fine. You might add some additional insmod statements, though.

Two important statements are provided in order to support command cryptomount, which is used to boot from encrypted devices and LUKS containers:

insmod luks
insmod geli

Available for download: grub-2.02_zerocat.cfg

This file has to be copied into the coreboot file system by means of coreboot’s cbfstool:

$ build/cbfstool build/coreboot.rom add -n etc/zerocat.cfg -t raw -f path/to/your/grub-2.02_zerocat.cfg
$ build/cbfstool build/coreboot.rom print

Adjust paths as required. Make sure option -n etc/zerocat.cfg matches the source path as specified in GRUB’s first configuration file grub-2.02_coreboot.cfg as provided by this project.

GRUB’s Authentication Support

The configuration file comes with a pre-defined set of GRUB users and corresponding clear text passwords:

password user0 topsecret0
password user1 topsecret1
password user2 topsecret2

Super cow power is granted to user ‘user0’, but other users can be specified as well if you use a space separated list. Setting the variable superusers to any value – including "" – actually activates GRUB’s authentication support:

set superusers="user0"

This setup improves your security as it restricts access to the GRUB boot menu in the following manner:

Warning
Playing around with authentication can be dangerous, as it will easily lock you out from accessing any hard disk or USB rescue system! Be aware of what you are doing, always double check your settings. Provide at least one unrestricted menu entry to boot your disk until you get confidence that all other settings work as intended. Note commands password and password_pbkdf2 are expecting two arguments, provided in the same line, separated by one ‘space’ character only. Disobey this rule and you will have to spend time and money in order to re-flash your device!
Note
In order to disable GRUB’s authentication support per default, set superusers="user0" has been turned into a comment line. Remove the preceding hash character (#) if you really want to activate GRUB’s authentication support! Please adjust user names and passwords to your needs! You can improve the level of security by using hashed passwords instead of clear text ones. See https://www.gnu.org/software/grub/manual/grub/grub.html#Security for more info's.

Done!

Your Coreboot ROM should now contain a valid GRUB payload configuration.

Main Page | Related Pages | List of Files