org.osbuild.grub2

Configure GRUB2 bootloader and set boot options

Configure the system to use GRUB2 as the bootloader, and set boot options. Sets the GRUB2 boot/root filesystem to rootfs. If a separated boot partition is used it can be specified via bootfs. The file-systems can be identified either via uuid (\{"uuid": "\<uuid\>"\}) or label (\{"label": "\<label\>"\}). The kernel boot argument will be composed of the root file system id and additional options specified in \{kernel_opts\}, if any. Configures GRUB2 to boot via the Boot Loader Specification (https://systemd.io/BOOT_LOADER_SPECIFICATION), which is the default behavior in Fedora 30 and later. This stage will overwrite /etc/default/grub, /boot/grub2/grubenv, and /boot/grub2/grub.cfg. (Leading directories will be created if not present.) If Legacy boot support is requested via legacy this stage will also overwrite /boot/grub2/grub.cfg and will copy the GRUB2 files from the buildhost into the target tree:

• /usr/share/grub/unicode.pf2 -> /boot/grub2/fonts/
• /usr/lib/grub/$platform/*.\{mod,lst\} -> /boot/grub2/$platform/
  • NOTE: skips fdt.lst, which is an empty file The $platform variable (default: i386-pc) refers to target platform that grub2 is mean to ran on (see grub-install(1)'s --target) NB: with legacy support enabled, this stage will fail if the buildhost doesn't have /usr/lib/grub/$platform/ and /usr/share/grub/unicode.pf2. If UEFI support is enabled via uefi: \{"vendor": "\<vendor\>"\} this stage will also write the grub.cfg to boot/efi/EFI/\<vendor\>/grub.cfg. EFI binaries and accompanying data can be installed from the built root via uefi.install. Both UEFI and Legacy can be specified at the same time (hybrid boot). If uefi.unified is specified or hybrid boot is enabled, the main grub config will be written to boot/grub2/grub.cfg and a redirect config will be placed in the EFI directory. If the saved_entry option is present it will result in an entry in the grubenv file of the same name. The grub config file contains logic so that this variable will be used to select the next boot entry. This will also make grub2-reboot and grub2-set-default tools work. It will also prevent newly installed non-default kernels (like e.g. the debug kernel) to be selected as default. The contents of variable needs to match the corresponding loader entry, which currently is a combination of the machine id and kernel NVRA, like e.g.: ffffffffffffffffffffffffffffffff-5.6.6-300.fc32.x86_64 If saved_entry is set it is advisable to set config.default to saved so that any re-creation of the grub configuration by the user will preserve that functionality. Support for "greenboot" can be turned on via the greenboot option. Greenboot is the idea of automatically rolling back bad updates, i.e. updates that do not boot successfully. The implementation is split between the boot loader and a user space component. The latter sets two variables boot_counter, which indicates the maximum number of boot attempts and boot_success which tells the boot laoder if a previous boot was successful. The bootloader on the other hand will decrement the counter variable and reset the success indicator one. An implementation of the user space component for rpm-ostree is called greenboot. Support for ignition (https://github.com/coreos/ignition) can be turned on via the ignition option. If enabled, a 'ignition_firstboot' variable will be created, which is meant to be included in the kernel command line. The grub.cfg will then contain the necessary code to detect and source the '/boot/ignition.firstboot' file and configure said 'ignition_firstboot' variable appropriately. See the 'org.osbuild.ignition' stage for more information on that file.

Schema 1

{
  "additionalProperties": false,
  "oneOf": [
    {
      "required": [
        "root_fs_uuid"
      ]
    },
    {
      "required": [
        "rootfs"
      ]
    }
  ],
  "definitions": {
    "uuid": {
      "description": "Identify the file system by UUID",
      "type": "string",
      "oneOf": [
        {
          "pattern": "^[0-9A-Za-z]{8}(-[0-9A-Za-z]{4}){3}-[0-9A-Za-z]{12}$",
          "examples": [
            "9c6ae55b-cf88-45b8-84e8-64990759f39d"
          ]
        },
        {
          "pattern": "^[0-9A-Za-z]{4}-[0-9A-Za-z]{4}$",
          "examples": [
            "6699-AFB5"
          ]
        }
      ]
    },
    "filesystem": {
      "description": "Description of how to locate a file system",
      "type": "object",
      "oneOf": [
        {
          "required": [
            "uuid"
          ]
        },
        {
          "required": [
            "label"
          ]
        }
      ],
      "properties": {
        "label": {
          "description": "Identify the file system by label",
          "type": "string"
        },
        "uuid": {
          "$ref": "#/definitions/uuid"
        }
      }
    },
    "terminal": {
      "description": "Terminal device",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "properties": {
    "rootfs": {
      "$ref": "#/definitions/filesystem"
    },
    "bootfs": {
      "$ref": "#/definitions/filesystem"
    },
    "root_fs_uuid": {
      "$ref": "#/definitions/uuid"
    },
    "boot_fs_uuid": {
      "$ref": "#/definitions/uuid"
    },
    "kernel_opts": {
      "description": "Additional kernel boot options",
      "type": "string",
      "default": ""
    },
    "legacy": {
      "description": "Include legacy boot support",
      "oneOf": [
        {
          "type": "boolean",
          "default": false
        },
        {
          "type": "string"
        }
      ]
    },
    "uefi": {
      "description": "Include UEFI boot support",
      "type": "object",
      "required": [
        "vendor"
      ],
      "properties": {
        "vendor": {
          "type": "string",
          "description": "The vendor of the UEFI binaries (this is us)",
          "examples": [
            "fedora"
          ],
          "pattern": "^(.+)$"
        },
        "efi_src_dir": {
          "type": "string",
          "description": "The source path to use for the EFI/ binaries when installing is set to True",
          "default": "/boot/efi/EFI"
        },
        "install": {
          "description": "Install EFI binaries and data from the build root",
          "type": "boolean",
          "default": false
        },
        "unified": {
          "description": "Main grub config in 'boot/grub2/grub.cfg'",
          "type": "boolean",
          "default": false
        }
      }
    },
    "saved_entry": {
      "description": "Set the variable of the same name in `grubenv`.",
      "type": "string"
    },
    "write_defaults": {
      "description": "Whether to write /etc/defaults/grub",
      "type": "boolean",
      "default": true
    },
    "write_cmdline": {
      "description": "Include the kernel command line in `grubenv`",
      "type": "boolean",
      "default": true
    },
    "ignition": {
      "description": "Include ignition support in the grub.cfg",
      "type": "boolean",
      "default": false
    },
    "greenboot": {
      "description": "Include support for fallback counting",
      "type": "boolean",
      "default": false
    },
    "config": {
      "description": "Configuration options for grub itself",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "default": {
          "description": "Default boot entry",
          "type": "string"
        },
        "disable_recovery": {
          "type": "boolean"
        },
        "disable_submenu": {
          "type": "boolean"
        },
        "distributor": {
          "description": "Name of the distributor",
          "type": "string"
        },
        "terminal": {
          "$ref": "#/definitions/terminal"
        },
        "terminal_input": {
          "$ref": "#/definitions/terminal"
        },
        "terminal_output": {
          "$ref": "#/definitions/terminal"
        },
        "timeout": {
          "description": "Timeout in seconds",
          "type": "integer",
          "minimum": 0,
          "default": 0
        },
        "timeout_style": {
          "type": "string",
          "enum": [
            "hidden",
            "menu",
            "countdown"
          ]
        },
        "serial": {
          "description": "The command to configure the serial console",
          "type": "string"
        }
      }
    }
  }
}

Schema 2

{}