Installing GRUB for a New Custom-Created Linux OS (Yocto) on Partitioned sda

Installing GRUB on a custom Yocto-generated Linux OS requires mounting the target partitions, binding essential filesystems like /proc and /sys, and using grub-install with the correct device path. This process ensures the bootloader is correctly written to the MBR or EFI System Partition, allowing the BIOS or UEFI firmware to locate and load your kernel.

Preparing the Target Environment

Before you can install GRUB, you must ensure that the root filesystem of your new Yocto image is accessible from your host machine. If you are working directly on the target hardware, this step is implicit, but for cross-compilation or chroot environments, manual setup is critical. Start by identifying the partition layout of your sda drive using lsblk or fdisk -l. You typically need at least two partitions: one for the boot files (often /dev/sda1) and one for the root filesystem (/dev/sda2). Mount the root filesystem first. Use the command mount /dev/sda2 /mnt assuming sda2 is your root partition. Next, mount the boot partition if it exists separately. For example, mount /dev/sda1 /mnt/boot. If your system uses an EFI System Partition (ESP) instead of a traditional boot partition, mount it to /mnt/boot/efi. It is crucial that these mounts are active before proceeding, as GRUB needs to write configuration files and binary blobs to these locations. If you are building a minimal Yocto image, you might not have standard directories like /dev, /proc, or /sys populated. You must bind-mount these virtual filesystems to make the environment functional for package installation tools. Execute the following commands to create and bind these directories:

mkdir -p /mnt/dev
mount --bind /dev /mnt/dev
mount --bind /proc /mnt/proc
mount --bind /sys /mnt/sys

This step is vital because many bootloader installation scripts attempt to access device nodes or kernel parameters during the installation process. Without these bindings, grub-install may fail silently or throw errors about missing devices.

Installing the GRUB Binary

With the filesystems mounted, you are ready to install the GRUB binaries. The method differs slightly depending on whether your target hardware uses Legacy BIOS or UEFI. For Legacy BIOS systems, you install GRUB directly to the disk's Master Boot Record (MBR). The command structure is grub-install --target=i386-pc /dev/sda. Note that you specify the disk device /dev/sda, not a specific partition like /dev/sda1. This writes the bootloader code to the beginning of the drive where the BIOS looks for the boot signature. For UEFI systems, the process involves targeting the EFI System Partition. You must specify the directory where the ESP is mounted using the --efi-directory flag and set the target architecture. A typical command would look like grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB. Ensure that the /boot/efi directory contains a valid FAT32 filesystem, as GRUB requires this format for UEFI compatibility. During installation, GRUB will copy its modules and core images to the boot partition. If you encounter errors related to "device map" or "fs_uuid," verify that your fstab entries in the target image are correct or use UUIDs instead of device names to avoid ambiguity. After successful installation, you should see output confirming that the installation was complete and no errors were reported.

Generating Configuration Files

Installing the binary is only half the battle; you must also generate a configuration file that tells GRUB which kernel to load. In a Yocto environment, this is often done using grub-mkconfig or by manually creating grub.cfg. If your image includes the grub-utils package, running grub-mkconfig -o /boot/grub/grub.cfg will automatically detect kernels and initramfs images. However, minimal Yocto builds often exclude these utilities to save space. In such cases, you must create grub.cfg manually. Open the file at /mnt/boot/grub/grub.cfg (or /mnt/boot/efi/grub/grub.cfg for UEFI) and define the necessary variables. You need to set the set root variable to point to your boot partition, for example, set root=(hd0,msdos1) for BIOS or set root=hd0,gpt1 for GPT disks. Then, define the kernel line using linux /vmlinuz root=/dev/sda2 rw and the initramfs line using initrd /initramfs.img. Ensure that the kernel and initramfs filenames match those generated by your Yocto build. You can check the contents of the boot partition using ls /mnt/boot to confirm the exact names. Incorrect paths here are the most common cause of boot failures after a successful GRUB installation.

Verifying the Boot Process

Once the configuration is in place, unmount the filesystems to ensure all data is flushed to disk. Use umount -R /mnt to recursively unmount all bound mounts. Remove the media and reboot the target machine. Watch the BIOS/UEFI POST screen to ensure it recognizes the new boot device. If the system boots into your Yocto Linux OS, the installation was successful. If the system fails to boot, refer to our guide on BIOS won't recognize bootloader: Troubleshooting Guide to diagnose firmware-level issues. Additionally, if you are dealing with dual-boot scenarios or menu visibility issues, check Fixing Lubuntu 16.04 - Windows 10 Not Showing in GRUB Menu for relevant configuration adjustments.

Frequently Asked Questions

What if my Yocto image does not include grub-mkconfig?

You must manually create the grub.cfg file in the boot directory. Define the root device, kernel path, and initramfs path explicitly within the file to ensure GRUB knows what to load at startup.

Why does grub-install fail with "device not found" errors?

This usually happens because the virtual filesystems like /dev and /sys are not bind-mounted in your chroot environment. Ensure you run mount --bind for these directories before invoking the installation command.

Can I use GRUB on a USB stick created with Yocto?

Yes, but you must specify the USB device (e.g., /dev/sdb) instead of /dev/sda during installation. Also, ensure the USB stick is formatted with a compatible filesystem like FAT32 for UEFI or ext4 for BIOS.

How do I update GRUB after changing the kernel version?

If you use grub-mkconfig, simply re-run the command to regenerate the config. If you edited grub.cfg manually, you must update the kernel filename and potentially the root UUID in the configuration file to reflect the new build.

Is it safe to install GRUB over an existing bootloader?

It is generally safe, but it will overwrite the existing MBR or EFI entries. Always back up your current boot sector or EFI variables before proceeding, especially if you are dual-booting with another operating system.