1178 Name Skill B649021a

---
name: qemu-startup
description: Guidance for starting and configuring QEMU virtual machines with proper serial console access. This skill should be used when tasks involve starting QEMU VMs, configuring serial console or telnet access, booting ISO images, or troubleshooting VM startup issues. Covers pre-flight checks, idempotent startup procedures, and intelligent readiness verification.
---

# QEMU VM Startup Skill

This skill provides procedural guidance for starting QEMU virtual machines with serial console access, particularly for tasks involving ISO boot, telnet connectivity, and headless operation.

## Pre-Flight Checks (Critical First Step)

Before attempting any QEMU operations, verify all prerequisites systematically. Skipping this step leads to iterative failures.

### Tool Availability Check

Verify available tools before planning the approach:

```bash
# Check QEMU installation
which qemu-system-x86_64 || which qemu-system-i386

# Check for process management tools (availability varies by environment)
which ps pkill pgrep kill 2>/dev/null

# Check for network diagnostic tools
which nc netstat ss lsof 2>/dev/null

# Check for telnet client
which telnet
```

Adapt the strategy based on which tools are actually available in the environment.

### KVM Availability Check

Never assume KVM is available. Check before using `-enable-kvm`:

```bash
# Check if KVM module is loaded
ls /dev/kvm 2>/dev/null && echo "KVM available" || echo "KVM not available"

# Alternative check
grep -E '(vmx|svm)' /proc/cpuinfo > /dev/null && echo "CPU supports virtualization"
```

If KVM is not available, omit the `-enable-kvm` flag entirely rather than letting it fail.

### Resource Verification

```bash
# Verify the ISO/disk image exists and is readable
ls -la /path/to/image.iso

# Check if the target port is already in use
# Use whichever tool is available:
nc -z localhost PORT 2>/dev/null && echo "Port in use"
# or
netstat -tuln | grep PORT
# or
ss -tuln | grep PORT
```

## QEMU Command Construction

Build the correct command from the start by gathering all necessary information first.

### Essential Parameters for Serial Console Access

For headless operation with telnet serial console:

```bash
qemu-system-x86_64 \
    -m 512 \                           # Memory (adjust as needed)
    -cdrom /path/to/image.iso \        # Boot ISO
    -nographic \                       # No graphical output
    -serial telnet:localhost:PORT,server,nowait \  # Serial on telnet
    -monitor none                      # Disable QEMU monitor on stdio
```

### Common Parameter Pitfalls

| Issue | Cause | Solution |
|-------|-------|----------|
| QEMU monitor prompt instead of serial console | Missing `-monitor none` or conflicting `-nographic` settings | Add `-monitor none` explicitly |
| "Port already in use" error | Previous QEMU instance still running | Clean up existing processes first |
| VM hangs at boot | KVM flag on system without KVM | Remove `-enable-kvm` |
| No output visible | Serial console not properly configured | Ensure `-serial` points to accessible telnet port |

### Conditional KVM Usage

```bash
# Build command conditionally
if [ -e /dev/kvm ]; then
    KVM_FLAG="-enable-kvm"
else
    KVM_FLAG=""
fi

qemu-system-x86_64 $KVM_FLAG -m 512 ...
```

## Process Management and Cleanup

### Idempotent Startup Procedure

Before starting a new QEMU instance, ensure no conflicting processes exist:

```bash
# Find existing QEMU processes (use available tools)
ps aux | grep qemu | grep -v grep

# If pkill available:
pkill -f "qemu.*PORT" 2>/dev/null

# If only kill available, find PID first:
# Then: kill PID

# Wait briefly for port release
sleep 2

# Verify port is free before starting
```

### Background Process Tracking

When running QEMU in background:

1. Record the process ID immediately after starting
2. Store the background job identifier if using shell job control
3. Verify the process is actually running after starting
4. Keep track of which attempt/process is the active one

## Readiness Verification

### Intelligent Polling (Preferred over Fixed Sleep)

Instead of arbitrary `sleep` durations, poll for actual readiness:

```bash
# Poll for port availability with timeout
MAX_WAIT=60
WAITED=0
while ! nc -z localhost PORT 2>/dev/null; do
    sleep 2
    WAITED=$((WAITED + 2))
    if [ $WAITED -ge $MAX_WAIT ]; then
        echo "Timeout waiting for VM"
        exit 1
    fi
done
echo "Port is listening after ${WAITED}s"
```

### Connection Verification

After port is listening, verify actual service readiness:

```bash
# Test telnet connection and look for expected output
# Use timeout to avoid hanging
timeout 10 telnet localhost PORT

# For automated verification, check for login prompt
echo "" | timeout 5 telnet localhost PORT 2>&1 | grep -i "login"
```

## Verification Strategies

### Layered Verification Approach

1. **Process verification**: Confirm QEMU process is running
2. **Port verification**: Confirm telnet port is listening
3. **Connection verification**: Confirm telnet connection succeeds
4. **Service verification**: Confirm expected output (login prompt, shell, etc.)

Perform each layer before proceeding to avoid false positives.

### State Reconciliation

If multiple startup attempts were made, explicitly identify which process is serving connections:

```bash
# Find process listening on the port
lsof -i :PORT  # if available
# or
netstat -tlnp | grep PORT
# or
ss -tlnp | grep PORT
```

## Common Mistakes to Avoid

1. **Assuming tool availability**: Always check for `ps`, `pkill`, `ss`, `nc` before using them
2. **Premature KVM usage**: Check `/dev/kvm` exists before adding `-enable-kvm`
3. **Incomplete cleanup**: Verify process termination and port release before restarting
4. **Arbitrary sleep times**: Use polling with readiness checks instead of fixed delays
5. **Unclear process state**: Track which background process is actually running
6. **Monitor/serial confusion**: Understand that `-nographic` alone may show QEMU monitor; use `-monitor none` for clean serial output
7. **Multiple redundant verifications**: Design verification sequence once, execute systematically

## Decision Framework

```
Start
  │
  ├─► Pre-flight checks pass?
  │     No ──► Adapt approach based on available tools
  │     Yes ──► Continue
  │
  ├─► KVM available?
  │     No ──► Omit -enable-kvm flag
  │     Yes ──► Include -enable-kvm flag
  │
  ├─► Port already in use?
  │     Yes ──► Clean up existing processes, wait for port release
  │     No ──► Continue
  │
  ├─► Start QEMU with complete command
  │
  ├─► Poll for port readiness (with timeout)
  │
  ├─► Verify connection and expected output
  │
  └─► Confirm final state explicitly
```