qemu-alpine-ssh

Original：🇺🇸 English

Translated

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.

1installs

Sourceletta-ai/skills

Added on2026-02-07

NPX Install

npx skill4agent add letta-ai/skills qemu-alpine-ssh

SKILL.md Content

View Translation Comparison →

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 =

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

Do NOT iterate on syntax variations
Immediately check port availability (see Diagnostic-First Approach)
Kill any orphaned QEMU processes
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 root@127.0.0.1

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:

Is QEMU running? (
```
ps aux | grep qemu
```
)
Is the host port listening? (
```
ss -tlnp | grep 2222
```
)
Is the guest network up? (In VM:
```
ip addr
```
)
Is SSH service running? (In VM:
```
rc-service sshd status
```
)
Is root login permitted? (Check
```
/etc/ssh/sshd_config
```
)
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

qemu-alpine-ssh

NPX Install

Tags

SKILL.md Content

QEMU Alpine SSH Setup

Overview

Diagnostic-First Approach

1. Check Port Availability

2. Check for Existing QEMU Processes

3. Verify ISO/Image Files Exist

QEMU Startup Configuration

Basic Command Structure

Port Forwarding Syntax

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

Alpine Linux Configuration Steps

1. Boot and Login

2. Set Root Password

3. Configure Network (if needed)

4. Configure Package Repositories

5. Install OpenSSH

6. Configure SSH for Root Login

7. Start SSH Service

Automation with Expect Scripts

Script Structure

Expect Script Best Practices

Verification Strategies

Verify SSH Connectivity

Verify Port Forwarding is Active

Verify SSH Service in Guest

Common Pitfalls

1. Orphaned QEMU Processes

2. Premature Syntax Debugging

3. Missing Service Enablement

4. SSH Configuration Not Applied

5. Network Not Configured

6. Repository Not Configured

Troubleshooting Checklist

Resource Cleanup