ventoy-extras/docs/RUNBOOK.md

Runbook: Building and refreshing a Ventoy USB

End-to-end procedure for taking a pile of downloaded ISOs and turning them into a categorised Ventoy boot stick. Designed to be safe to run repeatedly — adding new ISOs later is the same flow.

Audience and assumptions

• You already have a Ventoy-formatted USB drive (Ventoy installed via Ventoy2Disk or similar). If not, do that first at ventoy.net — these scripts only manage the payload, not the bootloader.
• You're on Windows with PowerShell 5.1+ or PowerShell 7+.
• You have all the ISOs you want to deploy in a single staging directory.

Drive layout this runbook produces

Two locations on the Ventoy USB matter:

Path on USB	What it holds
\iso-library\<os>\<version>\<arch>\*.iso	The actual ISO payload
\ventoy\ventoy.json	The menu definition Ventoy reads at boot

Ventoy itself only requires that ISOs exist somewhere on the data partition. The iso-library\ tree and the ventoy.json menu definition are layered on top to give a navigable boot menu.

---

Procedure

Step 1 — Stage the ISOs

Put every ISO you want into one directory. Filenames don't need to be "clean"; the parser handles vendor-supplied names like Win11_24H2_English_x64.iso, ubuntu-24.04.1-desktop-amd64.iso, Rocky-9.3-x86_64-minimal.iso, etc.

# Example staging area:
dir D:\iso-staging\
# Win11_24H2_English_x64.iso
# ubuntu-24.04.1-desktop-amd64.iso
# debian-12.5.0-amd64-netinst.iso
# Rocky-9.3-x86_64-minimal.iso
# clonezilla-live-3.1.2-22-amd64.iso

Step 2 — Dry-run the organiser

Always start with -DryRun to confirm the parser inferred the right os/version/arch for each file. Nothing is moved.

cd D:\Projects\own\forgejo\ventoy-extras
.\organise-isos.ps1 -SourceDir D:\iso-staging -DestDir D:\iso-library -DryRun

Output shows the planned target for every ISO. Look for anything that parsed as unknown or landed in a surprising slot — those are the cases to triage before committing to a move.

Step 3 — Run the organiser for real

Once the dry-run looks right:

.\organise-isos.ps1 -SourceDir D:\iso-staging -DestDir D:\iso-library

This moves (not copies) ISOs into iso-library\<os>\<version>\<arch>\. Source directory will be left empty (modulo non-ISO files). If you want copies kept, copy the staging directory aside first.

Step 4 — Generate ventoy.json

.\generate-ventoy-json.ps1 -IsoRoot D:\iso-library -OutFile D:\ventoy.json

The script prints the menu tree it built. Skim it to confirm sensible category groupings and labels.

Step 5 — Deploy to the USB

Plug in the Ventoy USB and note its drive letter (assume E: below).

# Mirror the iso-library tree onto the stick. Robocopy is safest because
# it handles long paths and resumes gracefully.
robocopy D:\iso-library E:\iso-library /MIR /R:1 /W:1

# Drop the menu file into the ventoy\ folder on the stick.
Copy-Item D:\ventoy.json E:\ventoy\ventoy.json -Force

E:\ventoy\ should already exist — Ventoy creates it when it installs the bootloader. If it doesn't, the Ventoy install is incomplete.

Step 6 — Verify the boot menu

Boot a machine (or a VM with USB passthrough) from the stick. The Ventoy menu should show category submenus rather than one flat list. If categories are missing, see Troubleshooting.

---

Adding ISOs later

You don't have to redo the whole flow. To add a single new ISO:

# Option A — let the organiser handle it
.\organise-isos.ps1 -SourceDir C:\downloads -DestDir D:\iso-library
.\generate-ventoy-json.ps1 -IsoRoot D:\iso-library -OutFile D:\ventoy.json
robocopy D:\iso-library E:\iso-library /MIR /R:1 /W:1
Copy-Item D:\ventoy.json E:\ventoy\ventoy.json -Force

# Option B — manually drop the ISO into the right tree, then just regenerate
Copy-Item C:\downloads\new.iso D:\iso-library\foo\1.2\x86_64\
.\generate-ventoy-json.ps1 -IsoRoot D:\iso-library -OutFile D:\ventoy.json
Copy-Item D:\ventoy.json E:\ventoy\ventoy.json -Force

robocopy /MIR will also remove ISOs from the stick that no longer exist in the local library — useful for retiring old versions, dangerous if your local copy is incomplete. Skip /MIR and use /E instead if you only want additive sync.

---

Troubleshooting

An ISO landed in unknown\unknown\noarch\

The filename didn't match any pattern in the OS map. Fix one of:

1. Rename the ISO to start with a recognised slug (e.g. myweirdspin-2024.iso becomes arch-2024-myweirdspin.iso).
2. Add a pattern to $osNormMap in organise-isos.ps1 — the regex matches against the lowercased first token of the cleaned filename.

After fixing, move the file back to staging and re-run.

Version parsed as unknown

Filename didn't contain a recognisable version. Either rename the file to include a \d+\.\d+ style version, or move it manually into the right <version> folder and regenerate.

Wrong architecture detected

organise-isos.ps1 checks arch tokens in priority order (see docs/organise-isos.md). If a token in the filename collides (e.g. a date that looks like an arch), rename the file or move it manually. Common gotcha: macOS-style x64 in the version string.

Ventoy boots but shows the old flat list

ventoy.json is in the wrong place. It must be at the root of the Ventoy data partition's ventoy\ folder, exactly: \ventoy\ventoy.json. Not \ventoy\config\, not anywhere else.

Ventoy reports JSON parse error on boot

Open ventoy.json in any editor and confirm it's valid JSON. The generator writes UTF-8 with no BOM, which Ventoy accepts. If you've hand-edited it, double-check for trailing commas (not valid JSON) or unbalanced brackets.

A category I want is missing

Add the slug to $categoryMap in generate-ventoy-json.ps1, then re-run. Unmapped slugs land in Other.

Access denied when moving ISOs

The source ISO is probably open in another process (mount, antivirus scan, browser download still finalising). Close it and retry. If on a removable drive, eject and reattach.

---

Recovery

"I ran organise-isos and now my ISOs are scattered, how do I get them back?"

The organiser only moves files into <DestDir>\<os>\<version>\<arch>\. To collapse everything back into one directory:

Get-ChildItem -Path D:\iso-library -Recurse -Filter *.iso |
  Move-Item -Destination D:\iso-staging

Then delete the empty tree:

Get-ChildItem -Path D:\iso-library -Recurse -Directory |
  Where-Object { -not (Get-ChildItem $_.FullName -Recurse -File) } |
  Remove-Item -Recurse

"My USB is borked"

These scripts don't touch the Ventoy bootloader — only the data partition content. To recover the bootloader, reinstall Ventoy with Ventoy2Disk.exe using the upgrade option (preserves the data partition) or the install option (wipes it). If you only modified ventoy.json and the boot menu now errors, just delete \ventoy\ventoy.json from the stick; Ventoy falls back to its default flat menu.

---

Smoke test before deploying

Want to confirm the menu before copying to a real USB? Mount the iso-library and ventoy.json into a VM with Ventoy installed, or use VBoxVentoy to boot from a VirtualBox USB device. Saves wear on physical sticks.