How Ventoy's Boot Configuration Replacement Plugin Modifies Boot Parameters for OS Images

Ventoy's boot configuration replacement plugin intercepts configuration files (such as grub.cfg or boot.cfg) inside ISO images at boot time and substitutes them with user-provided alternatives, effectively modifying kernel boot parameters without altering the original ISO file.

Ventoy is an open-source bootable USB solution that allows users to boot multiple ISO images from a single drive. Its boot configuration replacement plugin enables dynamic modification of internal configuration files within those ISO images. This capability allows users to customize kernel command-line arguments, initrd paths, and other boot parameters while maintaining the integrity of the original read-only ISO media.

How the Boot Configuration Replacement Plugin Works

The plugin operates through a five-phase pipeline implemented across the Ventoy GRUB2 module source files. When a user boots an ISO configured for replacement, Ventoy intercepts configuration files in memory before the kernel receives them.

Phase 1: Parsing the Plugin Configuration

When Ventoy initializes, it reads the user-supplied ventoy.json configuration file. The function ventoy_plugin_conf_replace_entry() in GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c parses each JSON object containing iso, org, new, and optional img fields.

This function constructs a linked list of replacement entries stored in the global variable g_conf_replace_head. Each node contains the target ISO path, the original file path inside the ISO, and the path to the replacement file on the USB drive.

Phase 2: Validating Replacement Files

Before booting begins, ventoy_plugin_conf_replace_check() (also in ventoy_plugin.c) validates that the original file exists within the ISO structure and that the replacement file is accessible on the USB filesystem. The function verifies that the replacement file size does not exceed vtoy_max_replace_file_size.

If validation fails, error messages are printed to the console, but Ventoy typically allows the boot process to continue, falling back to the original configuration.

Phase 3: Selecting Replacements for the Current ISO

When the user executes the built-in GRUB command vt_select_conf_replace <iso_path> <iso_root>, Ventoy identifies which replacement entries apply to the currently selected ISO. This command, implemented in ventoy_cmd.c, locates the original file within the ISO to determine its sector offset.

For each applicable replacement, Ventoy records:

• g_conf_replace_node[i] – pointer to the configuration node
• g_conf_replace_offset[i] – ISO sector offset of the original file (adjusted by 2 bytes for alignment)
• g_conf_replace_new_buf[i] and g_conf_replace_new_len[i] – buffer containing the new file contents and its length

If the img flag is set, the function also registers a virtual image-replace entry in g_grub_param->img_replace[i] to handle binary image replacements.

Phase 4: Injecting Configuration Data into the Boot Image

During the final boot preparation, ventoy_linux_fill_virt_data() in ventoy_linux.c performs the actual injection. This function iterates through all active replacement entries (g_conf_replace_count).

For each valid entry where g_conf_replace_offset[i] > 0:

1. Calculates the number of 2 KiB sectors required for the new file (cpio_secs)
2. Writes the replacement data from g_conf_replace_new_buf[i] directly into the virtual boot image at the computed memory offset (override + offset)
3. Updates the virtual chunk metadata so the kernel perceives the modified file as part of the original initrd

When handling image replacements (indicated by the img flag), the function populates g_grub_param->img_replace[i].new_file_virtual_id, enabling subsequent boot stages (EDK2 firmware or Linux kernel) to resolve the replacement file's virtual identifier.

Technical Implementation Details

The boot configuration replacement plugin relies on several key data structures defined in ventoy_def.h. The conf_replace structure stores the ISO identifier, original file path, and replacement file path. Global arrays such as g_conf_replace_offset and g_conf_replace_new_buf manage the runtime state during the boot process.

The plugin integrates with Ventoy's virtual file system layer. By modifying the virtual RAM disk before the kernel decompresses it, the plugin ensures that the operating system receives the modified configuration transparently. This approach maintains the integrity of the original ISO while allowing dynamic parameter modification.

Configuration Examples

To use the boot configuration replacement plugin, create a ventoy.json file in the Ventoy partition. The following example replaces the GRUB configuration inside an Ubuntu ISO:

{
    "conf_replace": [
        {
            "iso": "/ubuntu.iso",
            "org": "/boot/grub/grub.cfg",
            "new": "/custom/ubuntu-grub.cfg",
            "img": 0
        }
    ]
}

After configuring the JSON file, use the following GRUB commands to activate the replacement during boot:

# Select the configuration replacement for the current ISO

vt_select_conf_replace /path/to/ubuntu.iso /

# Verify the replacement entries are loaded

vt_dump_conf_replace

The img parameter specifies whether the replacement targets a binary image (set to 1) or a text configuration file (set to 0).

Summary

• Ventoy's boot configuration replacement plugin enables dynamic modification of configuration files inside ISO images without altering the original media.
• The plugin parses ventoy.json via ventoy_plugin_conf_replace_entry() and stores replacement rules in a linked list headed by g_conf_replace_head.
• Validation occurs through ventoy_plugin_conf_replace_check(), ensuring target files exist and meet size constraints defined by vtoy_max_replace_file_size.
• The vt_select_conf_replace command prepares replacement data by mapping original file offsets and loading new content into buffers managed by g_conf_replace_new_buf and g_conf_replace_new_len.
• During boot, ventoy_linux_fill_virt_data() injects the replacement data into the virtual RAM disk, presenting modified boot parameters to the kernel while preserving the original ISO integrity.

Frequently Asked Questions

What file types can the Ventoy boot configuration replacement plugin modify?

The plugin can replace any file within an ISO image, including text configuration files like grub.cfg, boot.cfg, or .vcfg files, as well as binary images when the img flag is set to 1. The replacement occurs in memory before the kernel processes the initrd, making it transparent to the boot process.

Does the boot configuration replacement plugin modify the original ISO file on the USB drive?

No, the plugin operates entirely in memory. It uses Ventoy's virtual file system layer to intercept and replace file contents during the boot process. The original ISO image remains read-only and unmodified on the USB drive, ensuring data integrity and allowing the same ISO to be used with different configurations on subsequent boots.

How does Ventoy handle size limitations for replacement files?

Before booting, the ventoy_plugin_conf_replace_check() function validates that the replacement file size does not exceed vtoy_max_replace_file_size. If the replacement file is too large, the plugin logs an error to the console but typically allows the boot to continue using the original configuration file instead of the oversized replacement.

Can I use the boot configuration replacement plugin for UEFI boot images?

Yes, the plugin supports both legacy BIOS and UEFI boot environments. When the img flag is enabled, the plugin registers virtual image-replace entries in g_grub_param->img_replace[], which allows EDK2 firmware components to resolve the replacement file's virtual ID. This ensures that UEFI boot images can also benefit from dynamic configuration replacement.

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