---
title: Modifying the GRUB configuration in CBFS for bare metal GNU GRUB coreboot payload
x-toc enable: true
...

This guide assumes that you use the GNU GRUB bootloader as your default
payload. In this configuration, GNU GRUB is flashed alongside coreboot and runs
on *bare metal* as a native coreboot payload and does *not* use BIOS or UEFI
services (but it *can* load and execute SeaBIOS, in addition to any other
coreboot payload, by chainloading it).

In most circumstances, this guide will not benefit you. Retroboot's default
GRUB configuration file contains scripting logic within it that intelligently
searches for GRUB partitions installed onto a partition on your SSD, HDD or
USB drive installed on your computer. If such a file is found, Retroboot's
default GRUB configuration is configured to switch automatically to that
configuration. While not perfect, the logic *does* work with most
configurations.

Therefore, you should only follow *this* guide if the automation (described
above) does not work. It goes without saying that modifying the default GRUB
configuration is risky, because a misconfiguration could create what's called
a *soft brick* where your machine is effectively useless and, in that scenario,
may or may not require external flashing equipment for restoring the machine to
a known state.

## Extracting the GRUB configuration file from your Retroboot ROM image

There are mainly three methods for obtaining a Retroboot ROM image:

1. Dump the contents of the the main *boot flash* on your system, which already
   has Retroboot installed (with GNU GRUB as the default payload). Extract the
   GRUB configuration from *that* ROM image.
2. Extract it from a Retroboot ROM image supplied by the Retroboot project, on
   the Retroboot website or mirrors of the Retroboot website.
3. Build the ROM yourself, using the Retroboot build system. Instructions for
   how to do this are covered in the following article:
   [How to build Retroboot from source](../git/)

In either case, you will use the `cbfstool` supplied by the coreboot project.
This can be found under `coreboot/*/util/cbfstool/` as source code,
where `*` can be any coreboot source code directory for a given mainboard.

For the time being, no *stable* Retroboot release exists and there are no
archives available with pre-compiled binaries. Therefore, we will download
the *source code* and *compile it*.

Since no stable release schedule is yet established for Retroboot, you may also
wish to compile the Retroboot ROM yourself. The guide linked above will tell
you how to do that.

Install the build dependencies. For Ubuntu 20.04 and similar, you can run
the following command in the Retroboot build system, from the root directory
of the Retroboot Git repository.

    ./build dependencies ubuntu2004

Then, download coreboot:

    ./download coreboot

Finally, compile the `cbutils` module:

    ./build module cbutils

Among other things, this will produce a `cbfstool` executable under any of the
subdirectories in `coreboot/` under `util/cbfstool/cbfstool

For example: coreboot/x230\_4mb/util/cbfstool/cbfstool

The `cbfstool` utility is what you shall use. It is used to manipulate CBFS
(coreboot file system) which is a file system contained within the coreboot
ROM image; as a *coreboot distribution*, Retroboot inherits this technology.

You will also want to build `flashrom` which Retroboot recommends for reading
from and/or writing to the boot flash. In the Retroboot build system, you can
build it by running this command:

    ./build module flashrom

An executable will be available at `flashrom/flashrom` after you have done
this.

### Dump the boot flash

If you wish to modify your *existing* Retroboot ROM, which was installed on
your computer, you can use `flashrom` to acquire it.

Simply run the following, after using Retroboot's build system to compile
flashrom:

    sudo ./flashrom/flashrom -p internal -r dump.bin

If flashrom complains about multiple flash chip definitions, do what it says to
rectify your command and run it again.

The `internal` option assumes that internal read/write is possible; this is
when you read from and/or write to the boot flash from an operating systems
(usually GNU+Linux) that is *running on* the target system.

At other sites, you may need to connect an SPI programmer externally (with the
machine powered down) and read the contents of the boot flash. At present, the
only SPI flasher documented by Retroboot is the *Raspberry Pi* which you can
learn how to use (for this purpose) by reading the following guide:
[How to program an SPI flash chip with the Raspberry Pi](../install/rpi_setup.md)

You *can* simply put a custom `grub.cfg` under `/boot/grub/` on your installed
GNU+Linux system, if you're using GNU+Linux. Retroboot also provides
instructions for systems running BSD with GNU GRUB payload in Retroboot, on
these articles:
[../bsd/](../bsd/)

Retroboot images that use the GNU GRUB bootloader will have *two* configuration
files in CBFS:

* `grub.cfg`
* `grubtest.cfg`

We recommend that you modify `grubtest.cfg` first, and boot. Select the boot
menu option for loading `grubtest.cfg` and verify that your new config works
correctly. If it doesn't, keep modifying `grubtest.cfg` until it does work.
When that it done, copy the changes over to `grub.cfg

You can use the following commands to modify the contents of CBFS, where
GRUB's configuration file is concerned (dump.bin is the ROM that you dumped,
or it could refer to the Retroboot ROM image that you compiled or otherwise
acquired).

Show the contents of CBFS, in your ROM:

    cbfstool dump.bin print

Remove `grub.cfg` (substitute with `grubtest.cfg` as desired):

    cbfstool dump.bin remove -n grub.cfg

Add your modified `grub.cfg` (substitute with `grubtest.cfg` as desired):

    cbfstool dump.bin add -f grub.cfg -n grub.cfg -t raw

Your modified `dump.bin` or other modified Retroboot ROM can then be re-flashed
using:

    sudo ./flashrom -p internal -w dump.bin

If a `-c` option is required, use it and specify a flash chip name. This is
only useful when `flashrom` complains about multiple flash chips being
detected.

If you need to use external flashing equipment, see the link above to the
Raspberry Pi page.
