Install Windows 3.11 in QEMU
Overview
This skill provides procedural knowledge for installing and running Windows 3.11 in a QEMU virtual machine with VNC and web-based access. Windows 3.11 is a legacy 16-bit operating system that requires specific QEMU configuration for proper operation.
Pre-Installation Checklist
Before starting, verify the following:
- Check for expected file paths and naming conventions - Tests or acceptance criteria may expect specific paths (e.g.,
/tmp/qemu-monitor.sockvs/tmp/monitor-socket). Review any test files or documentation first. - Identify the disk image location and format - Common locations include
/app/isos/or/var/lib/qemu/ - Determine QEMU version compatibility - If the image is known to work with a specific QEMU version, note any compatibility flags needed
QEMU Configuration for Windows 3.11
Essential Parameters
Windows 3.11 requires specific QEMU parameters for proper operation:
qemu-system-i386 \
-drive file=/path/to/win311.img,format=raw,if=ide \
-m 32 \
-vga cirrus \
-vnc :1 \
-monitor unix:/tmp/qemu-monitor.sock,server,nowait \
-snapshot \
-k en-usCritical Parameters Explained
| Parameter | Purpose | Notes |
|---|---|---|
-vga cirrus | VGA adapter type | REQUIRED for Windows 3.11 display compatibility. Alternatives: -vga std. Without this, display may not work. |
-m 32 | Memory allocation | 32MB is appropriate for Windows 3.11 |
-monitor unix:/tmp/qemu-monitor.sock,server,nowait | QMP monitor socket | Use the expected socket path - check tests/docs for naming conventions |
-snapshot | Immutable disk mode | Prevents writes to the original image |
-k en-us | Keyboard layout | US keyboard mapping |
if=ide | Disk interface | IDE interface for legacy OS compatibility |
Common VGA Options for Legacy Systems
-vga cirrus- Best compatibility for Windows 3.x/9x-vga std- Standard VGA, good fallback option-vga vmware- VMware SVGA (may not work with Windows 3.11)
VNC and Web Access Setup
VNC Configuration
When using -vnc:1, the VNC server runs on port 5901 (5900 + display number).
noVNC Web Interface
To provide web-based access to the VNC session:
- Install websockify: Bridges WebSocket connections to VNC
pip install websockify - Start websockify:
websockify --web=/usr/share/novnc 6080 localhost:5901 - Configure nginx (if needed):
- Check existing nginx configuration with nginx -T before making changes - Look for conflicting server blocks or port bindings - Create a dedicated configuration file in /etc/nginx/sites-available/
Verification Strategies
1. Verify QEMU Process
ps aux | grep qemuConfirm the process is running with expected parameters.
2. Test QMP Monitor Connection
echo '{"execute": "qmp_capabilities"}' | nc -U /tmp/qemu-monitor.sockExpected response should include {"return": {}}.
3. Test VNC Connectivity
nc -zv localhost 59014. Visual Verification (Critical)
Do not mark boot completion as verified without visual confirmation. Options:
- Take a VNC screenshot using a tool like
vncsnapshot - Use a headless browser to capture the noVNC web interface
- Connect via VNC client and manually verify
5. Wait for Boot Completion
Windows 3.11 boot time varies. Wait at least 30-60 seconds before testing, not just 10 seconds.
Common Pitfalls
Missing VGA Configuration
Problem: QEMU starts but display is blank or garbled. Solution: Add -vga cirrus or -vga std to the QEMU command.
Wrong Socket Path
Problem: Tests fail to connect to QMP monitor. Solution: Check expected socket path in tests/documentation. Common paths:
/tmp/qemu-monitor.sock/tmp/monitor-socket/var/run/qemu-monitor.sock
Nginx Configuration Conflicts
Problem: Nginx fails to start or proxy doesn't work. Solution:
- Run
nginx -Tto see full configuration before making changes - Check for conflicting server blocks
- Ensure no duplicate
listendirectives
Premature Completion Claims
Problem: Marking tasks complete without actual verification. Solution: Always verify visually that Windows 3.11 reaches the desktop before claiming completion.
QEMU Version Compatibility
Problem: Image created for older QEMU version doesn't work correctly. Solution:
- Check if legacy machine types are needed:
-M pc-i440fx-2.0 - Review QEMU changelog for breaking changes between versions
- Test with compatibility flags if available
Troubleshooting Workflow
- Check QEMU is running:
ps aux | grep qemu - Verify VNC port is open:
netstat -tlnp | grep 590 - Test QMP socket:
nc -U /tmp/qemu-monitor.sock - Check QEMU logs: Run QEMU with
-D /tmp/qemu.logfor debugging - Verify nginx status:
systemctl status nginxandnginx -t - Check websockify:
ps aux | grep websockify
Approach Summary
- Research first: Check tests/docs for expected paths and configurations
- Configure QEMU properly: Include VGA adapter and correct socket path
- Set up access layer: VNC, websockify, nginx in sequence
- Verify each component: Test connectivity at each layer
- Visual confirmation: Always verify Windows 3.11 actually boots to desktop