Libreboot documentation: GRUB menu

+ Libreboot uses the GRUB payload + by default, which means that the GRUB configuration file + (where your GRUB menu comes from) is stored directly alongside libreboot + and it's GRUB payload executable, inside + the flash chip. In context, this means that installing distributions and managing them + is handled slightly differently compared to traditional BIOS systems. +

+ A libreboot (or coreboot) ROM image is not simply "flat"; there is an actual + filesystem inside called CBFS (coreboot filesystem). A utility called 'cbfstool' + allows you to change the contents of the ROM image. In this case, libreboot is configured + such that the 'grub.cfg' and 'grubtest.cfg' files exists directly inside CBFS instead of + inside the GRUB payload's 'memdisk' (which is itself stored in CBFS). +

Getting started

Build 'cbfstool' from source

+ If you are working with libreboot_src, then you can run make command in + libreboot_src/coreboot/util/cbfstool to build the cbfstool and rmodtool + executable. +

+ Alternatively if you are working with libreboot_bin, then you can run ./builddeps-cbfstool + command inside libreboot_bin/; a cbfstool and rmodtool + executable will appear under libreboot_bin/ +

Which ROM image should I use?

+ You can work directly with one of the ROM's already included in the libreboot ROM archives. For the purpose of + this tutorial it is assumed that your ROM is named libreboot.rom so please make sure to adapt. +

+ If you want to re-use the ROM that you currently have flashed (and running) then see + ../git/index.html#build_flashrom + and then run:
+ $ sudo ./flashrom -p internal -r libreboot.rom
+ Notice that this is using "-r" (read) instead of "-w" (write). + This will create a dump (copy) of your current firmware and name it libreboot.rom. + You need to take ownership of the file. For example:
+ $ sudo chown yourusername:yourusername libreboot.rom
+ # chown yourusername:yourusername libreboot.rom +

+ If you currently have flashed a ROM image from an older version, it is recommended to update first: + basically, modify one of the latest ROM's and then flash it. +

Extract grubtest.cfg from the ROM image

+ The libreboot.rom file contains your grub.cfg and grubtest.cfg files. + You should extract, modify and re-insert the copy first. grub.cfg will load first, + but it has a menu entry for switching to the copy (grubtest.cfg). + This reduces your chance of making a mistake that could make your machine unbootable (or very hard to boot). +

+ Extract grubtest.cfg from the ROM image:
+ $ ./cbfstool libreboot.rom extract -n grubtest.cfg -f grubtest.cfg +

+ Now you have a grubtest.cfg in cbfstool directory. Edit it however you wish. +

+ +

Example modifications for grubtest.cfg

+ +

+ These are some common examples of ways in which the grubtest.cfg file can be modified. +

+ +

Trisquel GNU/Linux-libre

+ +

+ As an example, on my test system in /boot/grub/grub.cfg (on the HDD/SSD) I see for the main menu entry: +

linux /boot/vmlinuz-3.15.1-gnu.nonpae root=UUID=3a008e14-4871-497b-95e5-fb180f277951 ro crashkernel=384M-2G:64M,2G-:128M quiet splash $vt_handoff
initrd /boot/initrd.img-3.15.1-gnu.nonpae

+ +

+ ro, quiet, splash, crashkernel=384M-2G:64M,2G-:128M and + $vt_handoff can be safely ignored. +

+ +

+ I use this to get my partition layout:
+ $ lsblk +

+ +

+ In my case, I have no /boot partition, instead /boot is on the same partition as / on sda1. + Yours might be different. In GRUB terms, sda means ahci0. 1 means msdos1, or gpt1, depending + on whether I am using MBR or GPT partitioning. Thus, /dev/sda1 is GRUB is (ahci0,msdos1) or + (ahci0,gpt1). In my case, I use MBR partitioning so it's (ahci0,msdos1). + 'msdos' is GRUB's name simply because this partitioning type is traditionally used by MS-DOS. + It doesn't mean you have a proprietary OS. +

+ +

+ Trisquel doesn't keep the filenames of kernels consistent, instead it keeps old kernels and + new kernel updates are provided with the version in the filename. This can make GRUB payload + a bit tricky. Fortunately, there are symlinks /vmlinuz and /initrd.img + so if your /boot and / are on the same partition, you can set GRUB to boot from that. + These are also updated automatically when installing kernel updates from your distributions + apt-get repositories. + + Note: when using jxself kernel releases, + these are not updated at all and you have to update them manually. + +

+ +

+ For the GRUB payload's grubtest.cfg (in the 'Load Operating System' menu entry), we therefore have (in this example):
+ set root='ahci0,msdos1'
+ linux /vmlinuz root=UUID=3a008e14-4871-497b-95e5-fb180f277951
+ initrd /initrd.img +

+ +

+ Optionally, you can convert the UUID to it's real device name, for example /dev/sda1 in this case. + sdX naming isn't very reliable, though, which is why UUID is used for most distributions. +

+ +

+ Alternatively, if your /boot is on a separate partition then you cannot rely on the /vmlinuz and /initrd.img symlinks. + Instead, go into /boot and create your own symlinks (update them manually when you install a new kernel update).
+ $ sudo -s
+ # cd /boot/
+ # rm -rf vmlinuz initrd.img
+ # ln -s kernel ksym
+ # ln -s initrd isym
+ # exit +

+ +

+ Replace the underlined kernel and initrd filenames above with the actual filenames, of course. +

+ +

+ Then your grubtest.cfg menu entry (for payload) becomes like that, for example if / was on sda2 and /boot was on sda1:
+ set root='ahci0,msdos1'
+ linux /ksym root=/dev/sda2
+ initrd /isym +

+ +

+ There are lots of possible variations so please try to adapt. +

+ +

Parabola GNU/Linux-libre

+ +

+ You can basically adapt the above. Note however that Parabola does not keep old kernels still installed, and the file names + are always consistent, so you don't need to boot from symlinks, you can just use the real thing directly. +

+ +

Re-insert the modified grubtest.cfg into the ROM image

+ Delete the grubtest.cfg that remained inside the ROM:
+ $ ./cbfstool libreboot.rom remove -n grubtest.cfg +

+ Display ROM contents and now you see grubtest.cfg no longer exists there:
+ $ ./cbfstool libreboot.rom print +

+ Add the modified version that you just made:
+ $ ./cbfstool libreboot.rom add -n grubtest.cfg -f grubtest.cfg -t raw +

+ Now display ROM contents again and see that it exists again:
+ $ ./cbfstool libreboot.rom print +

Test it!

+ + Now you have a modified ROM. Refer back to ../install/index.html#flashrom for information + on how to flash it. Once you have done that, shut down and then boot up with your new test configuration. + +

+ Choose (in GRUB) the menu entry that switches to grubtest.cfg. If it works, then your config is safe and you can continue below. +

+ + If it does not work like you want it to, if you are unsure or sceptical in any way, + then re-do the steps above until you get it right! Do *not* proceed past this point + unless you are 100% sure that your new configuration is safe (or desirable) to use. + +

Final steps

+ Create a copy of grubtest.cfg, called grub.cfg, which is the same except for one difference: + change the menuentry 'Switch to grub.cfg' to 'Switch to grubtest.cfg' and inside it, + change all instances of grub.cfg to grubtest.cfg. This is so that the main config still + links (in the menu) to grubtest.cfg, so that you don't have to manually switch to it, in + case you ever want to follow this guide again in the future (modifying the already modified config)
+ $ sed -e 's:(cbfsdisk)/grub.cfg:(cbfsdisk)/grubtest.cfg:g' -e 's:Switch to grub.cfg:Switch to grubtest.cfg:g' < grubtest.cfg > grub.cfg
+

+ Delete the grub.cfg that remained inside the ROM:
+ $ ./cbfstool libreboot.rom remove -n grub.cfg +

+ Display ROM contents and now you see grub.cfg no longer exists there:
+ $ ./cbfstool libreboot.rom print +

+ Add the modified version that you just made:
+ $ ./cbfstool libreboot.rom add -n grub.cfg -f grub.cfg -t raw +

+ Now display ROM contents again and see that it exists again:
+ $ ./cbfstool libreboot.rom print +

+ + Now you have a modified ROM. Refer back to ../install/index.html#flashrom for information + on how to flash it. Once you have done that, shut down and then boot up with your new configuration. + +

Troubleshooting

+ A user reported that segmentation faults occur with cbfstool + when using this procedure depending on the size of the grub.cfg being re-insterted. + In his case, a minimum size of 857 bytes was required. This could (at the time of + this release) be a bug in cbfstool that should be investigated with the coreboot + community. If cbfstool segfaults, then keep this in mind. 'strace' (or gdb? clang?) + could be used for debugging. This was in libreboot 5th release (based on coreboot + from late 2013), and I'm not sure if the issue perists in the current releases. + I have not been able to reproduce it. strace (from that user) is here: + cbfstool_libreboot5_strace. + The issue has been reported by a few users, so it does not happen all the time: + this bug (if it still exists) could (should) be reproduced. +

+ Copyright © 2014 Francis Rowe <info@gluglug.org.uk>
+ This document is released under the Creative Commons Attribution-ShareAlike 4.0 International Public License and all future versions. + A copy of the license can be found at ../license.txt. +

+ This document is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See ../license.txt for more information. +

How to change your default GRUB menu

Table of Contents