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:

Record the process ID immediately after starting
Store the background job identifier if using shell job control
Verify the process is actually running after starting
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

Process verification: Confirm QEMU process is running
Port verification: Confirm telnet port is listening
Connection verification: Confirm telnet connection succeeds
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

Assuming tool availability: Always check for
```
ps
```
,
```
pkill
```
,
```
ss
```
,
```
nc
```
before using them
Premature KVM usage: Check
```
/dev/kvm
```
exists before adding
```
-enable-kvm
```
Incomplete cleanup: Verify process termination and port release before restarting
Arbitrary sleep times: Use polling with readiness checks instead of fixed delays
Unclear process state: Track which background process is actually running
Monitor/serial confusion: Understand that
```
-nographic
```
alone may show QEMU monitor; use
```
-monitor none
```
for clean serial output
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

qemu-startup

NPX Install

Tags

SKILL.md Content

QEMU VM Startup Skill

Pre-Flight Checks (Critical First Step)

Tool Availability Check

KVM Availability Check

Resource Verification

QEMU Command Construction

Essential Parameters for Serial Console Access

Common Parameter Pitfalls

Conditional KVM Usage

Process Management and Cleanup

Idempotent Startup Procedure

Background Process Tracking

Readiness Verification

Intelligent Polling (Preferred over Fixed Sleep)

Connection Verification

Verification Strategies

Layered Verification Approach

State Reconciliation

Common Mistakes to Avoid

Decision Framework