• Grub boot examples: custom.cfg

    Hi all!
    I’d like to present some examples of grub configurations, since booting problems are quite common, and they often are quite easy to fix.

    You probably know about file /boot/grub/grub.cfg, where grub configurations are generated by the system. It contains boot menu entries that specify how to boot to different entries shown on the boot list when you start your Antergos system. For example, if you dual boot (e.g. Antergos and Windows), then all ways to boot to them are presented in grub.cfg.

    So grub.cfg is a generated file, and you should not really make modifications to that file, since they will be overwritten when the system generates the file again (e.g. when kernel is updated).

    There is another file, /boot/grub/custom.cfg, that grub boot process will read during boot. It may also contains those boot menu entries as grub.cfg. Those menu entries will be shown in the boot menu list after the menu entries of grub.cfg. File custom.cfg is not generated by the system, so it is up to you to decide its contents!

    You could, for example, copy some selected menu entries from grub.cfg to custom.cfg and modify them in custom.cfg if needed. The only restriction is that they must follow the same syntax as in grub.cfg. The syntax resembles bash syntax.

    The following posts on this thread will show some examples that I hope will be useful for either fixing problems or just learning more about booting with grub.

    And I’m not saying I know (even nearly) everything about this subject, but I have done my share of trial and error with it, as a user, but not a developer.

  • So here’s my first custom.cfg example. It is a bit advanced example (for a newcomer at least), but hopefully it can serve its purpose as an example.
    I have almost an exact copy of this in use on one of my systems, so it should work as-is (unless there are typos…).

    function common_stuff {
      set kernel="$1"  # linux or linux-lts
      set crypt_uuid=<your-crypt-device-partition-uuid>
      set boot_partition_label=AntergosBoot
      set root_partition_label=AntergosRoot
      set swap_partition_label=AntergosSwap
      search --no-floppy --set=root --label $boot_partition_label
      linux	  /vmlinuz-$kernel root=LABEL=$root_partition_label rw cryptdevice=/dev/disk/by-uuid/$crypt_uuid:cryptAntergos quiet resume=LABEL=$swap_partition_label
      initrd  /intel-ucode.img /initramfs-$kernel.img
    menuentry 'Antergos LTS' {
      common_stuff linux-lts
    menuentry 'Antergos' {
      common_stuff linux

    As you can see, custom.cfg file contains menu entries (starts with word menuentry). It may contain also other things, including variables, if clauses, and functions. Many things that are familiar from bash.

    Here we have two menu entries, ‘Antergos LTS’ and ‘Antergos’. They are simple, they just call a function common_stuff, with one parameter, the kernel (either linux-lts or linux).

    The function takes the given kernel parameter to a variable named kernel. Function gets the (positional) parameters as in bash, $1 is the first positional parameter. If there would be more parameters, the following parameters would be $2, $3, and so on.

    For recognizing disk partitions, the function uses partition labels and partition uuids. You may know about them from commands like blkid or gparted.

    The savedefault line means that when this entry is selected, it is preserved as the next default entry. It requires some support in file /etc/default/grub, namely settings


    The search command is used for finding the boot partition (it may be a separate partition, or typically inside the root partition.) Boot partition contains kernel boot files like vmlinuz-* and initramfs-*.

    The linux line tells the name of the kernel file and some additional kernel boot options like root=*, rw, quiet etc. In this particular example we have a cryptdevice option to tell the uuid of the encrypted partition.

    The initrd line tells the name of the initial ramdisk file, and the line also has Intel’s microcode file, which is meant for machines with Intel’s processor.

    This initrd line, especially the microcode part, is sometimes the cause of boot problems if you have other linux distributions on the same machine. This is because other distros fail to properly generate a boot menu entry for distros like Antergos. The workaround is simple, write a proper custom.cfg file into that booting distro - you can copy the Antergos menu entry from Antergos’s grub.cfg).

    So, what do you think about this example? Would you like to see some more examples? 🙂

  • A simple menu entry for booting to Antergos, should work in most cases. If not, please see Caveats below.
    This menu entry finds partition UUIDs based on an existing file /boot/vmlinuz-linux-lts.
    Probably needless to say, but you need to have linux-lts installed in order to boot with it.

    menuentry "Antergos LTS" {
        set kernel=linux-lts
        search --set --file /boot/vmlinuz-$kernel
        probe -u $root --set=uuid
        linux  /boot/vmlinuz-$kernel root=UUID=$uuid rw quiet
        initrd /boot/intel-ucode.img /boot/initramfs-$kernel.img

    So if you have trouble with grub about booting with LTS kernel, you can try this. Copy the menu entry above to file /boot/grub/custom.cfg, reboot, and select this new boot menu entry.

    And the above menuentry is easy to change to boot the default kernel: just set variable kernel to linux.


    • Note that this example assumes that the directory /boot does not refer to a mounted partition, but a normal directory. This is the case in most installations (unless you are an expert and know exactly what you are doing).
    • If you have other Arch based linux installations on the same machine, this menuentry may need more specific info to select the one you really want to boot.
  • Yes, more examples, as it’s easy to understand but with more examples, maybe you’ll cover every option to boot on a disaster scenario.

  • @manuel yea yea more!

    [updates once a week] = [90% less problems]
    how to add system logs:
    wget http://bit.ly/2GCG9k2 && sh 2GCG9k2

  • Don’t be alarmed of a Windows example! 😉
    Booting Windows 10 with /boot/grub/custom.cfg:

    menuentry "Windows 10" {
      set file=/EFI/Microsoft/Boot/bootmgfw.efi
      insmod fat
      search --set --file $file
      chainloader $file

    This may help if your Windows 10 is no more booting and grub-mkconfig is not able to solve the problem.

    Note that this also may have similar caveats as the previous example, if you have more than one Windows installation on your machine… 😈

  • And now, how to boot directly from a downloaded ISO file!

    No need to “burn” or extract anything, just use the plain downloaded ISO file as-is!
    This way you could e.g. install another Antergos system to your machine (i.e. multiboot).

    Note that the ISO file cannot be stored on the same disk as the to-be-installed system. The ISO file must be copied e.g. to a USB stick. Note: simply copied, not “burned”!

    Naturally, this system requires an existing Linux system, and modification of its /boot/grub/custom.cfg. It should work on an Antergos system, and probably on an Arch system. Others I haven’t tested, but I suspect this example does not work e.g. on Debian based systems.

    menuentry "Antergos installer ISO from a file" {
        set isofile=antergos-18.2-x86_64.iso # name of the ISO file
        search --set --file $isofile         # get $root of the $isofile partition
        probe -l $root --set=volumelabel     # get $volumelabel of the $root
        set img_dev=/dev/disk/by-label/$volumelabel
        loopback loop $isofile
        linux (loop)/arch/boot/vmlinuz img_dev=$img_dev img_loop=$isofile
        initrd (loop)/arch/boot/archiso.img

    Note that this example (with some variation) has already been presented on this forum.
    But I wanted to gather all grub examples into one place, being most useful this way! 🙂

  • @manuel said in Grub boot examples: custom.cfg:

    Don’t be alarmed of a Windows example! 😉
    Booting Windows 10 with /boot/grub/custom.cfg:

    menuentry "Windows 10" {
      set file=/EFI/Microsoft/Boot/bootmgfw.efi
      insmod fat
      search --set --file $file
      chainloader $file

    This may help if your Windows 10 is no more booting and grub-mkconfig is not able to solve the problem.

    Note that this also may have similar caveats as the previous example, if you have more than one Windows installation on your machine… 😈

    What is that ‘Windows’ you talk about?? Do you mean FreeBSD? It’s important to have an example of FreeBSD because it’s one of those I want to have around.

  • @casquinhas
    Sorry, I don’t have any FreeBSD system installed on any of my machines… 😞

    But, the example about “Antergos LTS” above should be possible to convert to support a FreeBSD system.

    If you have Antergos in control of the boot process, then just add that example with some FreeBSD modifications to /boot/grub/custom.cfg in Antergos.
    And if you can make it work, please share the new FreeBSD menuentry also here! 🙂

    This link may also provide some help: https://www.gnu.org/software/grub/manual/grub/grub.html

  • Hi all!

    In post nr 7 here there is an error: the isofile should be set like this:

    set isofile=/antergos-18.2-x86_64.iso

    Note the slash (/) in front of the ISO file name. The isofile variable needs to include the full path of the ISO file in the partition where it is.

    Sorry about that mistake! And thanks for the heads up to @jptsetung who noticed it! 🙂

grub90 custom.cfg1 examples1 Posts 10Views 181
Log in to reply
Bloom Email Optin Plugin

Looks like your connection to Antergos Community Forum was lost, please wait while we try to reconnect.