Ventoy Boot Conf Replace Plugin

When we booting some Linux distros, sometimes we need to add or modify the boot options for special hardware or some other purpose.
These boot options are generally written in the bootloader configuration files, such as isolinux.cfg, grub.cfg, etc.

Currently, we can do this by the following two methods:
1. Press Tab or e to enter the boot menu editing mode and modify the options.
    But this is one-time effective and needed for every boot.
2. Modify the configuration file and make a new ISO file.
    This is more troublesome and you have to make a new ISO file again once you update the boot option.

With this plugin, you can specify a new configuration file to dynamically replace the original configuration file at boot time.
The replacement is dynamically and temporary, the original ISO file will not be really modified.
So you can change the boot options easily, no need to make new ISO file and no need to do it manually every time.

• Json Configuration

Recommend to use VentoyPlugson, a GUI ventoy.json configurator. Refer VentoyPlugson
A conf_replace array is defined in /ventoy/ventoy.json for this plugin.

{
    "conf_replace": [
        {
            "iso": "/CentOS-7-x86_64-DVD-1908.iso",
            "org": "/isolinux/isolinux.cfg",
            "new": "/ventoy/centos.cfg"
        },
        {
            "iso": "/ubuntu-20.04-desktop-amd64.iso",
            "org": "/isolinux/txt.cfg",
            "new": "/ventoy/ubuntu.cfg"
        }
    ]
}

MUlti-Mode Option is supported, so it can be specified separately for different BIOS mode, for example:

{
    "conf_replace_legacy": [
        {
            "iso": "/CentOS-7-x86_64-DVD-1908.iso",
            "org": "/isolinux/isolinux.cfg",
            "new": "/ventoy/centos_isolinux.cfg"
        }
    ],

    "conf_replace_uefi": [
        {
            "iso": "/CentOS-7-x86_64-DVD-1908.iso",
            "org": "/EFI/BOOT/grub.cfg",
            "new": "/ventoy/centos_grub.cfg"
        }
    ]
}

• Notes

1. Only ISO files in iso9660 format are supported
So windows iso files (UDF format) are not supported.


2. The file replacement is virtual and will not really modify the ISO file in disk


3. The replacement only take effect during boot phase.


4. User must ensure that the new configuration file is valid
Ventoy will only replace the file and will not check its content.


5. All the paths are case-sensitive. The path of org must be the same with it parsed in grub2.
You can follow the steps to check the path of org. Press c to enter grub shell in Ventoy boot menu and run commands as follows:


loopback viso $vtoy_iso_part/manjaro-xfce-20.1.2-201019-linux58.iso
ls (viso)/
ls (viso)/boot/
ls (viso)/boot/grub/

6. Only support normal boot mode. Will not take affect in memdisk/grub2 mode.

• Multi-Mode

Supported. You can set different configurations for different BIOS mode. Please refer Multi-Mode Option for details.

• Special option for systemd-boot

Most type of Linux distros use grub2 in UEFI mode, but some distros (e.g. Archlinux) use systemd-boot as the bootloader in UEFI mode. systemd-boot use a special method and also we need a special process for it.
How to check whether the ISO file use systemd-boot as the bootloader in UEFI mode?
Generally speaking, if there exist a /loader/entries directory in the ISO file, it is.
The special process is very simple, just add an integer option img as follows:

{
    "conf_replace": [
        {
            "iso": "/archlinux-2021.10.01-x86_64.iso",
            "org": "/loader/entries/03-archiso-x86_64-ram-linux.conf",
            "new": "/ventoy/03-archiso-x86_64-ram-linux-custom.conf",
            "img": 1
        }
    ]
}

In one word, if you want to replace config file under /loader/entries directory, you need img option.

There is a comment about this in github, you can refer #1170 if you are interested.

• Replace more that one files in an ISO file.

Since Ventoy 1.0.78, you can replace at most 2 configuration files in an ISO file. (only 1 file supported in previous release).
You need to write 2 replace entries in ventoy.json as follows:

{
    "conf_replace": [
        {
            "iso": "/debian-10.6.0-amd64-DVD-1.iso",
            "org": "/isolinux/isolinux.cfg",
            "new": "/ventoy/new_isolinux.cfg"
        },
        {
            "iso": "/debian-10.6.0-amd64-DVD-1.iso",
            "org": "/isolinux/menu.cfg",
            "new": "/ventoy/new_menu.cfg"
        }
    ]
}