QEMU Alpine SSH Setup

Overview

This skill guides the setup of Alpine Linux virtual machines in QEMU with SSH access configured through port forwarding. The typical goal is to have a running Alpine VM accessible via SSH on a forwarded host port.

Critical Pre-Flight Checks

Before starting QEMU, always perform these checks to avoid common failures:

1. Check for Port Conflicts

The most common cause of QEMU startup failures is a port already in use. Always check before starting:

# Check if target port is in use
ss -tlnp | grep :<port>
# or
lsof -i :<port>

If the port is in use, either:

• Kill the process using it: fuser -k <port>/tcp
• Choose a different port

2. Check for Orphaned QEMU Processes

Previous QEMU instances may still be running from failed attempts:

ps aux | grep qemu-system
pgrep -la qemu

Clean up any orphaned processes before starting a new instance:

pkill -f "qemu-system-x86_64" || true
sleep 1
# Verify cleanup
pgrep qemu && echo "WARNING: QEMU still running" || echo "Clean"

3. Verify Required Files

Ensure ISO/disk images exist and are accessible before attempting to boot.

Recommended Approach

Phase 1: Start QEMU with Port Forwarding

Start QEMU with user-mode networking and port forwarding:

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

Key parameters:

• -m 512M: Allocate sufficient memory (256MB minimum, 512MB recommended)
• -netdev user,id=net0,hostfwd=tcp::<port>-:22: User-mode networking with port forwarding
• -nographic: Console-only mode for scripted interaction

Phase 2: Configure the VM

After VM boots, perform configuration in this order:

1. Set root password:

   passwd
   

2. Configure networking inside VM:

   ifconfig eth0 up
   udhcpc -i eth0
   

3. Set up package repositories:

   setup-apkrepos -1
   # or manually configure /etc/apk/repositories
   

4. Install SSH server:

   apk update
   apk add openssh
   

5. Configure SSH for root login:

   sed -i 's/#PermitRootLogin.*/PermitRootLogin yes/' /etc/ssh/sshd_config
   # IMPORTANT: Verify the change
   grep "^PermitRootLogin" /etc/ssh/sshd_config
   

6. Start SSH service:

   rc-update add sshd
   rc-service sshd start
   

Phase 3: Verify Setup

After configuration, verify each component:

1. SSH service running: rc-status | grep sshd
2. Port forwarding working: From host, ss -tlnp | grep :<host_port>
3. SSH connection: ssh -o ConnectTimeout=5 -p <host_port> root@localhost

Common Pitfalls

Port Binding Failures

Symptom: QEMU fails to start or port forwarding doesn't work.

Common mistake: Trying different hostfwd syntax variations when the syntax is correct but the port is in use.

Correct approach: Always check port availability first. All of these syntaxes are valid:

• hostfwd=tcp::<port>-:22
• hostfwd=tcp:127.0.0.1:<port>-:22
• hostfwd=tcp:0.0.0.0:<port>-:22

If one fails, the issue is usually NOT the syntax.

SSH Connection Refused

Symptom: Cannot connect via SSH even though VM appears to be running.

Check in order:

1. Is sshd running in VM?
2. Is PermitRootLogin yes set in sshd_config?
3. Was sshd restarted after config change?
4. Is the network interface up with an IP?

Network Not Working in VM

Symptom: Cannot install packages, DNS fails.

Resolution:

1. Bring up interface: ifconfig eth0 up
2. Get DHCP lease: udhcpc -i eth0
3. If DNS fails: echo "nameserver 8.8.8.8" > /etc/resolv.conf

Verification Strategies

Incremental Verification

Verify each step before proceeding to the next. Do not assume success.

After running commands that modify configuration:

• Use grep or cat to verify changes took effect
• Check service status after starting services
• Test connectivity at each stage

Final Verification Checklist

Before declaring the task complete, verify ALL of:

• QEMU process is running: pgrep -la qemu
• Host port is listening: ss -tlnp | grep :<port>
• SSH service running in VM: rc-status | grep sshd
• Root login enabled: config shows PermitRootLogin yes
• VM has network: ip addr shows IP on eth0
• SSH connection succeeds from host

Debugging Failed States

When things fail, diagnose systematically rather than trying random variations:

1. Identify the failure point: Which specific step failed?
2. Check prerequisites: Are all prerequisites for that step satisfied?
3. Examine error messages: What exactly does the error say?
4. Check resource conflicts: Ports, processes, file locks
5. Verify intermediate state: Did previous steps actually succeed?

For detailed troubleshooting steps, consult references/troubleshooting.md.

Resources

references/

• troubleshooting.md: Detailed diagnosis and resolution steps for common issues including port conflicts, SSH failures, and network configuration problems.