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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-08 09:04:46 -08:00
commit c39465c2bd
386 changed files with 50649 additions and 0 deletions
--- a/docs/operations/guest-agent-setup.md
+++ b/docs/operations/guest-agent-setup.md
@@ -0,0 +1,211 @@
+# 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.
+