Repository navigation
Provisioning a new rig
How to turn a bare Windows XP machine into a test rig, from zero. Everything needed is in the repository — nothing has to be recovered from an old box.
Written because the existing rig was built incrementally over many sessions and the knowledge lived only in the scripts and the session log. If the box died, rebuilding it meant archaeology. This page is the answer to "a test rig that has never seen this project".
- A 32-bit Windows XP SP3 machine. Real hardware is the point — V86 and DPMI on real
silicon cannot be tested in a VM, and QEMU+HVF aborts on DOS/4GW's paged 32-bit protected
mode even under stock
ntvdm. - It on the same LAN as your build machine.
- An account you can log into interactively. The VDM host needs an interactive session (it is launched via the IFEO key from a real desktop), so a service or a headless login will not do.
./scripts/build.sh # -> build/ntvdmhost.exe (the host)
./scripts/build-controld.sh # -> build/controld.exe (control daemon)
./scripts/build-rigshot.sh # -> build/rigshot.exe (desktop capture)
./scripts/check-imports.sh # assert every import is an XP-shipped DLLOn the XP box, create a folder and share it as ntvdmex, readable and writable by the
account you will use. The canonical path the scripts assume is:
C:\Documents and Settings\All Users\Documents\ntvdmex
From the dev machine:
mount_smbfs -N //guest@<box-ip>/ntvdmex /tmp/xpshare
⚠️ The mount drops silently. When it does, writes to/tmp/xpshareland in a local directory that shadows the mountpoint and everything succeeds against nothing. Tell:controld.txtandbm/are missing. Fix: delete the stray local files and remount.
⚠️ Ping is filtered. ICMP silence does not mean the box is down — write a probe file.
mkdir -p /tmp/xpshare/bm
cp build/ntvdmhost.exe build/controld.exe build/rigshot.exe /tmp/xpshare/bm/
cp scripts/bm/*.bat /tmp/xpshare/bm/
cp scripts/bm/rt.bat /tmp/xpshare/bm/Guest programs go in the share too — MS-DOS's COMMAND.COM and ATTRIB.EXE are extracted
from the vendored floppy images with:
python3 tools/dostest/extract-dos-file.py COMMAND.COM guest/
guest/,games/,msdos-622/andvm/are gitignored on purpose: they are Microsoft's and id's, not ours. Supply your own copies.tools/doomoracle/likewise needs aDOOM1.WADyou provide.
Log in interactively and run bm\runwatch.bat from the share. It:
- copies
rt.battoC:\WINDOWS\— this is the copy the watcher actually runs - installs itself into Startup, so a reboot auto-recovers the watcher
- starts
controld.exe - then polls
cmd.txtforever
Leave that window open.
⚠️ This step needs a human at the box exactly once. After it, the machine is remotely recoverable:controldacceptsexec, so a dead watcher can be restarted from the dev machine. Before that existed, a broken watcher meant physical access.
⚠️ Copyrunwatch.batwith CRLF line endings. Written with LF,cmd.execannot resolvegoto loop, so the watcher runs one iteration and dies — while still writingwatcher.txtonce, which makes it look alive. That cost a session.
# control daemon -- should update within ~3 seconds
cat /tmp/xpshare/controld.txt
# watcher -- the ONLY reliable signal is cmd.txt being CONSUMED
printf 'selftest\r\n' > /tmp/xpshare/cmd.tmp && mv /tmp/xpshare/cmd.tmp /tmp/xpshare/cmd.txt
sleep 5 && ls /tmp/xpshare/cmd.txt 2>/dev/null || echo "consumed -- watcher alive"
⚠️ watcher.txtmerely existing means nothing — a dead watcher and a busy watcher look identical. A frozenwatcher.txtwhilecontrold.txtkeeps beating is the signature of a dead watcher.
reg add "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\ntvdm.exe" ^
/v Debugger /t REG_SZ /d "C:\ntvdmex\ntvdmhost.exe" /f
⚠️ ⚠️ This is the single most important thing to get right, and the easiest to get silently wrong. With the key absent, every test runs under stockntvdmand still "passes" — more than one session has gone into debugging code that was never executed. With it present, every DOS and Win16 launch on the box goes to NTVDMEX, and there is no WOW layer yet, so 16-bit Windows programs break.Treat it as a per-run setting, not a machine setting.
rt_stock.batdrops it, restores it on every exit path, and proves the state withreg query— copy that pattern.
printf 'doom\r\n' > /tmp/xpshare/cmd.tmp && mv /tmp/xpshare/cmd.tmp /tmp/xpshare/cmd.txtThen capture the screen to confirm what actually happened:
# via controld: exec cmd /c ""<share>\bm\rigshot.exe" shot "<share>\shot.bmp""A good first run shows the caption Microsoft Windows XP Virtual DOS Machine and a status
strip reading DOOM.EXE | 32-bit | Protected mode.
Read Traps and lessons. In particular: checksum what you deploy
(there are two EXEs and deploying the wrong one still "passes" off a stale log), never edit
a .bat in Python text mode, and remember the box is not necessarily unattended —
desktop-level behaviour is not the program's until you know nobody is using it.
Understand it
Work on it
- Building and running
- Testing and oracles
- The bare-metal rig
- Provisioning a new rig
⚠️ Traps and lessons
Live state
- STATE.md — where we are
- Issues — what's left
- Session archive
Published from docs/wiki/.
Edit there, not here — tools/wiki/publish.sh overwrites this wiki.