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:

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

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

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

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