qemu-alpine-ssh

Original source / Raw SKILL.md

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

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

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

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

## QEMU Startup Configuration

### Basic Command Structure

```bash
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

```bash
passwd
# Enter password twice when prompted
```

### 3. Configure Network (if needed)

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

### 4. Configure Package Repositories

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

### 5. Install OpenSSH

```bash
apk update
apk add openssh
```

### 6. Configure SSH for Root Login

Edit `/etc/ssh/sshd_config`:

```bash
# 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

```bash
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

```bash
#!/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:

```bash
ssh -p 2222 -o StrictHostKeyChecking=no root@localhost
# Or
ssh -p 2222 -o StrictHostKeyChecking=no [email protected]
```

### Verify Port Forwarding is Active

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

```bash
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:

```bash
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:

```bash
# 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
```