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:

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

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

Run nginx -T to see full configuration before making changes
Check for conflicting server blocks
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

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.log for debugging
Verify nginx status: systemctl status nginx and nginx -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

install-windows-3.11

Install Skill

SKILL.md