qemu-alpine-ssh

name	qemu-alpine-ssh
description	Guidance for setting up QEMU virtual machines with Alpine Linux and SSH access. This skill should be used when tasks involve starting QEMU with Alpine Linux ISO, configuring port forwarding for SSH, setting up OpenSSH server in Alpine, or troubleshooting QEMU networking issues.

QEMU Alpine SSH Setup

Overview

This skill provides procedural guidance for setting up QEMU virtual machines running Alpine Linux with SSH access configured. It covers VM startup, network port forwarding, Alpine system configuration, and SSH server setup.

Diagnostic-First Approach

Before attempting any QEMU setup or troubleshooting syntax, verify preconditions first:

1. Check Port Availability

Before starting QEMU with port forwarding, verify the target port is not in use:

# Preferred methods (if available)
ss -tlnp | grep :2222
netstat -tlnp | grep :2222
lsof -i :2222

# Fallback when standard tools unavailable
cat /proc/net/tcp | awk '{print $2}' | grep -i ":08AE"  # 08AE is hex for 2222

Port 2222 in hex is 08AE. Common ports: 22 = 0016, 2222 = 08AE, 8080 = 1F90.

2. Check for Existing QEMU Processes

Always verify no orphaned QEMU processes exist:

# Find QEMU processes
ps aux | grep qemu
pgrep -la qemu

# Kill all QEMU processes if needed
pkill -9 qemu-system
pkill -9 qemu

3. Verify ISO/Image Files Exist

Confirm required files are present before starting QEMU:

ls -la /path/to/alpine.iso
file /path/to/alpine.iso

QEMU Startup Configuration

Basic Command Structure

qemu-system-x86_64 \
  -m 512 \
  -cdrom /path/to/alpine.iso \
  -boot d \
  -nographic \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

Port Forwarding Syntax

The correct hostfwd syntax is: tcp::[host_port]-:[guest_port]

Valid examples:

• hostfwd=tcp::2222-:22 - Forward host 2222 to guest 22
• hostfwd=tcp:127.0.0.1:2222-:22 - Bind only to localhost
• hostfwd=tcp:0.0.0.0:2222-:22 - Bind to all interfaces

Common Error: "Could not set up host forwarding rule"

This error typically means the port is already in use, NOT a syntax error. When encountering this:

1. Do NOT iterate on syntax variations
2. Immediately check port availability (see Diagnostic-First Approach)
3. Kill any orphaned QEMU processes
4. Retry with the same command

Alpine Linux Configuration Steps

1. Boot and Login

Alpine boots to a login prompt. Login as root (no password initially).

2. Set Root Password

passwd
# Enter password twice when prompted

3. Configure Network (if needed)

setup-interfaces
# Select eth0, dhcp, no manual config, done
ifup eth0

4. Configure Package Repositories

setup-apkrepos
# Select a mirror (enter number) or 'f' for fastest

5. Install OpenSSH

apk update
apk add openssh

6. Configure SSH for Root Login

Edit /etc/ssh/sshd_config:

# Enable root login with password
sed -i 's/#PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
sed -i 's/#PasswordAuthentication.*/PasswordAuthentication yes/' /etc/ssh/sshd_config

7. Start SSH Service

rc-update add sshd
rc-service sshd start
# Or simply: /etc/init.d/sshd start

Automation with Expect Scripts

For non-interactive setup, use expect scripts. Key considerations:

Script Structure

#!/usr/bin/expect -f
set timeout 300

spawn qemu-system-x86_64 -m 512 -cdrom alpine.iso -boot d -nographic \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

# Wait for login prompt
expect "login:"
send "root\r"

# Continue with setup commands...
expect "# "
send "passwd\r"
expect "New password:"
send "password123\r"
expect "Retype password:"
send "password123\r"

# IMPORTANT: End with 'interact' not 'interac)' or other typos
interact

Expect Script Best Practices

• Set adequate timeout (300+ seconds for network operations)
• Include error handling for network timeouts during apk update
• Verify script syntax before execution (check for typos like interac))
• Use explicit \r for carriage returns, not \n

Verification Strategies

Verify SSH Connectivity

From the host:

ssh -p 2222 -o StrictHostKeyChecking=no root@localhost
# Or
ssh -p 2222 -o StrictHostKeyChecking=no root@127.0.0.1

Verify Port Forwarding is Active

# Check QEMU process shows hostfwd
ps aux | grep qemu | grep hostfwd

# Check port is listening
ss -tlnp | grep 2222

Verify SSH Service in Guest

Inside the Alpine VM:

rc-service sshd status
netstat -tlnp | grep :22

Common Pitfalls

1. Orphaned QEMU Processes

After killing a QEMU session, orphaned processes may still hold ports. Always run pkill qemu-system before retrying failed commands.

2. Premature Syntax Debugging

When port forwarding fails, the instinct is to try different syntax variations. This wastes time. The hostfwd syntax is well-documented and rarely the issue—check port availability first.

3. Missing Service Enablement

Installing openssh is not enough. The service must be:

• Started: rc-service sshd start
• Enabled for boot: rc-update add sshd

4. SSH Configuration Not Applied

After modifying /etc/ssh/sshd_config, restart the service:

rc-service sshd restart

5. Network Not Configured

Alpine minimal ISO does not auto-configure networking. Run setup-interfaces and ifup eth0 before attempting to install packages.

6. Repository Not Configured

apk update will fail without configured repositories. Run setup-apkrepos first.

Troubleshooting Checklist

When SSH connection fails, check in order:

1. Is QEMU running? (ps aux | grep qemu)
2. Is the host port listening? (ss -tlnp | grep 2222)
3. Is the guest network up? (In VM: ip addr)
4. Is SSH service running? (In VM: rc-service sshd status)
5. Is root login permitted? (Check /etc/ssh/sshd_config)
6. Is the password set? (Try passwd again in VM)

Resource Cleanup

After completing tasks, clean up:

# Kill QEMU processes
pkill qemu-system

# Verify ports released
ss -tlnp | grep 2222  # Should return nothing

# Remove temporary files if created
rm -f /tmp/alpine-setup.exp