Initial commit: loc_az_hci (smom-dbis-138 excluded via .gitignore)

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/troubleshooting/vm-troubleshooting.md

@@ -0,0 +1,310 @@
+# 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/)
+