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

```bash
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
   ```bash
   pip install websockify
   ```

2. **Start websockify**:
   ```bash
   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

```bash
ps aux | grep qemu
```

Confirm the process is running with expected parameters.

### 2. Test QMP Monitor Connection

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

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

### 3. Test VNC Connectivity

```bash
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