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

> Learn how Ventoy's boot configuration replacement plugin modifies boot parameters by swapping ISO config files at boot time. Customize OS boot options without changing ISOs.

- Repository: [longpanda/Ventoy](https://github.com/ventoy/Ventoy)
- Tags: internals
- Published: 2026-03-01

---

**Ventoy's boot configuration replacement plugin intercepts configuration files (such as [`grub.cfg`](https://github.com/ventoy/Ventoy/blob/main/grub.cfg) or [`boot.cfg`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) configuration file. The function `ventoy_plugin_conf_replace_entry()` in [`GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/ventoy_plugin.c`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/ventoy.json) file in the Ventoy partition. The following example replaces the GRUB configuration inside an Ubuntu ISO:

```json
{
    "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:

```grub

# 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`](https://github.com/ventoy/Ventoy/blob/main/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`](https://github.com/ventoy/Ventoy/blob/main/grub.cfg), [`boot.cfg`](https://github.com/ventoy/Ventoy/blob/main/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.