--- name: qemu-alpine-ssh description: This skill provides guidance for setting up Alpine Linux virtual machines in QEMU with SSH access via port forwarding. It should be used when tasks involve running Alpine Linux in QEMU, configuring SSH access to VMs, setting up port forwarding for VM network access, or troubleshooting QEMU networking issues. --- # 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: ```bash # Check if target port is in use ss -tlnp | grep : # or lsof -i : ``` If the port is in use, either: - Kill the process using it: `fuser -k \/tcp` - Choose a different port ### 2. Check for Orphaned QEMU Processes Previous QEMU instances may still be running from failed attempts: ```bash ps aux | grep qemu-system pgrep -la qemu ``` Clean up any orphaned processes before starting a new instance: ```bash 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: ```bash qemu-system-x86_64 \ -m 512M \ -cdrom alpine.iso \ -boot d \ -netdev user,id=net0,hostfwd=tcp::-: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::-: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**: ```bash ifconfig eth0 up udhcpc -i eth0 ``` 3. **Set up package repositories**: ```bash setup-apkrepos -1 # or manually configure \/etc\/apk\/repositories ``` 4. **Install SSH server**: ```bash apk update apk add openssh ``` 5. **Configure SSH for root login**: ```bash sed -i 's\/#PermitRootLogin.*\/PermitRootLogin yes\/' \/etc\/ssh\/sshd_config # IMPORTANT: Verify the change grep "^PermitRootLogin" \/etc\/ssh\/sshd_config ``` 6. **Start SSH service**: ```bash 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 :` 3. **SSH connection**: `ssh -o ConnectTimeout=5 -p 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::-:22` - `hostfwd=tcp:127.0.0.1:-:22` - `hostfwd=tcp:0.0.0.0:-: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 :` - [ ] 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.