How Ventoy Resolves the Configuration File Search Path When Multiple Config Files Exist

Ventoy implements a deterministic, priority-ordered search algorithm in INSTALL/grub/grub.cfg that iterates through a hard-coded list of candidate paths and stops at the first existing file, falling back to systemd-boot or Syslinux configurations only when no GRUB configuration is detected.

When booting from ISO images, the open-source multiboot tool Ventoy must determine which configuration file to load without assuming a single location. According to the ventoy/Ventoy repository source code, the bootloader resolves the configuration file search path through a deterministic algorithm that prioritizes conventional GRUB locations before attempting alternative bootloader formats.

The Deterministic Search Algorithm in INSTALL/grub/grub.cfg

The search logic is implemented in the install-time GRUB script at INSTALL/grub/grub.cfg. The algorithm follows a strict sequence:

1. Initialization: The flag vtback_cfg_find is reset to 0 at line 848.
2. Primary GRUB-CFG search: A for loop iterates over hard-coded candidate paths. The first file that exists (tested with -e) triggers configfile "$cfg" and breaks the loop (lines 848-855).
3. Fallback checks: If no GRUB config is found, Ventoy checks for systemd-boot environments (lines 857-865) and then Syslinux configurations (lines 869-877).
4. Final handling: If all searches fail, the script continues to the next boot entry (lines 879-880).

Priority Order of Configuration File Locations

The candidate list in the primary loop is ordered from most conventional to least common locations:

"/boot/grub/grub.cfg" \
"/EFI/BOOT/grub.cfg" \
"/EFI/debian/grub.cfg" \
"EFI/boot/grub.cfg" \
"efi/boot/grub.cfg" \
"/grub/grub.cfg" \
"EFI/BOOT/BOOTX64.conf"

Ventoy stops at the first file that returns true for the existence test -e. Consequently, if an ISO contains both /boot/grub/grub.cfg and /EFI/BOOT/grub.cfg, the former is chosen because it appears earlier in the list.

Fallback Mechanisms for Alternative Bootloaders

When the primary GRUB search returns no results (vtback_cfg_find remains 0), Ventoy executes secondary detection routines.

systemd-boot Detection

Ventoy checks for a systemd-boot environment by verifying the presence of loader/loader.conf and loader/entries. When detected, it invokes the vt_systemd_menu routine and sets vtback_cfg_find to indicate success (lines 857-865 in INSTALL/grub/grub.cfg).

Syslinux Configuration Fallback

If systemd-boot is not present, Ventoy looks for classic Syslinux configuration files such as isolinux/syslnx64.cfg or syslinux/porteus.cfg. Upon finding a valid file, it calls syslinux_configfile and marks the configuration as found (lines 869-877).

Integration with ventoy.json Plugin Configuration

Separate from the boot configuration search, Ventoy loads plugin settings from /ventoy/ventoy.json. In GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c (lines 2478-2483), the code opens this file using ventoy_grub_file_open, reads its content, and parses the JSON. If the file is missing, the function returns GRUB_ERR_NONE and continues booting without error. This follows the same "open-if-present-else-ignore" philosophy but does not interfere with the boot-config search order.

Practical Code Examples

Customizing the Search Order

To append a custom path to the existing candidate list, modify the for loop in INSTALL/grub/grub.cfg:

for cfg in "/boot/grub/grub.cfg" "/EFI/BOOT/grub.cfg" \
           "/EFI/debian/grub.cfg" "EFI/boot/grub.cfg" \
           "efi/boot/grub.cfg" "/grub/grub.cfg" \
           "EFI/BOOT/BOOTX64.conf" "/my/custom/path.cfg"; do
    if [ -e "$cfg" ]; then
        set vtback_cfg_find=1
        configfile "$cfg"
        break
    fi
done

Capturing the Chosen Configuration Path

To store the exact path of the selected configuration for debugging:

if [ -e "$cfg" ]; then
    set vtback_cfg_find=1
    set vt_chosen_cfg="$cfg"
    configfile "$cfg"
    break
fi

The variable $vt_chosen_cfg now holds the path that was loaded.

Adding a Custom Bootloader Fallback

Extend the secondary fallback block to support additional loaders:

if [ $vtback_cfg_find -eq 0 ]; then
    if [ -f (loop)/myloader/loader.cfg ]; then
        echo "Launching custom loader"
        configfile (loop)/myloader/loader.cfg
        set vtback_cfg_find=1
    fi
fi

Summary

• Ventoy uses a deterministic, ordered search through a hard-coded list of GRUB configuration paths in INSTALL/grub/grub.cfg.
• The algorithm stops at the first existing file using the -e test, ensuring predictable behavior regardless of how many configuration files exist in the ISO.
• If no GRUB config is found, Ventoy falls back to systemd-boot (via vt_systemd_menu) and then Syslinux (via syslinux_configfile) detection.
• The ventoy.json plugin file is loaded separately through ventoy_grub_file_open in ventoy_plugin.c and does not affect the boot configuration search priority.

Frequently Asked Questions

What happens if multiple GRUB configuration files exist in the same ISO?

Ventoy selects the first file that exists according to the priority list defined in INSTALL/grub/grub.cfg. If /boot/grub/grub.cfg and /EFI/BOOT/grub.cfg both exist, the former takes precedence because it appears earlier in the for loop iteration (lines 848-855).

Can I customize the configuration file search order?

Yes. You can modify the for cfg in … loop in INSTALL/grub/grub.cfg to add, remove, or reorder candidate paths. The search respects the first-match-wins principle, so placing a custom path earlier in the list ensures it takes priority over default locations.

How does Ventoy handle ISOs that use systemd-boot instead of GRUB?

If the primary GRUB search fails (vtback_cfg_find remains 0), Ventoy checks for systemd-boot markers (loader/loader.conf and loader/entries). When found, it invokes vt_systemd_menu to handle the boot process (lines 857-865), bypassing the need for a GRUB configuration file entirely.

Does the presence of ventoy.json affect which boot configuration is loaded?

No. The ventoy.json file is loaded independently by ventoy_plugin.c (lines 2478-2483) for plugin settings and follows a separate existence check. It does not influence the priority order or selection logic for GRUB, systemd-boot, or Syslinux configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}