feat: Add VM Guest Agent support and fix all compilation errors

- Added comprehensive VM Guest Agent support with network interface information - Enhanced Get-ProxmoxVM cmdlet to retrieve guest agent data automatically - Added ProxmoxVMGuestAgent model with IPv4/IPv6 address arrays - Fixed all 41 pre-existing compilation errors (100% success rate) - Eliminated all compilation warnings for clean builds - Standardized API patterns across all cmdlets - Enhanced error handling and type safety throughout codebase - Updated documentation with guest agent examples - Added comprehensive guest agent example script - Updated README with guest agent usage examples - Version bump to 2025.05.30.1740
2026-08-31 01:09:24 +00:00 · 2025-05-30 17:46:20 -04:00
parent 5f0e31725d
commit 33898b7b80
30 changed files with 1184 additions and 268 deletions
@@ -1,6 +1,6 @@
 # Get-ProxmoxVM

-Gets virtual machines from Proxmox VE.
+Gets virtual machines from Proxmox VE with comprehensive information including guest agent data.

 ## Syntax

@@ -17,7 +17,7 @@ Get-ProxmoxVM

 ## Description

-The `Get-ProxmoxVM` cmdlet retrieves virtual machines from Proxmox VE. You can retrieve all VMs, VMs on a specific node, or a specific VM by ID.
+The `Get-ProxmoxVM` cmdlet retrieves virtual machines from Proxmox VE with comprehensive information including guest agent data when available. You can retrieve all VMs, VMs on a specific node, or a specific VM by ID. The cmdlet automatically attempts to gather guest agent information for each VM, providing detailed network interface information from within the guest operating system.

 ## Parameters

@@ -196,6 +196,45 @@ $json = Get-ProxmoxVM -RawJson

 This example gets the raw JSON response for all VMs.

+### Example 7: Get VM with guest agent information
+
+```powershell
+Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
+$vm = Get-ProxmoxVM -VMID 100
+
+# Check if guest agent is available and running
+if ($vm.GuestAgent -and $vm.GuestAgent.Status -eq "running") {
+    Write-Host "Guest Agent is running"
+
+    # Display network interfaces from guest agent
+    foreach ($interface in $vm.GuestAgent.NetIf) {
+        Write-Host "Interface: $($interface.Name)"
+        Write-Host "  IPv4 Addresses: $($interface.IPv4Addresses -join ', ')"
+        Write-Host "  IPv6 Addresses: $($interface.IPv6Addresses -join ', ')"
+        Write-Host "  MAC Address: $($interface.MacAddress)"
+    }
+} else {
+    Write-Host "Guest Agent not available or not running"
+}
+```
+
+This example gets a VM and displays guest agent network information if available.
+
+### Example 8: Filter VMs with active guest agents
+
+```powershell
+Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
+$vmsWithGuestAgent = Get-ProxmoxVM | Where-Object {
+    $_.GuestAgent -and $_.GuestAgent.Status -eq "running"
+}
+
+foreach ($vm in $vmsWithGuestAgent) {
+    Write-Host "$($vm.Name): $($vm.GuestAgent.NetIf.Count) network interfaces"
+}
+```
+
+This example gets all VMs and filters those with active guest agents.
+
 ## Related Links

 - [Connect-ProxmoxServer](Connect-ProxmoxServer.md)
@@ -67,3 +67,8 @@ This directory contains example scripts for the PSProxmox module.
 - [Create a new IP pool](IP-CreatePool.ps1)
 - [Get information about IP pools](IP-GetPools.ps1)
 - [Clear an IP pool](IP-ClearPool.ps1)
+
+## VM Guest Agent Examples
+
+- [Working with VM Guest Agent data](VM-GuestAgent-Examples.ps1) - Comprehensive examples of guest agent functionality
+- [SMBIOS configuration examples](SMBIOS-Examples.ps1) - Examples of working with VM SMBIOS settings
@@ -0,0 +1,188 @@
+# VM-GuestAgent-Examples.ps1
+# This script demonstrates how to use the VM Guest Agent functionality in PSProxmox
+
+# Import the PSProxmox module
+Import-Module PSProxmox
+
+# Connect to the Proxmox VE server
+$credential = Get-Credential -Message "Enter your Proxmox VE credentials"
+Connect-ProxmoxServer -Server "proxmox.example.com" -Credential $credential -Realm "pam"
+
+Write-Host "=== PSProxmox VM Guest Agent Examples ===" -ForegroundColor Green
+
+# Example 1: Get a specific VM with guest agent information
+Write-Host "`n1. Getting VM with Guest Agent Information" -ForegroundColor Yellow
+$vmid = 100  # Change this to your VM ID
+$vm = Get-ProxmoxVM -VMID $vmid
+
+if ($vm) {
+    Write-Host "VM: $($vm.Name) (ID: $($vm.VMID))" -ForegroundColor Cyan
+    
+    if ($vm.GuestAgent) {
+        Write-Host "Guest Agent Status: $($vm.GuestAgent.Status)" -ForegroundColor Green
+        
+        if ($vm.GuestAgent.Status -eq "running" -and $vm.GuestAgent.NetIf) {
+            Write-Host "Network Interfaces from Guest Agent:" -ForegroundColor Green
+            
+            foreach ($interface in $vm.GuestAgent.NetIf) {
+                Write-Host "  Interface: $($interface.Name)" -ForegroundColor White
+                Write-Host "    MAC Address: $($interface.MacAddress)" -ForegroundColor Gray
+                
+                if ($interface.IPv4Addresses -and $interface.IPv4Addresses.Count -gt 0) {
+                    Write-Host "    IPv4 Addresses: $($interface.IPv4Addresses -join ', ')" -ForegroundColor Gray
+                }
+                
+                if ($interface.IPv6Addresses -and $interface.IPv6Addresses.Count -gt 0) {
+                    Write-Host "    IPv6 Addresses: $($interface.IPv6Addresses -join ', ')" -ForegroundColor Gray
+                }
+                Write-Host ""
+            }
+        } else {
+            Write-Host "Guest Agent is not running or no network interfaces available" -ForegroundColor Yellow
+        }
+    } else {
+        Write-Host "Guest Agent information not available" -ForegroundColor Red
+    }
+} else {
+    Write-Host "VM with ID $vmid not found" -ForegroundColor Red
+}
+
+# Example 2: Get all VMs and show guest agent status
+Write-Host "`n2. Guest Agent Status for All VMs" -ForegroundColor Yellow
+$allVMs = Get-ProxmoxVM
+
+Write-Host "VM Guest Agent Status Summary:" -ForegroundColor Cyan
+$guestAgentStats = @{
+    Running = 0
+    NotRunning = 0
+    NotAvailable = 0
+}
+
+foreach ($vm in $allVMs) {
+    $status = "Not Available"
+    $color = "Red"
+    
+    if ($vm.GuestAgent) {
+        if ($vm.GuestAgent.Status -eq "running") {
+            $status = "Running"
+            $color = "Green"
+            $guestAgentStats.Running++
+        } else {
+            $status = "Not Running"
+            $color = "Yellow"
+            $guestAgentStats.NotRunning++
+        }
+    } else {
+        $guestAgentStats.NotAvailable++
+    }
+    
+    Write-Host "  $($vm.Name) (ID: $($vm.VMID)): $status" -ForegroundColor $color
+}
+
+Write-Host "`nSummary:" -ForegroundColor Cyan
+Write-Host "  Running: $($guestAgentStats.Running)" -ForegroundColor Green
+Write-Host "  Not Running: $($guestAgentStats.NotRunning)" -ForegroundColor Yellow
+Write-Host "  Not Available: $($guestAgentStats.NotAvailable)" -ForegroundColor Red
+
+# Example 3: Filter VMs with active guest agents
+Write-Host "`n3. VMs with Active Guest Agents" -ForegroundColor Yellow
+$vmsWithActiveGA = $allVMs | Where-Object { 
+    $_.GuestAgent -and $_.GuestAgent.Status -eq "running" 
+}
+
+if ($vmsWithActiveGA.Count -gt 0) {
+    Write-Host "VMs with active Guest Agents:" -ForegroundColor Green
+    
+    foreach ($vm in $vmsWithActiveGA) {
+        Write-Host "  $($vm.Name) (ID: $($vm.VMID))" -ForegroundColor White
+        
+        if ($vm.GuestAgent.NetIf) {
+            $totalIPs = ($vm.GuestAgent.NetIf | ForEach-Object { 
+                $_.IPv4Addresses.Count + $_.IPv6Addresses.Count 
+            } | Measure-Object -Sum).Sum
+            
+            Write-Host "    Network Interfaces: $($vm.GuestAgent.NetIf.Count)" -ForegroundColor Gray
+            Write-Host "    Total IP Addresses: $totalIPs" -ForegroundColor Gray
+        }
+    }
+} else {
+    Write-Host "No VMs found with active Guest Agents" -ForegroundColor Yellow
+}
+
+# Example 4: Export guest agent network information to CSV
+Write-Host "`n4. Exporting Guest Agent Network Information" -ForegroundColor Yellow
+$networkData = @()
+
+foreach ($vm in $vmsWithActiveGA) {
+    if ($vm.GuestAgent.NetIf) {
+        foreach ($interface in $vm.GuestAgent.NetIf) {
+            foreach ($ipv4 in $interface.IPv4Addresses) {
+                $networkData += [PSCustomObject]@{
+                    VMName = $vm.Name
+                    VMID = $vm.VMID
+                    InterfaceName = $interface.Name
+                    MACAddress = $interface.MacAddress
+                    IPAddress = $ipv4
+                    IPVersion = "IPv4"
+                }
+            }
+            
+            foreach ($ipv6 in $interface.IPv6Addresses) {
+                $networkData += [PSCustomObject]@{
+                    VMName = $vm.Name
+                    VMID = $vm.VMID
+                    InterfaceName = $interface.Name
+                    MACAddress = $interface.MacAddress
+                    IPAddress = $ipv6
+                    IPVersion = "IPv6"
+                }
+            }
+        }
+    }
+}
+
+if ($networkData.Count -gt 0) {
+    $csvPath = "VM-GuestAgent-NetworkInfo.csv"
+    $networkData | Export-Csv -Path $csvPath -NoTypeInformation
+    Write-Host "Network information exported to: $csvPath" -ForegroundColor Green
+    Write-Host "Total network entries: $($networkData.Count)" -ForegroundColor Cyan
+} else {
+    Write-Host "No network information available to export" -ForegroundColor Yellow
+}
+
+# Example 5: Find VMs by IP address using guest agent data
+Write-Host "`n5. Find VM by IP Address" -ForegroundColor Yellow
+$searchIP = "192.168.1.100"  # Change this to the IP you're looking for
+Write-Host "Searching for VMs with IP address: $searchIP" -ForegroundColor Cyan
+
+$foundVMs = $vmsWithActiveGA | Where-Object {
+    $vm = $_
+    $found = $false
+    
+    if ($vm.GuestAgent.NetIf) {
+        foreach ($interface in $vm.GuestAgent.NetIf) {
+            if ($interface.IPv4Addresses -contains $searchIP -or 
+                $interface.IPv6Addresses -contains $searchIP) {
+                $found = $true
+                break
+            }
+        }
+    }
+    
+    return $found
+}
+
+if ($foundVMs.Count -gt 0) {
+    Write-Host "Found VMs with IP $searchIP" -ForegroundColor Green
+    foreach ($vm in $foundVMs) {
+        Write-Host "  $($vm.Name) (ID: $($vm.VMID))" -ForegroundColor White
+    }
+} else {
+    Write-Host "No VMs found with IP address $searchIP" -ForegroundColor Yellow
+}
+
+Write-Host "`n=== Examples Complete ===" -ForegroundColor Green
+
+# Disconnect from the server when done
+$connection = Test-ProxmoxConnection -Detailed
+Disconnect-ProxmoxServer -Connection $connection