PSProxmox/Documentation/cmdlets/Get-ProxmoxVM.md

Get-ProxmoxVM

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

Syntax

Get-ProxmoxVM
   [-Connection <ProxmoxConnection>]
   [-Node <String>]
   [-VMID <Int32>]
   [-Name <String>]
   [-UseRegex]
   [-RawJson]
   [-IncludeGuestAgent]
   [<CommonParameters>]

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. Use the -IncludeGuestAgent parameter to fetch guest agent information, which provides detailed network interface information from within the guest operating system. Note that including guest agent data may slow down queries as it requires additional API calls.

Parameters

-Connection

The connection to the Proxmox VE server.

Type: ProxmoxConnection
Parameter Sets: (All)
Aliases:

Required: False
Position: 0
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Node

The node to get VMs from. If not specified, VMs from all nodes will be returned.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-VMID

The ID of the VM to get. If not specified, all VMs will be returned.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Name

The name of the virtual machine to retrieve. Supports wildcards and regex when used with -UseRegex.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-UseRegex

Use regular expressions for filtering.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-RawJson

Whether to return the raw JSON response instead of parsed objects.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-IncludeGuestAgent

Whether to include guest agent information. This may slow down the query as it requires additional API calls.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

None

Outputs

PSProxmox.Models.ProxmoxVM

System.String

Notes

• This cmdlet requires a connection to a Proxmox VE server. Use Connect-ProxmoxServer to establish a connection.
• If no connection is specified, the cmdlet will use the default connection.
• If the -RawJson parameter is specified, the raw JSON response will be returned instead of parsed objects.
• If the -VMID parameter is specified and the VM is not found, an error will be thrown.
• The -Name parameter supports wildcards (e.g., "web*") by default.
• Use the -UseRegex parameter with -Name to filter using regular expressions (e.g., "^web[0-9]+$").

Examples

Example 1: Get all VMs

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vms = Get-ProxmoxVM

This example gets all VMs from all nodes.

Example 2: Get VMs on a specific node

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vms = Get-ProxmoxVM -Node "pve1"

This example gets all VMs on the node "pve1".

Example 3: Get a specific VM by ID

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vm = Get-ProxmoxVM -VMID 100

This example gets the VM with ID 100.

Example 4: Get VMs by name using wildcards

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vms = Get-ProxmoxVM -Name "web*"

This example gets all VMs with names starting with "web".

Example 5: Get VMs by name using regex

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vms = Get-ProxmoxVM -Name "^web[0-9]+$" -UseRegex

This example gets all VMs with names matching the pattern "web" followed by one or more digits.

Example 6: Get the raw JSON response

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$json = Get-ProxmoxVM -RawJson

This example gets the raw JSON response for all VMs.

Example 7: Get VM with guest agent information

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vm = Get-ProxmoxVM -VMID 100 -IncludeGuestAgent

# 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 with guest agent information and displays network interface details.

Example 8: Filter VMs with active guest agents

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)
$vmsWithGuestAgent = Get-ProxmoxVM -IncludeGuestAgent | 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 with guest agent information and filters those with active guest agents.

Example 9: Performance comparison - with and without guest agent

Connect-ProxmoxServer -Server "proxmox.example.com" -Credential (Get-Credential)

# Fast query without guest agent information
Measure-Command { $vms = Get-ProxmoxVM }

# Slower query with guest agent information
Measure-Command { $vmsWithGA = Get-ProxmoxVM -IncludeGuestAgent }

This example demonstrates the performance difference between queries with and without guest agent information.

Related Links

• Connect-ProxmoxServer
• New-ProxmoxVM
• Remove-ProxmoxVM
• Start-ProxmoxVM
• Stop-ProxmoxVM
• Restart-ProxmoxVM