# Ventoy Administrator & Developer Guide

Ventoy is a cross-firmware, cross-architecture bootable USB tool that eliminates the traditional extract-and-write workflow for live media. Install Ventoy once to a USB drive, then copy ISO/WIM/IMG/VHD/VHDX/EFI files directly onto the data partition and boot them without extraction. The project is built around a heavily modified GRUB2 core, an EDK2-based UEFI application, a modified iPXE for network boot, and a modified wimboot for Windows PE — all coordinated by shell-based installers and a suite of C-language platform tools.

This guide is the operational and architectural reference for engineers who deploy, maintain, build, package, or extend Ventoy. It covers the full boot chain from firmware handoff through image selection and OS handover, every component in the 101-module codebase, the build system and cross-compilation toolchains, the plugin/configuration architecture, the security model including Secure Boot enrollment, and the distro hook system that provides compatibility with 900+ Linux/BSD/Windows distributions. A reader who finishes this guide should be able to rebuild Ventoy from a clean host, execute a corporate rollout across hundreds of machines, diagnose firmware-level boot failures, and navigate the 2,772-file source tree with confidence.

**Project vitals:**

| Field | Value |
|---|---|
| Author | longpanda ([email removed]) |
| Website | https://www.ventoy.net |
| License | GPLv3+ |
| Source commit | `de3e6c6` (2026-04-14) |
| Codebase size | 2,772 files, complexity score 280 (Large) |
| Language mix | C (core), Shell (installers/hooks), JSON (config/i18n) |
| Supported firmware | Legacy BIOS, UEFI (x86_64, IA32, ARM64, MIPS64EL) |
| Tested distros | 900+ (Linux, Windows, BSD, ChromeOS, Haiku, and others) |

---

## 2. Architecture Overview

### 2.1 High-Level System Diagram

```
 +---------------------------USB DRIVE----------------------------+
 |                                                                 |
 |  Partition 1: "Ventoy" (exFAT/NTFS/ext)                       |
 |  +-----------+  +-----------+  +-----------+  +-----------+   |
 |  | file1.iso |  | file2.wim |  | file3.vhd |  | file4.img |   |
 |  +-----------+  +-----------+  +-----------+  +-----------+   |
 |  /ventoy/ventoy.json    (optional plugin config)               |
 |  /ventoy/theme/         (optional GRUB theme)                  |
 |                                                                 |
 |  Partition 2: "VTOYEFI" (32MB FAT16)                           |
 |  /grub/grub.cfg         /grub/i386-pc/     /grub/x86_64-efi/  |
 |  /grub/arm64-efi/       /grub/mips64el-efi/                    |
 |  /EFI/BOOT/             /ventoy/           /tool/              |
 |  /ENROLL_THIS_KEY_IN_MOKMANAGER.cer                            |
 +-----------------------------------------------------------------+
 
 MBR/GPT Boot Sector
        |
        v
 +--- BIOS Path --------+    +---- UEFI Path -------------------+
 | MBR boot code         |    | Firmware loads EFI app from       |
 | loads GRUB2 core.img  |    | VTOYEFI partition                 |
 | (i386-pc)             |    | EDK2 Ventoy EFI → GRUB2 EFI     |
 +------------------------+    +------------------------------------+
        |                              |
        v                              v
 +--- GRUB2 (Modified) -------------------------------------------+
 | grub.cfg → enumerate ISOs → display menu                        |
 | User selects image → Ventoy GRUB commands load it               |
 +------------------------------------------------------------------+
        |                    |                    |
        v                    v                    v
   Linux/BSD ISO        Windows WIM          VHD/VHDX
   (loopback mount      (wimboot 2.7.3       (ventoy_vdisk
    + distro hook)       modified)            via disk map)
```

> [!NOTE]
> Ventoy's architecture is fundamentally a boot chain orchestrator. Every component — GRUB2, EDK2, iPXE, wimboot — is a fork of an upstream project with Ventoy-specific patches applied. The modifications are substantial (custom GRUB commands, EFI protocol handlers, disk virtualization layers) and cannot be trivially rebased onto newer upstream releases.

### 2.2 Boot Chain — BIOS Legacy Path

1. **MBR boot sector** executes, loads GRUB2 `core.img` from the gap between the MBR and the first partition (or from a dedicated boot image area)
2. **GRUB2 (i386-pc)** initializes with Ventoy-modified `grub_main()` that injects custom prefix/root handling via `ventoy_env_write_root()`
3. For disks exceeding BIOS addressing limits, `ventoy_legacy_limit_workaround()` activates: loads `ventoy.disk.img.xz` via loopback to work around INT13h constraints
4. **grub.cfg** on VTOYEFI partition runs, enumerating bootable files on the data partition
5. Menu is displayed; GRUB theme and language loaded via `vt_load_menu_lang`
6. On image selection, Ventoy GRUB modules handle the image type (ISO loopback, WIM chain, VHD map, etc.)
7. Control transfers to the target OS bootloader

### 2.3 Boot Chain — UEFI Path

1. **UEFI firmware** locates the FAT partition marked as EFI System Partition (VTOYEFI) and loads the Ventoy EFI application
2. **EDK2 Ventoy EFI application** (built from `EDK2/edk2_mod/` against edk2-stable201911) initializes:
   - `VDiskChain`: virtual disk protocol for VHD/VHDX boot
   - `VtoyUtil`: utility protocols for UEFI environment manipulation
3. EDK2 application chain-loads **GRUB2 EFI** (architecture-specific: x86_64-efi, arm64-efi, or mips64el-efi)
4. GRUB2 EFI proceeds identically to the BIOS path from step 4 onward
5. For Secure Boot: the Ventoy MOK key must be enrolled first via MokManager (one-time operation)

### 2.4 Boot Chain — Windows WIM Path

1. GRUB2 identifies a WIM file (or ISO containing `sources/boot.wim`)
2. **wimboot** (modified version 2.7.3, from `wimboot/wimboot-2.7.3/`) is loaded
3. wimboot extracts `bootmgr.exe` from the compressed `bootmgr` file
4. A virtual disk is created in memory containing the WIM and required boot files
5. `bootmgr.exe` executes, loading Windows PE from the WIM
6. The `vtoyjump` component (`vtoyjump/vtoyjump/`) handles boot-time hooks: XZ decompression of payloads and disk/partition mapping so Windows PE can find the source ISO/WIM on the Ventoy data partition

### 2.5 Boot Chain — Network (iPXE) Path

1. **iPXE** (modified, based on commit `3fe683e`, from `IPXE/ipxe_mod_code/ipxe-3fe683e/`) provides PXE network boot
2. The `ventoy_boot_vdisk()` function enables VHD boot over network
3. iPXE can chain-load Ventoy's GRUB2 or directly boot network-hosted images
4. Useful for diskless workstation deployments where images are served from a network share

### 2.6 Boot Chain — Unix/BSD Path

1. Custom **geom_ventoy** kernel modules provide virtual block device access for BSD-family systems
2. Precompiled modules cover: FreeBSD 9.x through 15.x, DragonFly BSD, MidnightBSD, pfSense, ClonOS
3. Source in `Unix/` — these are GEOM (FreeBSD disk framework) classes that present the ISO content as a native block device
4. The kernel module loads during early boot via the distro hook mechanism, enabling the BSD installer/live system to find its root filesystem on the Ventoy-mapped device

---

## 3. Repository Layout and Module Index

The repository contains 101 modules. Below is the complete map organized by functional area.

### 3.1 Core Boot Infrastructure

| Module | Path | Language | Purpose |
|---|---|---|---|
| GRUB2 | `GRUB2/MOD_SRC/grub-2.04/` | C | Modified GRUB2 2.04 with Ventoy-specific commands, menu system, and disk handling |
| EDK2 | `EDK2/edk2_mod/` | C | UEFI application suite (edk2-stable201911): VDiskChain, VtoyUtil |
| wimboot | `wimboot/wimboot-2.7.3/` | C | Windows WIM/bootmgr boot loader (modified upstream 2.7.3) |
| iPXE | `IPXE/ipxe_mod_code/ipxe-3fe683e/` | C | Network boot with Ventoy VHD support (modified upstream 3fe683e) |
| vtoyjump | `vtoyjump/vtoyjump/` | C | Windows boot-time hook — XZ decompression, disk/partition mapping |

### 3.2 Installer Tools

| Module | Path | Language | Purpose |
|---|---|---|---|
| Ventoy2Disk (Windows) | `Ventoy2Disk/Ventoy2Disk/` | C (Win32 API) | Native Windows installer GUI (22 files, 519KB source) |
| Ventoy2Disk (Linux GUI) | `LinuxGUI/Ventoy2Disk/` | C/C++ | Linux installer with GTK2/GTK3/QT5/WebUI frontends |
| Plugson | `Plugson/src/` | C | Plugin configuration web server (civetweb-based) |
| Vlnk | `Vlnk/src/` | C | Ventoy link file (.vlnk) creator for Windows and Linux |

### 3.3 Disk and Filesystem Utilities

| Module | Path | Language | Purpose |
|---|---|---|---|
| VtoyTool | `VtoyTool/` | C | Low-level disk and ISO manipulation tools |
| vtoycli | `vtoycli/` | C | CLI for partition operations (partresize, etc.) |
| vtoygpt | `vtoygpt/` | C | GPT partition table creation and manipulation |
| vtoyfat | `vtoyfat/` | C | FAT filesystem I/O library wrapper |
| ExFAT | `ExFAT/` | C | ExFAT tools: mkexfatfs, mount.exfat-fuse |
| FUSEISO | `FUSEISO/` | C | FUSE-based ISO 9660 mounting |

### 3.4 Compression and Cryptography

| Module | Path | Language | Purpose |
|---|---|---|---|
| SQUASHFS | `SQUASHFS/` | C | Squashfs-tools 4.4 (unsquashfs for distro hooks) |
| LZIP | `LZIP/` | C | Lzip decompression (lunzip) |
| ZSTD | `ZSTD/` | C | Zstandard compression/decompression |
| cryptsetup | `cryptsetup/` | Binary | veritysetup for dm-verity (32-bit and 64-bit) |

### 3.5 System Support

| Module | Path | Language | Purpose |
|---|---|---|---|
| DMSETUP | `DMSETUP/` | C | Device-mapper setup tools (dmsetup32/64/aa64) |
| BUSYBOX | `BUSYBOX/` | C | Minimal busybox for initrd environments |
| VBLADE | `VBLADE/vblade-master/` | C | ATA over Ethernet (AoE) virtual blade daemon |
| KBD | `KBD/` | Config | Keyboard layout configuration files |
| Unix | `Unix/` | C | FreeBSD/DragonFly/pfSense/ClonOS/MidnightBSD geom_ventoy kernel modules |

### 3.6 Packaging and Distribution

| Module | Path | Language | Purpose |
|---|---|---|---|
| INSTALL | `INSTALL/` | Shell/Binary | Shell installer scripts, boot images, GRUB configs, EFI files, tools |
| IMG | `IMG/` | Shell | Boot initrd images (cpio archives) with per-distro hooks |
| LiveCD / LiveCDGUI | `LiveCD/`, `LiveCDGUI/` | Shell | LiveCD ISO generation scripts |
| LANGUAGES | `LANGUAGES/` | JSON | i18n language files (2 files, 237KB total) |

### 3.7 Directory Purposes on VTOYEFI (Partition 2)

| Path | Content |
|---|---|
| `/grub/grub.cfg` | Master GRUB configuration — image enumeration, menu generation |
| `/grub/i386-pc/` | GRUB2 modules for Legacy BIOS boot |
| `/grub/x86_64-efi/` | GRUB2 modules for x86_64 UEFI |
| `/grub/arm64-efi/` | GRUB2 modules for ARM64 UEFI |
| `/grub/mips64el-efi/` | GRUB2 modules for MIPS64EL UEFI |
| `/EFI/BOOT/` | EFI bootloader binaries (BOOTX64.EFI, BOOTIA32.EFI, BOOTAA64.EFI) |
| `/ventoy/` | Ventoy runtime data, version info |
| `/tool/` | Utility binaries used during boot |
| `/ENROLL_THIS_KEY_IN_MOKMANAGER.cer` | MOK certificate for Secure Boot enrollment |

---

## 4. Component Deep Dive

### 4.1 GRUB2 Modifications

Ventoy forks GRUB2 2.04 with extensive modifications that go well beyond configuration. The changes are in two areas: core boot handling and custom Ventoy-specific commands.

**Core modifications in `grub-core/`:**

- **`ventoy_env_write_root()`** — Hooks into GRUB's root device resolution. Intercepts the standard root-setting logic to inject Ventoy's virtual disk mapping, ensuring GRUB can address files on loopback-mounted ISOs as if they were on a native block device.
- **`ventoy_legacy_limit_workaround()`** — Addresses BIOS INT13h disk size limits. When the USB drive exceeds the addressable range (typically 2TB for LBA48, but firmware-dependent), this function loads `ventoy.disk.img.xz` via GRUB's loopback mechanism, providing an alternative access path to disk content beyond the firmware limit.
- **`grub_main()` patches** — The modified main function adds Ventoy-specific prefix and root handling before GRUB's normal initialization sequence. This ensures the GRUB environment is correctly configured to find modules and configuration on the VTOYEFI partition regardless of how the firmware enumerated the USB device.
- **`vt_load_menu_lang`** — Runtime language switching. Reads language JSON files from the data partition and applies translations to the GRUB menu at display time.

**Custom Ventoy GRUB commands (in `grub-core/ventoy/` and `grub-core/commands/`):**

These modules implement the image-type-specific boot logic:

- ISO loopback mount and chain-load for Linux live images
- WIM detection and wimboot handoff for Windows images
- VHD/VHDX virtual disk mapping
- IMG raw disk image boot
- EFI file direct execution
- Multi-image and persistence support
- Checksum verification of image files

The GRUB module set is architecture-specific. Each target (i386-pc, x86_64-efi, arm64-efi, mips64el-efi) gets its own compiled module directory on VTOYEFI.

### 4.2 EDK2 UEFI Application

Built against **edk2-stable201911** (not the latest EDK2 — pinned for stability), the Ventoy UEFI application provides two key protocols:

**VDiskChain:**
- Implements a UEFI Block I/O Protocol that presents a VHD/VHDX file as a native UEFI block device
- Allows UEFI firmware to boot directly from virtual hard disk files without OS-level support
- Handles both fixed-size and dynamic VHD formats

**VtoyUtil:**
- Utility protocol for UEFI environment manipulation
- Provides functions for memory mapping, device path construction, and protocol installation
- Used by the GRUB2 EFI build to interface with Ventoy-specific UEFI services

The EDK2 build produces architecture-specific EFI applications that are placed in the `/EFI/BOOT/` directory on VTOYEFI.

### 4.3 wimboot (Modified 2.7.3)

The wimboot fork handles Windows boot, which is the most complex boot path due to Windows' strict requirements:

1. **bootmgr extraction** — Windows ships `bootmgr` as a compressed PE executable. wimboot locates the embedded `bootmgr.exe`, decompresses it, and executes it directly.
2. **Virtual disk creation** — Constructs an in-memory virtual disk containing:
   - The WIM file (or a pointer to it on the USB)
   - BCD (Boot Configuration Data) store
   - Required boot fonts and resources
3. **Memory mapping** — Maps the virtual disk into the address space where `bootmgr.exe` expects to find its boot volume

The modifications over upstream wimboot are primarily in how the source WIM is located (on a Ventoy USB partition rather than a PXE server) and how the virtual disk interacts with Ventoy's disk mapping layer.

### 4.4 iPXE (Modified 3fe683e)

The iPXE fork adds `ventoy_boot_vdisk()` — a function that enables VHD boot over network. This allows a deployment where:

- The Ventoy USB provides the boot infrastructure
- VHD images are served from a network file server
- iPXE fetches the VHD and boots it via Ventoy's VDiskChain

This is primarily useful for enterprise thin-client or diskless workstation scenarios.

### 4.5 Windows Installer — Ventoy2Disk.exe

The Windows native installer is a Win32 application (22 source files, 519KB of C source) in `Ventoy2Disk/Ventoy2Disk/`.

**Key source files and responsibilities:**

| File | Purpose |
|---|---|
| `Ventoy2Disk.c` | Main entry, WinMain, message loop |
| `DiskService.c` | Disk enumeration, partition creation, format operations |
| `PhyDrive.c` | Physical drive access (CreateFile on `\\.\PhysicalDriveN`) |
| `AlertSuppress.c` | Suppresses Windows "format disk" and "location not available" popups during installation via window message interception |
| `fat_io_lib/` | Embedded FatFs R0.14 for direct FAT filesystem I/O |

**Notable implementation details:**

- XZ embedded decompression for `core.img` — the GRUB core image is stored compressed and decompressed at install time
- Both 32-bit and 64-bit builds; ARM64 version available for Windows on ARM devices
- Non-destructive install (`-n` flag) supports NTFS and ext2/3/4 filesystem shrink — resizes the existing filesystem, creates Ventoy partitions in the freed space, preserving existing data
- `AlertSuppress.c` runs in a separate thread, monitoring for and automatically dismissing Windows dialog boxes that appear when raw disk operations cause the OS to detect "unformatted" partitions

### 4.6 Linux GUI Installer

Four frontend variants share a common core in `LinuxGUI/Ventoy2Disk/Core/`:

**GTK2/GTK3** (`build_gtk.sh`):
- Native desktop GUI using GTK widget toolkit
- GTK3 preferred; GTK2 as fallback for older distributions

**QT5** (`build_qt.sh`):
- QT5 desktop GUI for KDE/QT-native desktop environments

**WebUI** (`build.sh`):
- civetweb-based web server (V2DServer)
- Provides a browser-based interface accessible at `http://127.0.0.1:24680`
- Fallback when no desktop toolkit is available (headless servers, minimal installs)

**Launcher script** `VentoyGUI.{arch}`:
- Probes toolkit availability in order: GTK3 → QT5 → GTK2 → WebUI
- Launches the first available frontend
- Architecture variants: x86_64, i386, aarch64, mips64el

### 4.7 Plugson — Plugin Configuration Server

Plugson is a civetweb-based (embedded HTTP, no SSL, no CGI) web application for managing Ventoy's JSON plugin configuration files.

**Core source files in `Plugson/src/`:**

| File | Purpose |
|---|---|
| `ventoy_disk.c` | USB disk detection and partition access |
| `ventoy_json.c` | JSON parser/serializer for `ventoy.json` |
| `ventoy_util.c` | Utility functions (path handling, string ops) |
| `ventoy_md5.c` | MD5 checksum calculation |
| `ventoy_utf.c` | UTF-8/UTF-16 conversion |

**Web UI** (`Plugson/www/`):
- Built on AdminLTE 2.3.0 (Bootstrap 3 admin template)
- DataTables for tabular plugin configuration
- jQuery for DOM manipulation and AJAX
- Provides point-and-click management of all `ventoy.json` plugin sections

Plugson reads and writes JSON configuration files in the `/ventoy/` directory on the USB data partition (Partition 1). It is launched from the installer GUI or manually via command line.

### 4.8 vtoyjump — Windows Boot-Time Hook

`vtoyjump` is a small C program that runs during Windows PE boot (before the full Windows environment loads). Its responsibilities:

- **XZ decompression** of compressed payloads needed during boot
- **Disk and partition mapping** so Windows PE can locate the source ISO/WIM on the Ventoy data partition
- **Drive letter assignment** for the Ventoy partition within the Windows PE environment

This is critical for Windows installations from ISO — Windows Setup needs to find the `sources/install.wim` inside the ISO, which requires the ISO content to be accessible as a mounted volume.

### 4.9 Disk Utilities

**VtoyTool** — Low-level operations: ISO sector mapping, disk geometry queries, partition offset calculations. Used by installer scripts to prepare the USB layout.

**vtoycli** — Command-line interface for partition operations. Key subcommand: `partresize` for Secure Boot partition adjustments (`vtoycli partresize -s` modifies the VTOYEFI partition layout).

**vtoygpt** — GPT partition table manipulation. Creates and modifies GUID Partition Tables for disks using GPT layout (required for disks >2TB, optional via `-g` flag for smaller disks).

**vtoyfat** — FAT filesystem I/O wrapper. Provides programmatic read/write access to the VTOYEFI FAT16 partition without OS-level mount operations.

---

## 5. Partition Layout and Disk Structure

### 5.1 Partition Table

Ventoy supports both MBR and GPT partition styles:

| Style | When Used | Notes |
|---|---|---|
| MBR | Default for disks ≤ 2TB | Maximum compatibility with Legacy BIOS |
| GPT | Disks > 2TB, or when `-g` flag is used | Required for large drives; recommended for pure-UEFI environments |

> [!IMPORTANT]
> 4K native sector devices (4Kn) are **not supported**. Ventoy requires 512-byte logical sector drives. Most USB drives use 512e (512-byte emulation over 4K physical), which works fine. True 4Kn devices will fail during installation.

### 5.2 Partition 1 — Data Partition

| Property | Value |
|---|---|
| Label | `Ventoy` (configurable with `-L` flag) |
| Default filesystem | exFAT |
| Alternative filesystems | NTFS (non-destructive install), ext2/3/4 (non-destructive install) |
| Cluster size (>32GB disk) | 128KB |
| Cluster size (≤32GB disk) | 32KB |
| Content | User-placed boot images + optional `/ventoy/` config directory |

Supported image formats on this partition: `.iso`, `.wim`, `.img`, `.vhd`, `.vhdx`, `.efi`, `.vtoy` (Ventoy auto-install), `.vlnk` (Ventoy link files).

### 5.3 Partition 2 — VTOYEFI

| Property | Value |
|---|---|
| Label | `VTOYEFI` |
| Filesystem | FAT16 |
| Size | 32MB (defined by `VENTOY_SECTOR_NUM` constant in source) |
| Content | GRUB2 modules, EFI bootloaders, Ventoy boot config, tools, MOK certificate |

This partition is managed entirely by Ventoy. Users should not modify its contents manually. Ventoy upgrades replace this partition's contents while preserving Partition 1 data.

### 5.4 Reserved Space

The `-r SIZE_MiB` flag reserves space at the end of the disk, between the data partition and VTOYEFI. Use cases:
- Preserving a small partition for other tools (e.g., a persistent encrypted volume)
- Working around firmware bugs that misread the disk's last sectors

### 5.5 Install Modes

| Mode | Flag | Behavior |
|---|---|---|
| Normal | (default) | Wipes disk, creates fresh Partition 1 (exFAT) + Partition 2 |
| Non-destructive | `-n` | Shrinks existing NTFS/ext2/3/4 filesystem, creates Ventoy partitions in freed space, existing data preserved |
| GPT | `-g` | Uses GPT instead of MBR partition table |
| Secure Boot | `-s` | Adjusts VTOYEFI layout for Secure Boot compatibility |

---

## 6. Build System

### 6.1 Build Environment Requirements

The build system is designed for Linux hosts. Cross-compilation toolchains are required for multi-architecture output.

**Required toolchains:**

| Target | Toolchain |
|---|---|
| x86_64 | gcc (native or cross) |
| i386 | gcc -m32 (or i686-linux-gnu-gcc) |
| ARM64 | aarch64-linux-gnu-gcc |
| MIPS64EL | mips-linux-gnu-gcc (or mips64el-linux-gnuabi64-gcc) |

**Required libraries:**

| Library | Purpose |
|---|---|
| dietlibc | Minimal C library for small static binaries |
| musl-libc | Alternative minimal C library |

**Build dependencies for sub-projects:**

| Component | Dependencies |
|---|---|
| GRUB2 | autoconf, automake, bison, flex, python, gettext, device-mapper headers |
| EDK2 | NASM, IASL (ACPI compiler), UUID libraries |
| iPXE | perl, mtools, syslinux (for isolinux.bin) |

### 6.2 Build Pipeline

The master build orchestration is in `INSTALL/all_in_one.sh` and `ventoy_pack.sh`.

**Build order:**

```
1. prepare_env        Set up toolchains, create build directories
        |
2. GRUB2 build        grub-2.04 for all 4 architectures
        |              (i386-pc, x86_64-efi, arm64-efi, mips64el-efi)
        |
3. iPXE build         Network boot firmware
        |
4. EDK2 build         UEFI applications (VDiskChain, VtoyUtil)
        |
5. Utility builds     VtoyTool, vtoycli, vtoygpt, vtoyfat, FUSEISO,
        |              ExFAT, SQUASHFS, VBLADE, DMSETUP, LZIP, ZSTD
        |
6. wimboot build      Windows WIM boot loader
        |
7. Installer builds   Ventoy2Disk (Windows), LinuxGUI variants
        |
8. Plugson build      Plugin configuration server
        |
9. ventoy_pack.sh     Package everything into release archives
```

### 6.3 Release Packaging

`ventoy_pack.sh` produces:

| Output | Contents |
|---|---|
| `ventoy-{version}-linux.tar.gz` | Shell installer, all boot files, Linux GUI variants, Plugson |
| `ventoy-{version}-windows.zip` | Ventoy2Disk.exe (32+64-bit), all boot files, Plugson |
| LiveCD ISO | Bootable ISO with Ventoy installer (via `LiveCD/` and `LiveCDGUI/` scripts) |

### 6.4 Docker CI Build

`docker_ci_build.sh` provides a reproducible build environment:

1. Downloads all required cross-compilation toolchains
2. Installs build dependencies in a container
3. Runs the full build pipeline
4. Outputs release packages

This is the recommended build method for contributors — it eliminates host-specific toolchain version issues.

> [!NOTE]
> The build system does not use CMake, Meson, or any modern build system generator. Each component has its own Makefile or build script. The `all_in_one.sh` script orchestrates them sequentially. Parallel builds of independent components are not implemented.

### 6.5 Building Individual Components

For development iteration, individual components can be rebuilt:

```bash
# GRUB2 only (all architectures)
cd GRUB2/MOD_SRC/grub-2.04
./autogen.sh
./configure --target=x86_64 --with-platform=efi
make

# EDK2 UEFI application
cd EDK2/edk2_mod
source edksetup.sh
build -a X64 -t GCC5 -p VentoyPkg/VentoyPkg.dsc

# Plugson
cd Plugson/src
make

# Windows installer (requires MinGW cross-compiler on Linux)
cd Ventoy2Disk/Ventoy2Disk
make -f Makefile.mingw
```

---

## 7. Configuration Mastery — ventoy.json

All Ventoy runtime configuration lives in a single JSON file at `/ventoy/ventoy.json` on the data partition (Partition 1). There is no formal schema documented in the source — the configuration structure is defined implicitly by the C code in Plugson and the GRUB2 modules that parse it.

> [!IMPORTANT]
> The `ventoy.json` file is optional. Ventoy works with zero configuration. Every configuration key described below is opt-in. Malformed JSON will cause Ventoy to silently ignore the entire configuration file and boot with defaults.

### 7.1 Configuration Categories

Based on source analysis of Plugson's JSON handling (`ventoy_json.c`) and GRUB2's config parsing, the major configuration sections are:

**Boot control:**
- Default boot image selection
- Boot timeout
- Menu display options (list mode vs. TreeView)
- GRUB theme selection
- Language/locale

**Image filtering:**
- Include/exclude patterns for image enumeration
- Directory-specific image ordering
- Image aliases (display names)
- Image tips (descriptions shown in menu)
- Image classes (icon mappings for GRUB themes)

**Persistence:**
- Persistence image mapping (link specific persistence files to specific ISOs)
- Persistence backends: raw image files, partition-based persistence
- Multiple persistence images per ISO (selectable at boot)

**Auto-installation:**
- Kickstart/preseed/autounattend file mapping
- Per-ISO auto-install configuration
- Injection of additional files/drivers into the boot environment

**Plugin system:**
- Password protection (plain, MD5, or SHA256 hash)
- Custom GRUB menu entries
- DUD (Driver Update Disk) injection
- Custom boot parameters (kernel command line appendix)
- Wimboot options for Windows images
- Secure Boot configuration overrides

### 7.2 Configuration Management via Plugson

Plugson provides a web UI for editing `ventoy.json` without manual JSON editing:

```bash
# Linux — launch Plugson for a specific USB device
sudo ./VentoyPlugson.sh /dev/sdb

# Opens browser to http://127.0.0.1:24681
# (port may vary; check terminal output)
```

On Windows, Plugson is accessible from the Ventoy2Disk GUI via a menu option.

The Plugson web interface provides:
- Form-based editing of each configuration section
- File browser for selecting ISOs and persistence images
- Validation of basic JSON structure before saving
- Preview of effective configuration

### 7.3 Theme Configuration

GRUB themes are placed in `/ventoy/theme/` on the data partition:

```
/ventoy/
  theme/
    theme.txt          # GRUB theme definition
    background.png     # Background image
    icons/             # Boot entry icons
    fonts/             # Custom fonts (.pf2)
```

Theme selection in `ventoy.json`:

```json
{
  "theme": {
    "file": "/ventoy/theme/theme.txt",
    "gfxmode": "1920x1080"
  }
}
```

### 7.4 Persistence Configuration

```json
{
  "persistence": [
    {
      "image": "/ubuntu-22.04.iso",
      "backend": [
        "/persistence/ubuntu-rw.img"
      ]
    },
    {
      "image": "/kali-linux.iso",
      "backend": [
        "/persistence/kali-rw.img",
        "/persistence/kali-rw-backup.img"
      ]
    }
  ]
}
```

When multiple backends are listed for one image, Ventoy presents a selection menu at boot time. Persistence images are created using `CreatePersistentImg.sh` (Linux) or tools on the Ventoy website.

---

## 8. Distro Hook System

The distro hook system is the largest maintenance surface in Ventoy. It provides per-distribution compatibility patches that run during the boot initrd phase to ensure the target OS can find its root filesystem on the Ventoy-mapped virtual device.

### 8.1 Architecture

```
IMG/cpio/ventoy/
  hook/
    ventoy-hook-lib.sh      # Common library functions
    ventoy-os-lib.sh        # OS detection and dispatch
    alpine/                  # Alpine Linux hooks
    arch/                    # Arch Linux hooks
    debian/                  # Debian hooks
    fedora/                  # Fedora hooks
    gentoo/                  # Gentoo hooks
    manjaro/                 # Manjaro hooks
    nixos/                   # NixOS hooks
    suse/                    # openSUSE hooks
    ubuntu/                  # Ubuntu hooks
    ... (50+ additional distro directories)
```

### 8.2 Hook Mechanism

1. **initrd injection** — Ventoy prepends a custom cpio archive to the target ISO's initrd. This archive contains `ventoy-hook-lib.sh`, the appropriate distro hook script, and a `udev` rule.

2. **udev rule** (`99-ventoy.rules`) — Triggers when the block device subsystem initializes. Calls the Ventoy hook script.

3. **Device-mapper setup** — The hook script uses `dmsetup` to create `/dev/mapper/ventoy`, a device-mapper target that maps to the ISO content on the USB drive. This device-mapper target presents the ISO's filesystem as a standard block device.

4. **Busybox** — A minimal busybox binary is included in the injected cpio for environments where the target initrd lacks required utilities.

### 8.3 Hook Library Functions (ventoy-hook-lib.sh)

Key functions available to all distro hooks:

| Function | Purpose |
|---|---|
| `ventoy_os_install_dmsetup_by_fuse` | Install dmsetup binary from FUSE-mounted ISO |
| `ventoy_create_persistent_link` | Set up persistence device symlinks |
| `ventoy_udev_disk_common` | Common udev handler for standard Linux distros |
| `ventoy_set_inotify_script` | Set up inotify watches for late-appearing devices |

### 8.4 Special-Case Hooks

Some distributions require unique handling that goes beyond the standard device-mapper approach:

| Category | Distros | Special Handling |
|---|---|---|
| Loop mount | Tails, LibreELEC, Batocera, Endless, FydeOS, CloudReady | Direct loop mount of squashfs/filesystem image instead of device-mapper |
| vtloopex | OpenWrt, Lakka, LibreELEC (specific versions) | Precompiled dm-mod kernel modules injected because these distros ship without device-mapper support |
| Read-only root | NixOS, Guix | Special handling for immutable root filesystem patterns |
| Live persistence | Ubuntu, Kali, Debian | Casper/live-boot persistence backend integration |
| Encrypted | MX-Linux | LUKS persistence partition support |

### 8.5 Precompiled Kernel Modules (vtloopex)

The `vtloopex/` directory contains precompiled `dm-mod.ko` kernel modules for specific distro kernel versions. These are necessary for distributions that:
- Do not include device-mapper in their default initrd
- Ship minimal kernels without module loading support
- Use custom kernel configurations that exclude dm-mod

Each vtloopex entry is kernel-version-specific and must be updated when the target distro releases a new kernel.

> [!WARNING]
> The vtloopex precompiled modules are the most fragile part of the hook system. A kernel update in any supported distro can break boot compatibility until a matching dm-mod module is compiled and added. This is the primary reason some distro versions stop working after updates.

---

## 9. Security Model

### 9.1 UEFI Secure Boot

Ventoy implements Secure Boot support via the Machine Owner Key (MOK) mechanism:

1. **First boot with Secure Boot enabled** — UEFI firmware rejects Ventoy's unsigned bootloader
2. **MOK enrollment** — User must:
   - Boot with Secure Boot disabled (one time)
   - Or use MokManager to enroll `ENROLL_THIS_KEY_IN_MOKMANAGER.cer` from the VTOYEFI partition
3. **Subsequent boots** — The enrolled MOK key validates Ventoy's EFI binaries; Secure Boot proceeds normally

> [!CAUTION]
> Enrolling the Ventoy MOK key trusts ALL binaries signed by that key. This is a machine-level trust decision. In enterprise environments, evaluate whether the Ventoy MOK key meets your organization's Secure Boot policy. Some organizations may require adding Ventoy's key to a centrally managed MOK database via `mokutil`.

**Partition resize for Secure Boot:**

```bash
# Adjust VTOYEFI partition for Secure Boot compatibility
sudo vtoycli partresize -s /dev/sdb
```

This modifies the VTOYEFI partition layout to accommodate Secure Boot shim and MOK binaries.

### 9.2 Password Protection

Ventoy supports password-protecting the boot menu via `ventoy.json`:

```json
{
  "password": {
    "type": "sha256",
    "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }
}
```

Supported hash types: `plain` (cleartext — not recommended), `md5`, `sha256`.

The password protects access to the GRUB boot menu. It does not encrypt the USB drive contents — files on the exFAT data partition remain readable by any OS that mounts the drive.

### 9.3 dm-verity Integration

Boot hooks include `veritysetup32` and `veritysetup64` binaries for dm-verity support. This is used by specific distros (Chrome OS, Android-x86, and others) that require verified boot chains. Ventoy's hook system provides the verity setup tools when the target initrd expects them.

### 9.4 Binary Integrity and False Positives

> [!CAUTION]
> Ventoy packages contain precompiled binaries (dmsetup, busybox, veritysetup, GRUB modules, EFI applications) that frequently trigger antivirus false positives. This is a known and recurring issue (GitHub issue #3569). The binaries are compiled from the source in this repository. VirusTotal reports should be evaluated in this context — heuristic detections on low-level boot utilities are expected behavior, not indicators of compromise.

### 9.5 Disk-Level Security Considerations

| Concern | Status |
|---|---|
| USB drive encryption | Not provided — data partition is cleartext exFAT |
| Boot image integrity | Optional — Ventoy can verify checksums if configured |
| Tamper detection | None — no chain-of-trust from USB hardware to boot images |
| Write protection | Not enforced — any OS can write to the data partition |
| Secure erase | Not provided — use OS-level tools |

For environments requiring encrypted boot media, Ventoy is not a standalone solution. It must be combined with OS-level encryption (e.g., LUKS for Linux, BitLocker for Windows) applied to the booted OS, not to the Ventoy USB itself.

---

## 10. Deployment Strategies

### 10.1 Single USB — Interactive Use

The standard deployment: one USB drive, one user, interactive boot menu selection.

```bash
# Linux installation
sudo sh Ventoy2Disk.sh -i /dev/sdb

# With GPT partition table
sudo sh Ventoy2Disk.sh -i -g /dev/sdb

# Non-destructive install on existing NTFS drive
sudo sh Ventoy2Disk.sh -i -n /dev/sdb

# Custom partition label
sudo sh Ventoy2Disk.sh -i -L "MYBOOT" /dev/sdb

# Reserve 1GB at end of disk
sudo sh Ventoy2Disk.sh -i -r 1024 /dev/sdb
```

> [!WARNING]
> The `-i` (install) flag is destructive in normal mode — it wipes the entire disk. Double-check the target device with `lsblk` before running. The non-destructive (`-n`) flag preserves existing data by shrinking the filesystem.

### 10.2 Upgrade Existing Installation

```bash
# Upgrade Ventoy on USB (preserves data partition and all ISOs)
sudo sh Ventoy2Disk.sh -u /dev/sdb
```

Upgrades replace only the VTOYEFI partition contents and boot sector code. The data partition (Partition 1) is untouched — all ISO/WIM/VHD files are preserved.

### 10.3 Enterprise Mass Deployment

For deploying Ventoy to many USB drives:

```bash
#!/bin/bash
# Mass deployment script example
VENTOY_DIR="/path/to/ventoy-release"
ISO_SOURCE="/path/to/approved-images/"

for dev in /dev/sd{b,c,d,e,f}; do
  echo "Installing Ventoy to $dev"
  sudo "$VENTOY_DIR/Ventoy2Disk.sh" -i -g "$dev"
  
  # Wait for partition to appear
  sleep 2
  
  # Mount data partition and copy approved images
  mount_point=$(mktemp -d)
  mount "${dev}1" "$mount_point"
  cp -r "$ISO_SOURCE"/* "$mount_point/"
  
  # Copy standard configuration
  mkdir -p "$mount_point/ventoy"
  cp ventoy.json "$mount_point/ventoy/"
  
  umount "$mount_point"
  rmdir "$mount_point"
done
```

### 10.4 Ventoy Link Files (.vlnk)

For images stored on network shares or other partitions, Ventoy link files provide indirection:

```bash
# Create a .vlnk file pointing to a network-accessible image
# Linux
./VentoyVlnk.sh -c /path/to/actual.iso -o /ventoy-usb/link.vlnk

# Windows
VentoyVlnk.exe -c D:\images\actual.iso -o E:\link.vlnk
```

The `.vlnk` file is a small pointer file placed on the Ventoy data partition. At boot time, Ventoy resolves the link and boots the target image. This is useful when the actual ISO is too large for the USB or is maintained on a central file server.

> [!NOTE]
> `.vlnk` files for GPT-partitioned drives have known issues (GitHub issue #3566). Test thoroughly in your environment before deploying.

### 10.5 LiveCD Deployment

The `LiveCD/` and `LiveCDGUI/` scripts generate a bootable ISO containing the Ventoy installer itself. This is useful for installing Ventoy on machines without an existing OS or USB boot capability — boot the LiveCD from optical media, then install Ventoy to a USB drive from within the live environment.

---

## 11. Operations and Maintenance

### 11.1 Version Upgrades

> [!IMPORTANT]
> Always upgrade via the official upgrade path (`Ventoy2Disk.sh -u` or Ventoy2Disk.exe Update button). Never manually modify the VTOYEFI partition. Manual changes will be overwritten on next upgrade and may leave the USB in an unbootable state.

Upgrade checklist:
1. Back up any custom `ventoy.json` and theme files from the data partition
2. Run the upgrade command
3. Verify boot on at least one test image
4. Restore custom configuration if overwritten (rare — upgrades typically preserve Partition 1)

### 11.2 Adding and Removing Boot Images

No special procedure required — copy files to or delete files from the Ventoy data partition using any file manager or command-line tool. Ventoy re-enumerates at every boot.

Supported file extensions: `.iso`, `.wim`, `.img`, `.vhd`, `.vhdx`, `.efi`, `.vtoy`, `.vlnk`

Subdirectory organization is supported — Ventoy scans recursively (or in TreeView mode, presents the directory structure as a navigable menu).

### 11.3 Monitoring USB Health

Ventoy does not include USB health monitoring. For drives used in production (kiosk boot, deployment stations), implement external monitoring:

```bash
# Check filesystem integrity
sudo fsck.exfat /dev/sdb1

# SMART data (if USB-to-SATA bridge supports it)
sudo smartctl -a /dev/sdb

# Monitor write cycles (USB flash has finite endurance)
# No built-in tool — use manufacturer utilities
```

### 11.4 Backup and Recovery

> [!WARNING]
> There is no built-in backup mechanism for Ventoy USB drives. The VTOYEFI partition can be recreated by re-running the installer, but custom configurations and theme files on Partition 1 require manual backup.

Recommended backup strategy:
1. Periodically copy `/ventoy/ventoy.json` and `/ventoy/theme/` to a separate location
2. Maintain a master copy of all ISO images on a network share or NAS
3. Document the Ventoy version installed (check `/ventoy/ventoy_version` on VTOYEFI or the GRUB menu title)

### 11.5 Multi-Architecture USB Drives

A single Ventoy USB contains boot files for all supported architectures (i386 BIOS, x86_64 UEFI, ARM64 UEFI, MIPS64EL UEFI). The firmware selects the appropriate boot path automatically. No configuration is needed for multi-architecture support — it is the default.

However, the boot images themselves are architecture-specific. An x86_64 Linux ISO will not boot on ARM64 hardware. Organize images by architecture on the data partition for clarity:

```
/x86_64/
  ubuntu-22.04-amd64.iso
  windows-11.iso
/arm64/
  ubuntu-22.04-arm64.iso
  fedora-arm64.iso
```

---

## 12. Internationalization

### 12.1 Language System

The `LANGUAGES/` directory contains two large JSON files (237KB total) with translations for the GRUB boot menu and installer UIs. Languages are loaded at runtime via `vt_load_menu_lang` in GRUB2.

To set the boot menu language, configure it in `ventoy.json`:

```json
{
  "menu_lang": "zh_CN"
}
```

Or select the language interactively from the GRUB boot menu (F5 or language menu option, depending on theme).

### 12.2 Keyboard Layouts

The `KBD/` directory contains keyboard layout configuration files. These are loaded by GRUB2 to support non-US keyboard layouts in the boot menu. Configure via:

```json
{
  "menu_kbd": "de"
}
```

---

## 13. Troubleshooting Playbook

### 13.1 Boot Failures — Diagnostic Approach

```
USB not detected by firmware
  └─> Check BIOS boot order, enable USB boot
  └─> Try different USB port (USB 2.0 vs 3.0)
  └─> Verify Ventoy installation: mount VTOYEFI, check for grub/grub.cfg

GRUB menu appears but image won't boot
  └─> Check image integrity (MD5/SHA256 against source)
  └─> Try GRUB console: press 'c', run 'ls' to verify partitions
  └─> Check GRUB modules: ls (hd0,msdos2)/grub/x86_64-efi/

Image boots to black screen / kernel panic
  └─> Distro hook issue — check if distro is in supported list
  └─> Try adding 'nomodeset' to kernel parameters (press 'e' in GRUB, edit linux line)
  └─> Check vtloopex for kernel version mismatch

Windows setup error 0x80070001
  └─> Known issue with Windows 11 24H2 (GitHub #2887)
  └─> Try alternative WIM extraction method
  └─> Ensure USB is connected to USB 3.0 port for speed
```

### 13.2 Known Issue Reference

> [!CAUTION]
> These are confirmed issues from the project's issue tracker. Workarounds are noted where available.

| Issue | Description | Status/Workaround |
|---|---|---|
| #3570 | VirtualBox boot compatibility | Use VBox EFI mode, not BIOS |
| #3451 | OOM/BSOD installing Nobara | Increase VM RAM or use physical hardware |
| #2727 | Fedora CoreOS 39 boot failure | Hook update needed for CoreOS initrd format |
| #3545 | MX-Linux encrypted persistence | LUKS persistence configuration required |
| #2887 | Windows 11 24H2 error 0x80070001 | Alternative WIM extraction; USB 3.0 port |
| #3503 | Archlinux vtoyboot UUID timeout | Regenerate initramfs with ventoy hooks |
| #1846 | USB becomes read-only | Hardware write-protect switch; replace drive |
| #3555 | VentoyGUI fails on Hyprland | Use WebUI fallback: `sudo ./VentoyWebDiskStart.sh` |
| #3566 | vlnk files on GPT drives | Known limitation; use MBR for vlnk use cases |
| #2697 | Haiku OS boot failure | Unsupported — Haiku's boot chain is incompatible |

### 13.3 Secure Boot Enrollment Failures

> [!WARNING]
> If MOK enrollment fails or the certificate is rejected, the most common causes are:
> 1. **Firmware bug** — Some UEFI implementations have broken MokManager support. Try updating firmware.
> 2. **Timeout** — MOK enrollment has a short timeout window. Be ready to enter the password immediately.
> 3. **Certificate format** — The `.cer` file must be DER-encoded X.509. If it was accidentally converted, re-extract from a fresh Ventoy install.

Fallback: Disable Secure Boot in UEFI settings. This is acceptable for personal use but not for managed enterprise environments.

### 13.4 Filesystem Corruption Recovery

```bash
# exFAT data partition repair
sudo fsck.exfat -a /dev/sdb1

# Recreate VTOYEFI without touching data partition
sudo sh Ventoy2Disk.sh -u /dev/sdb

# Complete rebuild (destroys data partition)
sudo sh Ventoy2Disk.sh -i /dev/sdb
```

### 13.5 Debugging GRUB at Boot Time

Press `c` at the Ventoy GRUB menu to enter the GRUB command line:

```
grub> ls                          # List all detected drives/partitions
grub> ls (hd0,msdos1)/            # List files on data partition
grub> ls (hd0,msdos2)/grub/       # List GRUB directory on VTOYEFI
grub> cat (hd0,msdos2)/grub/grub.cfg  # View GRUB configuration
grub> set                         # Show all GRUB environment variables
grub> lsmod                       # List loaded GRUB modules
```

Press `e` on a menu entry to edit boot parameters before launching (add `nomodeset`, `debug`, `break=init`, etc.).

---

## 14. Platform Support Matrix

### 14.1 Host OS for Installation

| Platform | Installer | GUI Options |
|---|---|---|
| Windows (x86, x64, ARM64) | Ventoy2Disk.exe | Native Win32 GUI |
| Linux (x86_64) | Ventoy2Disk.sh / VentoyGUI.x86_64 | GTK3, QT5, GTK2, WebUI |
| Linux (i386) | Ventoy2Disk.sh / VentoyGUI.i386 | GTK3, QT5, GTK2, WebUI |
| Linux (ARM64) | Ventoy2Disk.sh / VentoyGUI.aarch64 | GTK3, QT5, GTK2, WebUI |
| Linux (MIPS64EL) | Ventoy2Disk.sh / VentoyGUI.mips64el | GTK3, QT5, GTK2, WebUI |

### 14.2 Boot Target Firmware

| Firmware | Architecture | GRUB Module Path |
|---|---|---|
| Legacy BIOS | x86 (16/32-bit) | `grub/i386-pc/` |
| UEFI | x86_64 | `grub/x86_64-efi/` |
| UEFI | IA32 | `grub/i386-efi/` (if present) |
| UEFI | ARM64 | `grub/arm64-efi/` |
| UEFI | MIPS64EL | `grub/mips64el-efi/` |

### 14.3 Boot Target OS Families

| Family | Examples | Boot Method |
|---|---|---|
| Linux (mainstream) | Ubuntu, Fedora, Debian, Arch, SUSE, Manjaro | initrd injection + device-mapper hook |
| Linux (minimal) | Alpine, Void, Tiny Core | Specialized hooks per distro |
| Linux (immutable) | NixOS, Guix, Endless, Fedora Silverblue | Read-only root handling |
| Linux (appliance) | OpenWrt, LibreELEC, Lakka, Batocera | vtloopex precompiled modules + loop mount |
| Linux (security) | Tails, Kali, Parrot | Loop mount hooks; Tails requires special handling |
| Windows PE | Windows 10/11 Setup, WinPE | wimboot → bootmgr extraction → WIM boot |
| Windows (VHD) | Windows To Go, VHD deployments | VDiskChain EFI protocol |
| FreeBSD | FreeBSD 9.x–15.x | geom_ventoy kernel module |
| DragonFly BSD | DragonFly BSD | geom_ventoy kernel module |
| Other BSD | MidnightBSD, pfSense, ClonOS | geom_ventoy kernel module |
| ChromeOS | FydeOS, CloudReady | Loop mount + dm-verity hooks |
| Other | Android-x86, Haiku (limited), ReactOS | Varies by project |

---

## 15. Code Patterns and Conventions

### 15.1 Language and Style

The codebase is predominantly C (C89/C99) with POSIX shell scripts. There is no unified code style guide, but observed patterns include:

- **C code**: K&R-style braces, 4-space indentation in most modules, `snake_case` for functions, `UPPER_CASE` for macros and constants
- **Shell scripts**: `#!/bin/sh` (POSIX sh, not bash), extensive use of `sed`/`awk`/`grep` for text processing, `set -e` in installer scripts
- **JSON**: Machine-generated (language files) or hand-edited (ventoy.json) — no consistent formatting
- **No formal testing framework**: The project relies on manual testing across physical hardware and virtual machines

### 15.2 Naming Conventions

| Pattern | Meaning |
|---|---|
| `ventoy_` prefix (C) | Ventoy-specific function in modified upstream code |
| `vt_` prefix (C) | Short-form Ventoy function prefix (GRUB modules) |
| `vtoy` prefix (tool names) | Ventoy utility: vtoycli, vtoygpt, vtoyfat, vtoyjump |
| `Ventoy2Disk` | Installer tool name (all platforms) |
| `VTOYEFI` | Boot partition label (constant) |
| `ventoy.json` | Plugin configuration file (constant) |
| `*.vlnk` | Ventoy link file extension |
| `*.vtoy` | Ventoy auto-install template |

### 15.3 Error Handling Patterns

- **C code**: Return-code based (`0` success, non-zero failure). No exception mechanism.
- **Shell scripts**: `set -e` for fail-fast; critical operations wrapped in conditionals with explicit error messages to stderr
- **GRUB modules**: Silent failure — most Ventoy GRUB commands fail gracefully by falling back to default behavior rather than halting boot
- **Plugson**: HTTP error responses (no structured error format)

### 15.4 Build Artifact Organization

Compiled binaries are placed in `INSTALL/` alongside the shell installer scripts. The build system does not use a separate `build/` or `dist/` directory — output binaries go directly to their deployment location in the source tree.

This means `INSTALL/` contains a mix of:
- Source (shell scripts)
- Compiled binaries (GRUB modules, EFI apps, tools)
- Boot images (cpio archives)
- Configuration files (grub.cfg)

### 15.5 Cross-Platform Abstractions

The codebase handles cross-platform differences at the source level:

- **Disk access**: `PhyDrive.c` (Windows `CreateFile`), `Core/ventoy_disk.c` (Linux `/dev/sdX`)
- **GUI**: Separate builds per toolkit (GTK2, GTK3, QT5, WebUI) with shared core logic
- **Filesystem**: Embedded FatFs (Windows installer) vs. OS-level mount (Linux installer)
- **Compilation**: Separate Makefiles per target (MinGW for Windows cross-compile, native gcc for Linux)

---

## 16. Developer Internals

### 16.1 Adding Support for a New Distribution

To add boot support for a new Linux distribution:

1. **Identify the initrd format** — Is it cpio, cpio.gz, cpio.xz, or something custom?
2. **Determine root-finding mechanism** — How does the distro's init/systemd locate its root filesystem?
3. **Create a hook script** in `IMG/cpio/ventoy/hook/{distro_name}/`:

```bash
#!/bin/sh
# ventoy-hook.sh for NewDistro
. /ventoy/hook/ventoy-hook-lib.sh

ventoy_udev_disk_common
```

4. **Test device-mapper availability** — If the distro's initrd includes `dmsetup`, the standard hook works. If not, compile `dm-mod.ko` for the distro's kernel version and add to `vtloopex/`.
5. **Add udev rule** if the distro uses a non-standard udev path
6. **Test**: Boot the ISO in both Legacy BIOS and UEFI modes on real hardware (VMs may mask firmware-specific issues)
7. **Rebuild initrd cpio** — The IMG build process repackages all hooks into the boot cpio archives

### 16.2 Modifying GRUB2 Ventoy Commands

Ventoy-specific GRUB commands live in `GRUB2/MOD_SRC/grub-2.04/grub-core/ventoy/`:

1. Modify or add command handlers in the `ventoy/` subdirectory
2. Register new commands in the GRUB module initialization
3. Rebuild GRUB for all four target architectures
4. Test boot with verbose GRUB output (`set debug=all` in grub.cfg)

### 16.3 Modifying the EDK2 UEFI Application

1. Source is in `EDK2/edk2_mod/`
2. The build uses EDK2's own build system (not Make directly)
3. Modify VDiskChain or VtoyUtil protocol handlers
4. Build with: `build -a X64 -t GCC5 -p VentoyPkg/VentoyPkg.dsc`
5. Test in QEMU with OVMF firmware before physical hardware

### 16.4 The VentoyWorker.sh Installation Logic

`VentoyWorker.sh` (in `INSTALL/`) contains the core installation logic:

- **Partition creation**: Calculates sizes based on disk capacity, creates MBR/GPT, formats Partition 1 (exFAT) and Partition 2 (FAT16)
- **Cluster size selection**: 128KB for disks >32GB, 32KB for ≤32GB (optimized for large sequential reads of ISO files)
- **VENTOY_SECTOR_NUM constant**: Defines the exact size of the VTOYEFI partition (32MB equivalent in sectors)
- **Boot sector installation**: Writes MBR boot code or GPT protective MBR + EFI boot entries
- **Non-destructive mode**: Uses `ntfsresize` (NTFS) or `resize2fs` (ext2/3/4) to shrink existing filesystems

### 16.5 Extending Plugson

To add a new configuration section to Plugson:

1. Add JSON parsing logic in `Plugson/src/ventoy_json.c`
2. Create the web UI page in `Plugson/www/` (AdminLTE template structure)
3. Add API endpoint in the civetweb handler registration
4. Rebuild Plugson (`cd Plugson/src && make`)

---

## 17. Performance Considerations

### 17.1 Boot Speed Factors

| Factor | Impact | Optimization |
|---|---|---|
| USB interface (2.0 vs 3.0) | 10x read speed difference | Use USB 3.0 ports; USB 3.0 drive |
| Number of ISOs on drive | Menu enumeration time increases | Use subdirectories + TreeView mode |
| ISO file size | Larger files = longer load time | No optimization possible (sequential read) |
| exFAT cluster size | Affects metadata overhead | Automatic (128KB for >32GB drives) |
| GRUB theme complexity | Affects menu render time | Use simple themes for fast boot |
| Persistence image size | Affects mount time | Size persistence images appropriately |

### 17.2 Filesystem Choice Impact

| Filesystem | Max File Size | Speed | Compatibility |
|---|---|---|---|
| exFAT (default) | 16 EB (effectively unlimited) | Fast | Windows, macOS, modern Linux |
| NTFS (non-destructive) | 16 TB | Fast | Windows native, Linux via NTFS-3G |
| ext2/3/4 (non-destructive) | 16 TB (ext4) | Fastest on Linux | Linux native; needs drivers on Windows |

---

## 18. Testing Strategy

The project has no automated test suite. Testing is performed manually across a matrix of:

- **Firmware**: Legacy BIOS, UEFI with Secure Boot off, UEFI with Secure Boot on
- **Hardware**: Multiple USB controller types (EHCI, XHCI), multiple UEFI implementations (AMI, Phoenix, Insyde, TianoCore)
- **Virtual machines**: QEMU/KVM (with OVMF for UEFI), VirtualBox, VMware
- **Distributions**: Regression testing across the 900+ supported distros (subset-based)

For contributors, the minimum test matrix should cover:
1. One Legacy BIOS boot (any Linux ISO)
2. One UEFI boot (any Linux ISO)
3. One Windows WIM boot (Windows 10/11 installer ISO)
4. One VHD boot (Windows VHD)
5. The specific distro/feature being modified

---

## 19. Improvement Opportunities

### 19.1 Architecture

- **GRUB2 upstream rebase** — Ventoy is pinned to GRUB 2.04 (released 2019). Upstream GRUB has had security fixes and feature improvements. The Ventoy modifications are extensive enough that rebasing is a multi-week effort, but the security exposure grows with time.
- **EDK2 upstream rebase** — Pinned to edk2-stable201911 (2019). Same concern as GRUB2.
- **iPXE upstream rebase** — Pinned to commit 3fe683e. Less critical than GRUB2/EDK2 as iPXE is a secondary boot path.

### 19.2 Build System

- **No parallel component builds** — Each component builds sequentially. Independent components (GRUB2 architectures, utilities) could build in parallel.
- **No incremental builds** — Changes to one module require a full rebuild cycle.
- **No CI/CD pipeline** — The Docker CI script exists but is not integrated with GitHub Actions or any CI service.

### 19.3 Code Quality

- **No automated testing** — The entire test strategy is manual. Unit tests for the C utilities (vtoycli, vtoygpt, vtoyfat) would catch regressions.
- **No static analysis** — No Coverity, cppcheck, or clang-tidy integration.
- **Mixed binary/source in INSTALL/** — Compiled artifacts committed alongside source makes the repository large and git history opaque.

### 19.4 Documentation

- **No formal schema for ventoy.json** — Configuration is defined implicitly by the C parser. A JSON Schema would enable validation tooling.
- **No developer onboarding guide** — The repository has no README, no CONTRIBUTING.md, no architecture documentation. This Admin Guide serves as the first comprehensive reference.
- **Hook system undocumented** — The per-distro hook mechanism is learned by reading existing hooks. A hook development guide would lower the contribution barrier.

### 19.5 Security

- **No reproducible builds** — The Docker CI script improves consistency but does not guarantee bit-for-bit reproducibility.
- **Precompiled binaries in repo** — The dmsetup, busybox, and veritysetup binaries are committed pre-built. Building from source and documenting the exact toolchain would improve trust.
- **MOK key management** — The same MOK key is used across all Ventoy installations. A compromised key would affect all users. Per-installation key generation would be more secure but dramatically less user-friendly.

---

## 20. Quick Reference

### 20.1 Installation Commands

```bash
# Install (destructive)
sudo sh Ventoy2Disk.sh -i /dev/sdX

# Install with GPT
sudo sh Ventoy2Disk.sh -i -g /dev/sdX

# Non-destructive install
sudo sh Ventoy2Disk.sh -i -n /dev/sdX

# Upgrade (preserves data)
sudo sh Ventoy2Disk.sh -u /dev/sdX

# Custom label + reserved space
sudo sh Ventoy2Disk.sh -i -L "MYBOOT" -r 1024 /dev/sdX

# Secure Boot partition resize
sudo vtoycli partresize -s /dev/sdX

# Launch Plugson
sudo ./VentoyPlugson.sh /dev/sdX

# Create Ventoy link file
./VentoyVlnk.sh -c /path/to/image.iso -o /ventoy-usb/link.vlnk
```

### 20.2 Key File Locations

| Location | Purpose |
|---|---|
| USB Partition 1: `/` | Boot images (.iso, .wim, .vhd, etc.) |
| USB Partition 1: `/ventoy/ventoy.json` | Plugin configuration |
| USB Partition 1: `/ventoy/theme/` | GRUB theme files |
| USB Partition 2: `/grub/grub.cfg` | GRUB boot configuration |
| USB Partition 2: `/EFI/BOOT/` | EFI bootloader binaries |
| USB Partition 2: `/ENROLL_THIS_KEY_IN_MOKMANAGER.cer` | Secure Boot MOK certificate |

### 20.3 Supported Image Formats

| Extension | Type | Boot Method |
|---|---|---|
| `.iso` | ISO 9660 | Loopback mount → OS-specific boot |
| `.wim` | Windows Imaging | wimboot → bootmgr → WinPE |
| `.img` | Raw disk image | Direct disk map |
| `.vhd` | Virtual Hard Disk | VDiskChain (UEFI) / disk map (BIOS) |
| `.vhdx` | VHD Extended | VDiskChain (UEFI) / disk map (BIOS) |
| `.efi` | EFI Application | Direct UEFI execution |
| `.vtoy` | Ventoy auto-install | Template-driven unattended install |
| `.vlnk` | Ventoy link | Pointer to image on another location |

### 20.4 GRUB Boot Menu Hotkeys

| Key | Action |
|---|---|
| `Enter` | Boot selected image |
| `e` | Edit boot parameters for selected entry |
| `c` | GRUB command line |
| `F5` | Language selection (theme-dependent) |
| Arrow keys | Navigate menu |

---

_Generated May 2026 from ventoy/Ventoy at de3e6c6. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._