loc_az_hci/docs/operations/guest-agent-setup.md

QEMU Guest Agent Setup Guide

Overview

QEMU Guest Agent provides better integration between Proxmox and VMs, enabling:

• Proper VM shutdown/reboot from Proxmox Web UI
• Automatic IP address detection in Proxmox
• Better VM status reporting (CPU, memory, disk usage)
• File system information and operations
• Time synchronization between host and guest

Prerequisites

• VMs must have Ubuntu installed and be reachable via SSH
• SSH key access configured
• VMs must be running

Quick Setup

Automated Setup (Recommended)

# Set SSH key (if different from default)
export SSH_KEY="~/.ssh/id_rsa"
export SSH_USER="ubuntu"

# Run setup script
./scripts/setup-guest-agent.sh

This script will:

1. Install qemu-guest-agent on each VM
2. Enable and start the service
3. Enable agent in Proxmox VM configuration
4. Verify agent is working

Manual Setup

Step 1: Install Guest Agent on VM

SSH to each VM and run:

sudo apt-get update
sudo apt-get install -y qemu-guest-agent
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent
sudo systemctl status qemu-guest-agent

Step 2: Enable Agent in Proxmox

For each VM in Proxmox Web UI:

1. Stop the VM (if running)
2. Go to: VM → Options tab
3. Find: "QEMU Guest Agent"
4. Click: "Edit"
5. Enable: Check "Use QEMU Guest Agent"
6. Click: "OK"
7. Start the VM

Step 3: Verify Agent is Working

In Proxmox Web UI:

1. Go to: VM → Monitor tab
2. Look for: "QEMU Guest Agent" section
3. Check: Agent status should show as active

Or via command line:

# Check agent status via Proxmox API
curl -k -s -H "Cookie: PVEAuthCookie=<ticket>" \
  "https://192.168.1.206:8006/api2/json/nodes/pve/qemu/100/agent/get-fsinfo"

Troubleshooting

Agent Not Responding

Symptoms:

• Proxmox shows "Guest Agent not running"
• Cannot get VM IP address
• Cannot shutdown VM from Proxmox

Solution:

1. Check agent is installed:

   ssh ubuntu@<VM_IP>
   sudo systemctl status qemu-guest-agent
   

2. Restart agent:

   sudo systemctl restart qemu-guest-agent
   

3. Check logs:

   sudo journalctl -u qemu-guest-agent -f
   

4. Reinstall agent:

   sudo apt-get install --reinstall qemu-guest-agent
   sudo systemctl restart qemu-guest-agent
   

5. Use fix script:

   ./scripts/fix-guest-agent.sh
   

Agent Not Enabled in Proxmox

Symptoms:

• Agent installed on VM but not working
• Proxmox doesn't detect agent

Solution:

1. Stop VM
2. Enable agent in Proxmox:
   • Options → QEMU Guest Agent → Enable
3. Start VM
4. Wait 1-2 minutes for agent to initialize

Agent Takes Time to Initialize

Note: After enabling the agent, it may take 1-2 minutes to fully initialize and start responding to Proxmox queries. This is normal.

Check status:

# On VM
sudo systemctl status qemu-guest-agent

# Should show: Active: active (running)

Verification

Check Agent Status on VM

ssh ubuntu@<VM_IP>
sudo systemctl status qemu-guest-agent

Expected output:

● qemu-guest-agent.service - QEMU Guest Agent
     Loaded: loaded (/lib/systemd/system/qemu-guest-agent.service; enabled)
     Active: active (running) since ...

Check Agent in Proxmox

Web UI:

• VM → Monitor → QEMU Guest Agent
• Should show agent information

API:

# Get filesystem info (requires authentication)
curl -k -s -H "Cookie: PVEAuthCookie=<ticket>" \
  "https://192.168.1.206:8006/api2/json/nodes/pve/qemu/100/agent/get-fsinfo"

Benefits After Setup

Once guest agent is working:

1. VM Shutdown/Reboot:

   • Can properly shutdown/reboot VMs from Proxmox
   • No need to force stop

2. IP Address Detection:

   • Proxmox automatically detects VM IP addresses
   • Shows in VM summary

3. Resource Monitoring:

   • Better CPU, memory, disk usage reporting
   • More accurate VM statistics

4. File Operations:

   • Can execute commands in VM from Proxmox
   • File system information available

Scripts Reference

• scripts/setup-guest-agent.sh - Install and configure guest agent
• scripts/fix-guest-agent.sh - Fix guest agent issues

When to Run

Run guest agent setup after:

• ✅ Ubuntu installation is complete on all VMs
• ✅ VMs are reachable via SSH
• ✅ Install scripts have been applied (optional, can run before)

Summary

1. Install agent: ./scripts/setup-guest-agent.sh
2. Verify: Check Proxmox Web UI → VM → Monitor
3. Fix if needed: ./scripts/fix-guest-agent.sh

Guest agent setup should be done after all VMs are installed and configured, as it requires SSH access to the VMs.