install-windows-311

name	install-windows-3.11
description	Guidance for installing and running Windows 3.11 in QEMU with VNC access and web-based noVNC interface. This skill should be used when tasks involve setting up legacy Windows 3.11 environments, configuring QEMU for DOS/Windows 3.x, or creating virtualized retro computing setups with remote access capabilities.

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:

1. Check for expected file paths and naming conventions - Tests or acceptance criteria may expect specific paths (e.g., /tmp/qemu-monitor.sock vs /tmp/monitor-socket). Review any test files or documentation first.
2. Identify the disk image location and format - Common locations include /app/isos/ or /var/lib/qemu/
3. 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-us

Critical 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:

1. Install websockify: Bridges WebSocket connections to VNC

   pip install websockify
   

2. Start websockify:

   websockify --web=/usr/share/novnc 6080 localhost:5901
   

3. 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 qemu

Confirm the process is running with expected parameters.

2. Test QMP Monitor Connection

echo '{"execute": "qmp_capabilities"}' | nc -U /tmp/qemu-monitor.sock

Expected response should include {"return": {}}.

3. Test VNC Connectivity

nc -zv localhost 5901

4. 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:

1. Run nginx -T to see full configuration before making changes
2. Check for conflicting server blocks
3. Ensure no duplicate listen directives

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

1. Check QEMU is running: ps aux | grep qemu
2. Verify VNC port is open: netstat -tlnp | grep 590
3. Test QMP socket: nc -U /tmp/qemu-monitor.sock
4. Check QEMU logs: Run QEMU with -D /tmp/qemu.log for debugging
5. Verify nginx status: systemctl status nginx and nginx -t
6. Check websockify: ps aux | grep websockify

Approach Summary

1. Research first: Check tests/docs for expected paths and configurations
2. Configure QEMU properly: Include VGA adapter and correct socket path
3. Set up access layer: VNC, websockify, nginx in sequence
4. Verify each component: Test connectivity at each layer
5. Visual confirmation: Always verify Windows 3.11 actually boots to desktop