Variable Expansion Syntax for Ventoy Auto-Installation Scripts: A Complete Guide

Ventoy auto-installation scripts use the syntax $$VT_VARIABLE_NAME$$ where the variable name is enclosed in double dollar signs, processed by the vtoyexpand binary during boot to dynamically insert disk names, sizes, and other system values.

Ventoy's auto-install feature allows you to automate OS deployments by providing plain-text configuration files that adapt to the target hardware at boot time. According to the ventoy/Ventoy source code, this dynamic behavior is achieved through a specialized variable expansion system that replaces placeholders with computed values based on the current system's disk topology.

Ventoy Variable Expansion Syntax

The fundamental syntax for variable expansion follows a strict double-dollar notation:

$$VT_VARIABLE_NAME$$

This pattern must begin with $$VT_ and end with $$. The variable name between these delimiters determines what value gets substituted during the boot process. For example, $$VT_LINUX_DISK_MAX_SIZE$$ would be replaced with the device name of the largest disk detected on the system.

How Variable Expansion Works in Ventoy

The expansion process involves two core components in the Ventoy source tree: a shell script that detects placeholders and a C binary that performs the actual substitution.

Detection Phase

The script IMG/cpio/ventoy/hook/default/auto_install_varexp.sh scans the autoinstall file for any placeholder containing the substring $$VT_. If detected, it triggers the expansion workflow:

if grep -q '\$\$VT_' /ventoy/autoinstall; then
    vlog "======== auto install variables expansion ======="
    vtoyexpand "$1" "$VTOYDISK"
fi

This check occurs early in the boot process to determine whether variable processing is required before the installation begins.

Parsing and Replacement

When placeholders are detected, the script invokes the vtoyexpand binary (compiled from VtoyTool/vtoyexpand.c). The binary processes the autoinstall file line by line, identifying delimiters using strstr:

start = strstr(line, "$$VT_");          // find opening delimiter
end   = strstr(start + 5, "$$");       // find closing delimiter

if (start && end) {
    *start = 0;                     // write part before placeholder
    fprintf(fout, "%s", line);
    *end = 0;                       // isolate placeholder name
    expand_var(start + 2, value, sizeof(value));
    fprintf(fout, "%s", value);     // write expanded value
    fprintf(fout, "%s", end + 2);   // write rest of line
}

The expand_var() function in vtoyexpand.c (lines 456-511) contains the logic for mapping variable names to their computed values.

Supported Variables for Auto-Installation

The Ventoy source code defines a fixed set of variable names in the expand_var() function. These variables enable dynamic disk selection without hardcoding device names:

• VT_LINUX_DISK_SDX_1ST_NONVTOY – Resolves to the first SD-X style device (e.g., sda, sdb) that is not the Ventoy boot device
• VT_LINUX_DISK_SDX_1ST_NONUSB – Resolves to the first SD-X device that is not attached via USB
• VT_LINUX_DISK_MAX_SIZE – Resolves to the device name with the largest storage capacity
• VT_LINUX_DISK_CLOSEST_ – Resolves to the disk whose size is closest to the specified <GB> value (e.g., $$VT_LINUX_DISK_CLOSEST_100$$ finds the disk nearest to 100 GiB)

If a placeholder does not match any known variable in the source code, Ventoy leaves it unchanged in the output file.

Practical Examples

Basic Syntax in Kickstart Files

When creating an unattended installation for Red Hat-based systems, you can embed Ventoy variables directly in the kickstart file:

# Autoinstall configuration for Rocky Linux

install
url --url="http://mirror.example.com/rocky/9/BaseOS/x86_64/os/"
autopart --type=lvm

%pre

# Dynamically select the largest available disk

DISK="$$VT_LINUX_DISK_MAX_SIZE$$"
echo "Selected disk: $DISK"
%end

At boot time, Ventoy replaces $$VT_LINUX_DISK_MAX_SIZE$$ with the actual device node (e.g., sda or nvme0n1) before the installer reads the file.

Selecting Non-USB Disks

For installations where you must avoid USB drives (common when the Ventoy media itself is USB), use the NONUSB variable:

part / --fstype=ext4 --onpart=$$VT_LINUX_DISK_SDX_1ST_NONUSB$$1

This ensures the installation targets the first internal SATA or NVMe disk rather than any USB storage device present during installation.

Extending Variable Expansion

While Ventoy ships with predefined variables, the source architecture allows for extension. To add a custom variable, you would modify the expand_var() function in VtoyTool/vtoyexpand.c:

else if (strcmp(var, "VT_CUSTOM_HOSTNAME") == 0) {
    snprintf(value, len, "auto-host-%s", get_disk_serial());
    return 0;
}

After recompiling vtoyexpand and rebuilding the Ventoy image, your autoinstall files could use $$VT_CUSTOM_HOSTNAME$$ to insert dynamically generated hostnames based on hardware identifiers.

Summary

• Syntax: Use $$VT_VARIABLE_NAME$$ with double dollar signs as opening and closing delimiters
• Detection: The auto_install_varexp.sh script scans for $$VT_ patterns before installation begins
• Processing: The vtoyexpand binary performs actual substitution by parsing VtoyTool/vtoyexpand.c
• Available variables: Include disk selection helpers like VT_LINUX_DISK_MAX_SIZE and VT_LINUX_DISK_SDX_1ST_NONVTOY
• Fallback behavior: Unknown variables remain unchanged in the output file
• Extensibility: New variables can be added by extending the expand_var() function in the source code

Frequently Asked Questions

What is the exact syntax for Ventoy auto-installation variables?

The exact syntax is $$VT_VARIABLE_NAME$$ where VARIABLE_NAME is replaced with one of the supported identifiers defined in the Ventoy source code. Both the opening $$VT_ and closing $$ are required for the vtoyexpand binary to recognize and process the placeholder.

Which file handles the variable expansion in Ventoy?

Variable expansion is handled by two files in the ventoy/Ventoy repository: IMG/cpio/ventoy/hook/default/auto_install_varexp.sh detects placeholders and triggers processing, while VtoyTool/vtoyexpand.c contains the actual implementation including the expand_var() function that maps variable names to system values.

Can I use custom variables in Ventoy auto-install scripts?

Yes, but it requires modifying the source code. You must add a new case in the expand_var() function within VtoyTool/vtoyexpand.c, recompile the vtoyexpand binary, and rebuild the Ventoy image. Without source modification, only the built-in variables are recognized.

What happens if I use an unrecognized variable name?

If the variable name between the delimiters does not match any case in the expand_var() function, Ventoy leaves the placeholder unchanged in the autoinstall file. For example, $$VT_UNKNOWN_VAR$$ would remain as literal text in the output rather than being replaced with a value.

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