• 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!

  • 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! :)

  • Hello again!

    Here’s another example of how to use the downloaded ISO file directly in a menuentry.
    This may be slightly more useful then the earlier one, since it uses UUIDs instead of labels.

    menuentry 'Boot from file /AllMyISOs/antergos-minimal-18.5-x86_64.iso' {
        set isofile=/AllMyISOs/antergos-minimal-18.5-x86_64.iso
        search --no-floppy --set=root --file $isofile
        probe -u $root --set=uuid
        set img_dev=/dev/disk/by-uuid/$uuid
        loopback loop $isofile
        linux (loop)/arch/boot/vmlinuz img_dev=$img_dev img_loop=$isofile
        initrd (loop)/arch/boot/archiso.img

    Note that the ISO file needs to be stored into some partition that grub can read. It can be under a subdirectory, but you need to specify the full path to it (starting from the root directory of the drive where the ISO exists).
    For example, if you stored the ISO file into the /AllMyISOs directory on a USB drive, then the path in the menuentry defines the location correctly. You don’t need to give any info about the drive, just the full path within then drive in the line

    set isofile=/AllMyISOs/...


    Please note that this is a directly useful example. It can help you easily boot your machine up if the normal boot method is failing, allowing you to check and fix the issues. And the minimal installer ISO doesn’t take huge amounts of space on modern hard disks (it is currently 745MB). And it is handy, even if you don’t have a USB stick available.

    Of course this doesn’t help in every possible problem, but IMHO it can help in most cases. And I’m using this menuentry myself on all of my Antergos machines! ;)

  • i just was curious and add this to my grub.cfg, but with the UUID i get not booted up, it searches also for /dev/disk/by-label waiting 30 seconds and prompt to roorfs…

    and it is not clerar where it should get uuids from do i need to add them or is the entry searching for it?

  • @joekamprad
    The menuentry searches the $isofile file (you must have a correct path there), and when it finds it, it uses the containing disk as as $root. Then it uses the $root variable to search for the UUID of the containing disk.

    So you don’t need to give any UUID info, just the ISO file name and its path on the containing disk.

    So the problem may be the path to the ISO file is not correct.
    Easiest way is to move the ISO file into the root directory of a disk (any disk basically), and set the isofile variable as:

    set isofile=/antergos-minimal-18.5-x86_64.iso
  • O.K. i do understand now, and indeed i can boot with anergos iso, but not with my antergos-rescue iso…

  • @joekamprad
    Yes I have the same problem with the rescue ISO. Don’t know why.

    But there is another ISO menuentry example on this thread that uses labels (and contains an error in the isofile path, it should have “/” in the beginning), have you tried that?

    I can try it again here, just a moment, I’ll have to download it first…

  • @joekamprad
    While I’m downloading, could you put some echo statements inside the menuentry to see what is does and how far it gets?
    Something like

    echo "isofile = $isofile"


  • I tried and the rescue ISO failed.
    It must be somehow in the structure of the ISO, there may be something different.
    I’ll check here if I can find something.

  • Maybe it is the kernel parameters for the rescue ISO that are missing?
    Just guessing, since the rescue ISO has booted successfully when burned onto a USB stick.

  • @manuel the structure is almost the same, as it is build from the same source, but bootmenu has other entries…with different kernel parameters…

    0_1527713176200_Bildschirmfoto vom 2018-05-30 22-44-46.png

grub127 examples1 custom.cfg1 Posts 36Views 5198
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.