libreboot/docs/grub/grubeditor.md

GRUB EDITOR

Libreboot ROM images now support fluid grub.cfg and grubtest.cfg configuration editing with the grubeditor.sh script! Instead of manually running cbfstool to manipulate these configuration files, this script will handle the work for you so you can focus on actually modifying your GRUB configuration files to your setup's needs.

At the time of this writing, grubeditor.sh supports extracting and editing either the grub.cfg or grubtest.cfg file in any cbfstool-compatible Libreboot ROM image that contains these files, even ones that have been previously modified. It can also swap these configuration files in an existing ROM image, handy if you have a working grubtest.cfg and want to make it the default or if you broke the main grub.cfg and know that your grubtest.cfg still works. Lastly, it can also run diff on these two configuration files to show you how they differ.

Introduction

grubeditor.sh takes a number of options, the only one which is required being a valid Libreboot ROM image that uses the GRUB2 payload and contains both grub.cfg and grubtest.cfg files. Additional options should come before the ROM image file on the command line.

You can call the script the-hor--help` option to view a brief summary of the options available. Consider this guide a more extensive version of this screen.

grubeditor.sh supports extended getopt, which means that all options have both a short and a long form which respectively begin with a single hyphen and a double hyphen. You can group together several short options with a single hyphen like -ris (or not, like -r -i -s). Long options should be written as standalone arguments.

Lastly, you can check which version of grubeditor.sh you are using with the -v or --version option.

Requirements

grubeditor.sh requires an x86, x86_64, or armv7l environment, since these are the environments for which cbfstools binaries are provided. Additionally, grubeditor.sh needs a Bash environment with extended getopt functionality that can run the diff command and write to /tmp. Lastly, the script expects to live in the top directory of the Libreboot utilities package so it can properly call cbfstool.

Chances are that you already meet these requirements if you are on a Linux environment of the listed architectures and downloaded the Libreboot utilities package from an official source. If not, it shouldn't be too hard to use a Linux LiveCD of your choice which provides these essentials.

Optionally, you should make sure your EDITOR variable is set. Otherwise, grubeditor.sh will default to using vi, which may not exist on your system. You can override this default or the contents of your EDITOR variable using the -e or --editor command.

Editing configuration files

Invoked without any arguments except for the ROM image, grubeditor.sh will attempt to extract the grubtest.cfg file from the provided ROM image and launch it in your editor of choice. If you make changes to the file, grubeditor.sh will incorporate your changes into a new ROM image with the same name in the same directory, except that the new ROM file will end with ".modified". You can then flash this ROM image to your platform's BIOS chip.

If you would prefer to edit the actual grub.cfg configuration file, use the -r or the --realcfg option. Everything else will work the same except that your editor will open the grub.cfg instead.

If you would prefer to overwrite your existing ROM image instead of creating a new one ending in ".modified" use the -i or --inplace option. Naturally, you can combine this option with the -r/--realcfg option described above.

Swapping and diffing grub.cfg and grubtest.cfg

grubeditor.sh supports swapping the grub.cfg and grubtest.cfg configuration files with the -s or --swap options. This will create a new ROM image alongside the existing ROM image ending with ".modified" which has these files swapped. Naturally, you can request this operation overwrite the existing file instead using the -i/--inplace option.

Lastly, grubeditor.sh supports comparing grub.cfg and grubtest.cfg files for differences with the -d or --diffcfg option. This uses the diff command by default, but if you want to use another program (e.g. vimdiff), you can specify it with the -D or --differ option. Note that this mode is only intended to show differences in the files and does not support updating the configs themselves, so any changes you make in an interactive differ will be ignored.

Conclusion

I hope that grubeditor.sh will significantly ease modifying your configuration files in your Libreboot ROM files.

Should you find any bugs or want any feature requests, please don't hesitate to email me or bug me on IRC.