qemu-startup

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:

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

# 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

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

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

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

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

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

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

# 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