Page MenuHomeVyOS Platform

GRUB loader configuration rework
In progress, NormalPublicFEATURE REQUEST


The problem and solution idea

We now use a single configuration file for GRUB (grub.cfg). This is simple and understandable to humans because all the info can be easily read and understood. However, this also makes life much harder for software: there is no way to easily modify the file from the installation script and other places. Scripts need to parse it which leads to multiple mistakes, inserting a new entry is also not a very trivial task.

This is a stopper for more flexible boot menus and better/richer system image manipulation tools.

It would be good to reorganize the whole GRUB config in a way, where everything will be both human and machine-readable, and also very easy to modify.

GRUB configuration supports a lot of internal scripting, and we can use this power here. We can use for loops together with source commands to include multiple configuration parts and construct a menu from them. Moreover, each included configuration part may include its chunks, which allows giving each installed VyOS version its section and boot settings.

Simplified example

An example of the main configuration file to make this possible is:

insmod regexp

for cfgfile in ${prefix}/grub.cfg.d/*.cfg
    source ${cfgfile}

And it will load all the .cfg files from /boot/grub/grub.cfg.d/ directory.

New configuration structure

I am suggesting switching to the next configuration structure (relatively to the /boot/grub/ directory):

File pathDescription
grub.cfgmain configuration file
grub.cfg.d/directory with other config files
grub.cfg.d/10-vyos-modules.cfgloading GRUB modules
grub.cfg.d/20-vyos-defaults.cfgsetting default values (for all installed versions)
grub.cfg.d/30-vyos-platform.cfgsettings specific to a hardware/virtual platform
grub.cfg.d/40-vyos-menu.cfgload menu entries for all installed versions from the directory described below
grub.cfg.d/vyos-versions/VERSION_NAME.cfgmenuentries for a specific installed version
grub.cfg.d/vyos-versions/VERSION_NAME/an optional directory with additional configuration files required by a scecific installed version

With a structure like this, each component or version gets its configuration file and it is much easier to generate them from scripts. Adding or removing a new version becomes as easy as adding or removing a file from the directory.

New menu structure

Also, this opens a way for the reorganization of the GRUB menu, to make it easier to use, especially in the case when many versions are installed or multiple consoles are available. So, we can split it into multiple levels using submenu and navigate between them.

The suggested structure is:

  • List of installed versions
    • Boot mode for a selected version (normal, password reset)
      • Console type to use (KVM, serial, USB)

With this, each version can contain specific settings available from the menu. For example, we can add at some moment a simple recovery mode with the ability to modify the filesystem, pass additional parameters to the system during boot, etc.

Implementation stages

I realize that migration to this new structure can be not so fast and easy, because we may need to rewrite a code in many places at the same time to not break any features, so I think that it can be done in multiple stages:

  1. Prepare a module for operating with the new GRUB structure. Can be done as a part of this task:
  2. Create migration service to the new structure. It can check during the boot if the configuration file has a new structure and migrate it, if necessary. At the same time all the commands like add/delete/show image should be migrated to a new module written in stage 1.
  3. Rewrite image build tools to create a new structure during the build process.


Difficulty level
Hard (possibly days)
Why the issue appeared?
Will be filled on close
Is it a breaking change?
Config syntax change (migratable)
Issue type
Improvement (missing useful functionality)

Event Timeline

zsdc changed the task status from Open to In progress.Tue, Aug 2, 4:21 PM
zsdc triaged this task as Normal priority.
zsdc changed Difficulty level from Unknown (require assessment) to Hard (possibly days).