Skip to main content Link Menu Expand (external link) Document Search Copy Copied
OpenCore Configuration

OpenLinuxBoot

OpenLinuxBoot is an OpenCore plugin implementing . It aims to automatically detect and boot most Linux distros without additional configuration.

Usage is as follows:

  • Add OpenLinuxBoot.efi and also typically (see below) ext4_x64.efi to the config.plist Drivers section.
  • Make sure RequestBootVarRouting and LauncherOption are enabled in config.plist; it is also recommended to enable HideAuxiliary in order to hide older Linux kernels except when required (they are added as auxiliary entries and so may then be shown by pressing the 2 key in the OpenCore boot menu).
  • Install Linux as normal if this has not been done earlier – OpenLinuxBoot is not involved in this stage.
  • Reboot into OpenCore: the installed Linux distribution should just appear and boot directly from OpenCore when selected, which it does without chainloading via GRUB.

If OpenCore has already been manually set up to boot Linux, e.g. via BlessOverride or via Entries then then these settings may be removed so that the Linux distribution is not displayed twice in the boot menu.

It is recommended to install Linux with its default bootloader, even though this will not be actively used when booting via OpenLinuxBoot. This is because OpenLinuxBoot has to detect the correct kernel options to use, and does so by looking in files left by the default bootloader. If no bootloader was installed (or these options cannot be found) booting is still possible, but the correct boot options must be manually specified before OpenLinuxBoot will attempt to start the distro.

OpenLinuxBoot typically requires filesystem drivers that are not available in firmware, such as EXT4 and BTRFS drivers. These drivers can be obtained from external sources. Drivers tested in basic scenarios can be downloaded from OcBinaryData. Be aware that these drivers are not tested for reliability in all scenarious, nor did they undergo tamper-resistance testing, therefore they may carry potential security or data-loss risks.

Most Linux distros require the ext4_x64 driver, a few may require the btrfs_x64 driver, and a few may require no additional file system driver: it depends on the filesystem of the boot partition of the installed distro, and on what filesystems are already supported by the system’s firmware. LVM is not currently supported - this is because it is not believed that there is currently a stand-alone UEFI LVM filesystem driver.

Be aware of the SyncRuntimePermissions quirk, which may need to be set to avoid early boot failure (typically halting with a black screen) of the Linux kernel, due to a firmware bug of some firmware released after 2017. When present and not mitigated by this quirk, this affects booting via OpenCore with or without OpenLinuxBoot.

After installing OpenLinuxBoot, it is recommended to compare the options shown in the OpenCore debug log when booting (or attempting to boot) a given distro against the options seen using the shell command cat /proc/cmdline when the same distro has been booted via its native bootloader. In general (for safety and security of the running distro) these options should match, and if they do not it is recommended to use the driver arguments below (in particular LINUX_BOOT_ADD_RO, LINUX_BOOT_ADD_RW, autoopts:{PARTUUID} and autoopts) to modify the options as required.

Note however that the following differences are normal and do not need to be fixed:

  • If the default bootloader is GRUB then the options generated by OpenLinuxBoot will not contain a BOOT_IMAGE=... value where the GRUB options do, and will contain an initrd=... value where the GRUB options do not.
  • OpenLinuxBoot uses PARTUUID rather than filesystem UUID to identify the location of initrd, this is by design as UEFI filesystem drivers do not make Linux filesystem UUID values available.
  • Less important graphics handover options (such as discussed in the Ubuntu example given in autoopts below) will not match exactly, this is not important as long as distro boots successfully.

If using OpenLinuxBoot with Secure Boot, users may wish to use the shim-to-cert.tool included in OpenCore utilities, which can be used to extract the public key needed to boot a distro’s kernels directly, as done when using OpenCore with OpenLinuxBoot, rather than via GRUB shim. For non-GRUB distros, the required public key must be found by user research.

Configuration

The default parameter values should work well with no changes under most circumstances, but if required the following options for the driver may be specified in UEFI/Drivers/Arguments:

  • flags

    • Default: all flags are set except the following:

      • LINUX_BOOT_ADD_RW,
      • LINUX_BOOT_LOG_VERBOSE and
      • LINUX_BOOT_ADD_DEBUG_INFO.

    Available flags are:

    • 0x00000001 (bit 0) — LINUX_BOOT_SCAN_ESP, Allows scanning for entries on EFI System Partition.
    • 0x00000002 (bit 1) — LINUX_BOOT_SCAN_XBOOTLDR, Allows scanning for entries on Extended Boot Loader Partition.
    • 0x00000004 (bit 2) — LINUX_BOOT_SCAN_LINUX_ROOT, Allows scanning for entries on Linux Root filesystems.
    • 0x00000008 (bit 3) — LINUX_BOOT_SCAN_LINUX_DATA, Allows scanning for entries on Linux Data filesystems.
    • 0x00000080 (bit 7) — LINUX_BOOT_SCAN_OTHER, Allows scanning for entries on file systems not matched by any of the above.

    The following notes apply to all of the above options:

    Note 1: Apple filesystems APFS and HFS are never scanned.

    Note 2: Regardless of the above flags, a file system must first be allowed by Misc/Security/ScanPolicy before it can be seen by OpenLinuxBoot or any other OC_BOOT_ENTRY_PROTOCOL driver.

    Note 3: It is recommended to enable scanning LINUX_ROOT and LINUX_DATA in both OpenLinuxBoot flags and Misc/Security/ScanPolicy in order to be sure to detect all valid Linux installs, since Linux boot filesystems are very often marked as LINUX_DATA.

    • 0x00000100 (bit 8) — LINUX_BOOT_ALLOW_AUTODETECT, If set allows autodetecting and linking vmlinuz* and init* ramdisk files when loader/entries files are not found.
    • 0x00000200 (bit 9) — LINUX_BOOT_USE_LATEST, When a Linux entry generated by OpenLinuxBoot is selected as the default boot entry in OpenCore, automatically switch to the latest kernel when a new version is installed.

    When this option is set, an internal menu entry id is shared between kernel versions from the same install of Linux. Linux boot options are always sorted highest kernel version first, so this means that the latest kernel version of the same install always shows as the default, with this option set.

    Note: This option is recommended on all systems.

    • 0x00000400 (bit 10) — LINUX_BOOT_ADD_RO, This option applies to autodetected Linux only (i.e. not to BLSpec or Fedora-style distributions which have /loader/entries/*.conf files). Some distributions run a filesystem check on loading which requires the root filesystem to initially be mounted read-only via the ro kernel option, which requires this option to be added to the autodetected options. Set this bit to add this option on autodetected distros; should be harmless but very slightly slow down boot time (due to requried remount as read-write) on distros which do not require it. When there are multiple distros and it is required to specify this option for specific distros only, use autoopts:{PARTUUID}+=ro to manually add the option where required, instead of using this flag.
    • 0x00000800 (bit 11) — LINUX_BOOT_ADD_RW, Like LINUX_BOOT_ADD_RO, this option applies to autodetected Linux only. It is not required for most distros (which usually require either ro or nothing to be added to detected boot options), but is required on some Arch-derived distros, e.g. EndeavourOS. When there are mul- tiple distros and it is required to specify this option for specific distros only, use autoopts:{PARTUUID}+=rw to manually add the option where required, instead of using this flag. If this option and LINUX_BOOT_ADD_RO are both specified, only this option is applied and LINUX_BOOT_ADD_RO is ignored.
    • 0x00002000 (bit 13) — LINUX_BOOT_ALLOW_CONF_AUTO_ROOT, In some instances of BootLoaderSpecByDefault in combination with ostree, the /loader/entries/*.conf files do not specify a required root=... kernel option – it is added by GRUB. If this bit is set and this situation is detected, then automatically add this option. (Required for example by Endless OS.)
    • 0x00004000 (bit 14) — LINUX_BOOT_LOG_VERBOSE, Add additional debug log info about files encountered and autodetect options added while scanning for Linux boot entries.
    • 0x00008000 (bit 15) — LINUX_BOOT_ADD_DEBUG_INFO, Adds a human readable file system type, followed by the first eight characters of the partition’s unique partition uuid, to each generated entry name. Can help with debugging the origin of entries generated by the driver when there are multiple Linux installs on one system.

    Flag values can be specified in hexadecimal beginning with 0x or in decimal, e.g. flags=0x80 or flags=128. It is also possible to specify flags to add or remove, using syntax such as flags+=0xC000 to add all debugging options or flags-=0x400 to remove the LINUX_BOOT_ADD_RO option.

  • autoopts:{PARTUUID}[+]="{options}" - Default: not set.

    Allows manually specifying kernel options to use in autodetect mode for a given partition only. Replace the text {PARTUUID} with the specific partition UUID on which the kernels are stored (in normal layout, the partition which contains /boot), e.g. autoopts:11223344-5566-7788-99aa-bbccddeeff00+="vt.handoff=7". If specified with += then these options are used in addition to any autodetected options, if specified with = they are used instead. Used for autodetected Linux only – values specified here are never used for entries created from /loader/entries/*.conf files.

    Note: The PARTUUID value to be specified here is typically the same as the PARTUUID seen in root=PARTUUID=... in the Linux kernel boot options (view using cat /proc/cmdline). Alternatively, and for more advanced scenarios, it is possible to examine how the distro’s partitions are mounted using the Linux mount command, and then find out the partuuid of relevant mounted partitions by examining the output of ls -l /dev/disk/by-partuuid.

  • autoopts[+]="{options}" - Default: None specified.

    Allows manually specifying kernel options to use in autodetect mode. The alternative format autoopts:{PARTUUID} is more suitable where there are multiple distros, but autoopts with no PARTUUID required may be more convenient for just one distro. If specified with += then these are used in addition to autodetected options, if specified with = they are used instead. Used for autodetected Linux only – values specified here are never used for entries created from /loader/entries/*.conf files.

    As example usage, it is possible to use += format to add a vt.handoff options, such as autopts+="vt.handoff=7" or autopts+="vt.handoff=3" (check cat /proc/cmdline when booted via the distro’s default bootloader) on Ubuntu and related distros, in order to add the vt.handoff option to the auto-detected GRUB defaults, and avoid a flash of text showing before the distro splash screen.

Additional information

OpenLinuxBoot can detect the loader/entries/*.conf files created according to the Boot Loader Specification or the closely related systemd BootLoaderSpecByDefault. The former is specific to systemd-boot and is used by Arch Linux, the latter applies to most Fedora-related distros including Fedora itself, RHEL and variants.

Where the above files are not present, OpenLinuxBoot can autodetect and boot {boot}/vmlinuz* kernel files directly. It links these automatically – based on the kernel version in the filename – to their associated {boot}/init* ramdisk files. This applies to most Debian-related distros, including Debian itself, Ubuntu and variants.

When autodetecting in /boot as part of the root filesystem, OpenLinuxBoot looks in /etc/default/grub for kernel boot options and /etc/os-release for the distro name. When autodetecting in a standalone boot partition (i.e. when /boot has its own mount point), OpenLinuxBoot cannot autodetect kernel arguments and all kernel arguments except initrd=... must be fully specified by hand using autoopts=... or autoopts:{partuuid}=... (+= variants of these options will not work, as these only add additional arguments).

BootLoaderSpecByDefault (but not pure Boot Loader Specification) can expand GRUB variables in the *.conf files – and this is used in practice in certain distros such as CentOS. In order to handle this correctly, when this situation is detected OpenLinuxBoot extracts all variables from {boot}/grub2/grubenv and also any unconditionally set variables from {boot}/grub2/grub.cfg, and then expands these where required in *.conf file entries.

The only currently supported method of starting Linux kernels relies on their being compiled with EFISTUB. This applies to almost all modern distros, particularly those which use systemd. Note that most modern distros use systemd as their system manager, even though most do not use systemd-boot as their bootloader.

systemd-boot users (probably almost exclusively Arch Linux users) should be aware that OpenLinuxBoot does not support the systemd-boot–specific Boot Loader Interface; therefore efibootmgr rather than bootctl must be used for any low-level Linux command line interaction with the boot menu.