qemu-startup

QEMU VM 起動スキル

このスキルでは、特に ISO からの起動、telnet 接続、ヘッドレス操作を伴うタスク向けに、シリアルコンソールから QEMU 仮想マシンを起動する手順を説明します。

起動前の確認（最初に必ず実施）

QEMU の操作を始める前に、すべての前提条件を体系的に確認してください。この手順を省くと、試行錯誤による失敗が繰り返されます。

ツールの利用可否を確認

手順を決める前に、利用可能なツールを確認してください。

# 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

環境で実際に利用できるツールに応じて、方針を調整してください。

KVM の利用可否を確認

KVM が利用可能だと決めつけないでください。-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"

KVM が利用できない場合は、エラーを発生させるのではなく、-enable-kvm フラグを完全に省略してください。

リソースの確認

# 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 コマンドの組み立て

必要な情報をすべて先に集め、最初から正しいコマンドを組み立ててください。

シリアルコンソール接続に必要なパラメーター

telnet シリアルコンソールを使ったヘッドレス操作の場合：

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

よくあるパラメーターの落とし穴

問題	原因	解決策
シリアルコンソールではなく QEMU モニターのプロンプトが表示される	-monitor none が指定されていない、または -nographic の設定が競合している	-monitor none を明示的に追加する
「ポートはすでに使用中です」エラー	前回の QEMU インスタンスがまだ実行中	まず既存のプロセスをクリーンアップする
VM が起動中に停止する	KVM のないシステムで KVM フラグを指定している	-enable-kvm を削除する
出力が表示されない	シリアルコンソールが正しく設定されていない	-serial がアクセス可能な telnet ポートを指していることを確認する

KVM の条件付き使用

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

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

プロセス管理とクリーンアップ

冪等な起動手順

新しい QEMU インスタンスを起動する前に、競合するプロセスがないことを確認してください。

# 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

バックグラウンドプロセスの追跡

QEMU をバックグラウンドで実行する場合：

1. 起動直後にプロセス ID を記録する
2. シェルのジョブ制御を使用する場合は、バックグラウンドジョブ識別子を保存する
3. 起動後、プロセスが実際に実行中であることを確認する
4. どの試行／プロセスが現在有効なのかを追跡する

起動準備の確認

インテリジェントなポーリング（固定時間のスリープより推奨）

任意の時間だけ sleep するのではなく、実際に準備が整うまでポーリングしてください。

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

接続の確認

ポートがリッスン状態になった後、サービスが実際に利用可能か確認してください。

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

検証方法

段階的な検証アプローチ

1. プロセスの検証：QEMU プロセスが実行中であることを確認する
2. ポートの検証：telnet ポートがリッスン状態であることを確認する
3. 接続の検証：telnet 接続が成功することを確認する
4. サービスの検証：期待される出力（ログインプロンプト、シェルなど）を確認する

誤検知を避けるため、次に進む前に各段階を実施してください。

状態の照合

起動を複数回試行した場合は、どのプロセスが接続を処理しているのかを明確に特定してください。

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

よくある間違いとその回避方法

1. ツールが使えると思い込む：使用する前に、必ず ps、pkill、ss、nc の利用可否を確認する
2. KVM を早まって使用する：-enable-kvm を追加する前に、/dev/kvm が存在することを確認する
3. クリーンアップが不十分：再起動する前に、プロセスの終了とポートの解放を確認する
4. 根拠のないスリープ時間を設定する：固定時間の待機ではなく、起動準備の確認を伴うポーリングを使う
5. プロセスの状態が不明確：実際に実行中のバックグラウンドプロセスを追跡する
6. モニターとシリアルを混同する：-nographic だけでは QEMU モニターが表示される場合があることを理解し、シリアル出力のみを表示するには -monitor none を使う
7. 重複した検証を何度も行う：検証手順を一度設計し、体系的に実行する

判断の枠組み

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