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)

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

```bash
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:

```bash
# 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:**
   ```bash
   ssh ubuntu@<VM_IP>
   sudo systemctl status qemu-guest-agent
   ```

2. **Restart agent:**
   ```bash
   sudo systemctl restart qemu-guest-agent
   ```

3. **Check logs:**
   ```bash
   sudo journalctl -u qemu-guest-agent -f
   ```

4. **Reinstall agent:**
   ```bash
   sudo apt-get install --reinstall qemu-guest-agent
   sudo systemctl restart qemu-guest-agent
   ```

5. **Use fix script:**
   ```bash
   ./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:**
```bash
# On VM
sudo systemctl status qemu-guest-agent

# Should show: Active: active (running)
```

## Verification

### Check Agent Status on VM

```bash
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:**
```bash
# 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.