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:

   qm config <vmid> | grep boot
   qm set <vmid> --boot order=scsi0
   

2. Verify Disk Attachment:

   qm config <vmid> | grep scsi0
   

3. Check BIOS/UEFI Settings:

   qm config <vmid> | grep bios
   # For UEFI: qm set <vmid> --bios ovmf
   # For BIOS: qm set <vmid> --bios seabios
   

4. Review VM Logs:

   journalctl -u qemu-server@<vmid> -f
   

VM Performance Issues

Symptoms:

• Slow response times
• High CPU usage
• Memory issues

Solutions:

1. Check Resource Allocation:

   qm config <vmid> | grep -E "memory|cpu|cores"
   

2. Monitor Resource Usage:

   qm status <vmid>
   

3. Optimize VM Settings:

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

   qm config <vmid> | grep net
   

2. Verify Bridge Configuration:

   ip link show vmbr0
   

3. Test Network from Host:

   ping <vm-ip>
   

4. Check VM Network Interface:

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

   pvesm status
   df -h
   

2. Verify Disk Configuration:

   qm config <vmid> | grep -E "scsi|virtio|ide"
   

3. Check for Disk Errors:

   dmesg | grep -i error
   

4. Resize Disk if Needed:

   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:

   qm config <vmid> | grep -E "ciuser|cipassword|sshkey|ipconfig"
   

2. Verify Cloud-Init Drive:

   qm config <vmid> | grep ide2
   

3. Check Cloud-Init Logs (in VM):

   # From within VM
   journalctl -u cloud-init
   cat /var/log/cloud-init-output.log
   

4. Reconfigure Cloud-Init:

   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:

   qm config <vmid> | grep agent
   

2. Enable Guest Agent:

   qm set <vmid> --agent 1
   

3. Install Guest Agent in VM:

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

   qm list | grep template
   

2. Verify Template:

   qm config <template-id>
   

3. Clone Template:

   qm clone <template-id> <new-vmid> --name <new-name>
   

4. Configure Cloned VM:

   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:

   pvesh get /nodes/<node>/status
   

2. Verify VM ID Availability:

   qm list
   

3. Check Storage:

   pvesm status
   

Import Disk Fails

Solutions:

1. Verify Image File:

   qemu-img info <image-file>
   

2. Check Image Format:

   file <image-file>
   

3. Verify Storage:

   pvesm status
   

VM Management

Useful Commands

# 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

Additional Resources

• Proxmox Operations Runbook
• Common Issues
• Proxmox VE Documentation