loc_az_hci/docs/troubleshooting/vm-troubleshooting.md

# VM Troubleshooting Guide

Comprehensive troubleshooting guide for virtual machine issues.

## Common VM Issues

### VM Won't Boot

**Symptoms:**
- VM starts but doesn't boot
- Boot loop
- Black screen

**Solutions:**

1. **Check Boot Order:**
   ```bash
   qm config <vmid> | grep boot
   qm set <vmid> --boot order=scsi0
   ```

2. **Verify Disk Attachment:**
   ```bash
   qm config <vmid> | grep scsi0
   ```

3. **Check BIOS/UEFI Settings:**
   ```bash
   qm config <vmid> | grep bios
   # For UEFI: qm set <vmid> --bios ovmf
   # For BIOS: qm set <vmid> --bios seabios
   ```

4. **Review VM Logs:**
   ```bash
   journalctl -u qemu-server@<vmid> -f
   ```

### VM Performance Issues

**Symptoms:**
- Slow response times
- High CPU usage
- Memory issues

**Solutions:**

1. **Check Resource Allocation:**
   ```bash
   qm config <vmid> | grep -E "memory|cpu|cores"
   ```

2. **Monitor Resource Usage:**
   ```bash
   qm status <vmid>
   ```

3. **Optimize VM Settings:**
   ```bash
   # Enable CPU type for better performance
   qm set <vmid> --cpu host
   
   # Enable IO thread
   qm set <vmid> --iothread 1
   
   # Set cache mode
   qm set <vmid> --cache none
   ```

### Network Connectivity Issues

**Symptoms:**
- VM cannot reach network
- Cannot SSH to VM
- Network interface not working

**Solutions:**

1. **Check Network Configuration:**
   ```bash
   qm config <vmid> | grep net
   ```

2. **Verify Bridge Configuration:**
   ```bash
   ip link show vmbr0
   ```

3. **Test Network from Host:**
   ```bash
   ping <vm-ip>
   ```

4. **Check VM Network Interface:**
   ```bash
   # From within VM
   ip addr show
   ip link show
   ```

### Disk Issues

**Symptoms:**
- Cannot create disk
- Disk full errors
- I/O errors

**Solutions:**

1. **Check Disk Space:**
   ```bash
   pvesm status
   df -h
   ```

2. **Verify Disk Configuration:**
   ```bash
   qm config <vmid> | grep -E "scsi|virtio|ide"
   ```

3. **Check for Disk Errors:**
   ```bash
   dmesg | grep -i error
   ```

4. **Resize Disk if Needed:**
   ```bash
   qm resize <vmid> scsi0 +10G
   ```

### Cloud-Init Issues

**Symptoms:**
- Cloud-Init not running
- User data not applied
- SSH keys not working

**Solutions:**

1. **Check Cloud-Init Configuration:**
   ```bash
   qm config <vmid> | grep -E "ciuser|cipassword|sshkey|ipconfig"
   ```

2. **Verify Cloud-Init Drive:**
   ```bash
   qm config <vmid> | grep ide2
   ```

3. **Check Cloud-Init Logs (in VM):**
   ```bash
   # From within VM
   journalctl -u cloud-init
   cat /var/log/cloud-init-output.log
   ```

4. **Reconfigure Cloud-Init:**
   ```bash
   qm set <vmid> --ciuser ubuntu
   qm set <vmid> --sshkey ~/.ssh/id_rsa.pub
   qm set <vmid> --ipconfig0 ip=dhcp
   ```

### Guest Agent Issues

**Symptoms:**
- Cannot get VM status
- Shutdown not working
- No CPU/memory stats

**Solutions:**

1. **Check Guest Agent:**
   ```bash
   qm config <vmid> | grep agent
   ```

2. **Enable Guest Agent:**
   ```bash
   qm set <vmid> --agent 1
   ```

3. **Install Guest Agent in VM:**
   ```bash
   # Ubuntu/Debian
   sudo apt-get install qemu-guest-agent
   sudo systemctl enable qemu-guest-agent
   sudo systemctl start qemu-guest-agent
   ```

### Template Issues

**Symptoms:**
- Cannot clone from template
- Template not found
- Clone fails

**Solutions:**

1. **List Templates:**
   ```bash
   qm list | grep template
   ```

2. **Verify Template:**
   ```bash
   qm config <template-id>
   ```

3. **Clone Template:**
   ```bash
   qm clone <template-id> <new-vmid> --name <new-name>
   ```

4. **Configure Cloned VM:**
   ```bash
   qm set <new-vmid> --ciuser ubuntu
   qm set <new-vmid> --sshkey ~/.ssh/id_rsa.pub
   qm set <new-vmid> --ipconfig0 ip=<new-ip>/24,gw=<gateway>
   ```

## VM Creation Issues

### Cannot Create VM

**Solutions:**

1. **Check Available Resources:**
   ```bash
   pvesh get /nodes/<node>/status
   ```

2. **Verify VM ID Availability:**
   ```bash
   qm list
   ```

3. **Check Storage:**
   ```bash
   pvesm status
   ```

### Import Disk Fails

**Solutions:**

1. **Verify Image File:**
   ```bash
   qemu-img info <image-file>
   ```

2. **Check Image Format:**
   ```bash
   file <image-file>
   ```

3. **Verify Storage:**
   ```bash
   pvesm status
   ```

## VM Management

### Useful Commands

```bash
# List all VMs
qm list

# Get VM status
qm status <vmid>

# Get VM configuration
qm config <vmid>

# Start VM
qm start <vmid>

# Stop VM
qm stop <vmid>

# Shutdown VM (graceful)
qm shutdown <vmid>

# Reset VM
qm reset <vmid>

# View VM console
qm terminal <vmid>

# View VM logs
journalctl -u qemu-server@<vmid> -f
```

## Getting Help

If you cannot resolve a VM issue:

1. Review VM configuration: `qm config <vmid>`
2. Check VM logs: `journalctl -u qemu-server@<vmid>`
3. Review Proxmox logs: `journalctl -u pve-cluster`
4. Check Proxmox documentation
5. Review [Common Issues](common-issues.md)

## Additional Resources

- [Proxmox Operations Runbook](../operations/runbooks/proxmox-operations.md)
- [Common Issues](common-issues.md)
- [Proxmox VE Documentation](https://pve.proxmox.com/pve-docs/)