{"id":49730077,"url":"https://github.com/Grace-Solutions/PSProxmox","last_synced_at":"2026-05-25T19:00:51.883Z","repository":{"id":290425465,"uuid":"974372831","full_name":"Grace-Solutions/PSProxmox","owner":"Grace-Solutions","description":"PSProxmox is a PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for managing virtual machines, storage, networks, users, roles, and more.","archived":false,"fork":false,"pushed_at":"2025-07-03T12:05:17.000Z","size":505,"stargazers_count":39,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-03T12:37:58.508Z","etag":null,"topics":["module","powershell","proxmox"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Grace-Solutions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T17:15:23.000Z","updated_at":"2025-07-03T12:05:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"4b325685-c0b5-42b6-8f2f-57ca8793e50a","html_url":"https://github.com/Grace-Solutions/PSProxmox","commit_stats":null,"previous_names":["freedbygrace/psproxmox","grace-solutions/psproxmox"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/Grace-Solutions/PSProxmox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Grace-Solutions%2FPSProxmox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Grace-Solutions%2FPSProxmox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Grace-Solutions%2FPSProxmox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Grace-Solutions%2FPSProxmox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Grace-Solutions","download_url":"https://codeload.github.com/Grace-Solutions/PSProxmox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Grace-Solutions%2FPSProxmox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33488942,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["module","powershell","proxmox"],"created_at":"2026-05-09T06:00:22.646Z","updated_at":"2026-05-25T19:00:51.866Z","avatar_url":"https://github.com/Grace-Solutions.png","language":"C#","funding_links":[],"categories":["C# #"],"sub_categories":[],"readme":"# PSProxmox\n\nPSProxmox is a C#-based PowerShell module for managing Proxmox VE clusters. It provides a comprehensive set of cmdlets for interacting with Proxmox VE API, featuring structured return objects, mass deployment tools, automatic IP management, and more.\n\n## Features\n\n- **Session Management**: Authenticate and persist sessions with Proxmox VE clusters\n- **Core CRUD Operations**: Manage VMs, LXC Containers, Storage, Network, Users, Roles, SDN, and Clusters\n- **VM Guest Agent Support**: Comprehensive guest agent data retrieval with network interface information\n- **Templates**: Create and use VM deployment templates\n- **Cloud Images**: Download, customize, and create templates from cloud images\n- **Cloud-Init Support**: Configure VMs with Cloud-Init for easy customization\n- **LXC Containers**: Create and manage Linux Containers with full CRUD operations\n- **TurnKey Templates**: Download and use TurnKey Linux templates for LXC containers\n- **Mass Creation**: Bulk create VMs with prefix/counter\n- **IP Management**: CIDR parsing, subnetting, FIFO IP queue assignment\n- **Structured Objects**: All outputs are typed C# classes (PowerShell-native)\n- **Pipeline Support**: Cmdlets support pipeline input where appropriate\n- **Clean Codebase**: 100% compilation success with zero errors and warnings\n\n## Project Structure\n\n- **Module/**: Contains the PowerShell module files\n- **PSProxmox/**: Contains the C# source code for the module\n- **Documentation/**: Contains detailed documentation and examples\n- **Scripts/**: Contains build and installation scripts\n- **Release/**: Contains built releases (created by build script)\n\n## Installation\n\n### From PowerShell Gallery (Recommended)\n\n```powershell\n# Install from PowerShell Gallery\nInstall-Module -Name PSProxmox -Scope CurrentUser\n```\n\n### Manual Installation\n\n```powershell\n# Clone the repository\ngit clone https://github.com/Grace-Solutions/PSProxmox.git\ncd PSProxmox\n\n# Build the module\n.\\Scripts\\build.ps1\n\n# Install the module\n.\\Scripts\\Install-PSProxmox.ps1\n```\n\n## Getting Started\n\n### Connecting to a Proxmox VE Server\n\n```powershell\n# Connect using username and password\n$securePassword = ConvertTo-SecureString \"password\" -AsPlainText -Force\nConnect-ProxmoxServer -Server \"proxmox.example.com\" -Username \"root\" -Password $securePassword -Realm \"pam\"\n\n# Connect using a credential object\n$credential = Get-Credential\nConnect-ProxmoxServer -Server \"proxmox.example.com\" -Credential $credential -Realm \"pam\"\n\n# Test the connection\nTest-ProxmoxConnection -Detailed\n```\n\n### Managing Virtual Machines\n\n```powershell\n# Get all VMs (uses the default connection automatically)\n$vms = Get-ProxmoxVM\n\n# Get a specific VM\n$vm = Get-ProxmoxVM -VMID 100\n\n# Create a new VM\n$vm = New-ProxmoxVM -Node \"pve1\" -Name \"test-vm\" -Memory 2048 -Cores 2 -DiskSize 32 -Start\n\n# Create a new VM using the builder pattern\n$builder = New-ProxmoxVMBuilder -Name \"web-server\"\n$builder.WithMemory(4096)\n        .WithCores(2)\n        .WithDisk(50, \"local-lvm\")\n        .WithNetwork(\"virtio\", \"vmbr0\")\n        .WithIPConfig(\"192.168.1.10/24\", \"192.168.1.1\")\n        .WithStart($true)\n\n$vm = New-ProxmoxVM -Node \"pve1\" -Builder $builder\n\n# Start, stop, and restart VMs\nStart-ProxmoxVM -Node \"pve1\" -VMID 100\nStop-ProxmoxVM -Node \"pve1\" -VMID 100\nRestart-ProxmoxVM -Node \"pve1\" -VMID 100\n\n# Remove a VM\nRemove-ProxmoxVM -Node \"pve1\" -VMID 100 -Confirm:$false\n```\n\n### Working with VM Guest Agent\n\n```powershell\n# Get VM with guest agent information (use -IncludeGuestAgent for detailed network info)\n$vm = Get-ProxmoxVM -VMID 100 -IncludeGuestAgent\n\n# Check if guest agent is available and running\nif ($vm.GuestAgent -and $vm.GuestAgent.Status -eq \"running\") {\n    Write-Host \"Guest Agent is running\"\n\n    # Display network interfaces from guest agent\n    foreach ($interface in $vm.GuestAgent.NetIf) {\n        Write-Host \"Interface: $($interface.Name)\"\n        Write-Host \"  IPv4 Addresses: $($interface.IPv4Addresses -join ', ')\"\n        Write-Host \"  IPv6 Addresses: $($interface.IPv6Addresses -join ', ')\"\n        Write-Host \"  MAC Address: $($interface.MacAddress)\"\n    }\n} else {\n    Write-Host \"Guest Agent not available or not running\"\n}\n\n# Get all VMs with active guest agents\n$vmsWithGuestAgent = Get-ProxmoxVM -IncludeGuestAgent | Where-Object {\n    $_.GuestAgent -and $_.GuestAgent.Status -eq \"running\"\n}\n\n# Performance comparison: fast vs detailed queries\nMeasure-Command { $fastVMs = Get-ProxmoxVM }  # Fast query\nMeasure-Command { $detailedVMs = Get-ProxmoxVM -IncludeGuestAgent }  # Detailed query\n\n# Find VMs by IP address using guest agent data\n$searchIP = \"192.168.1.100\"\n$foundVMs = $vmsWithGuestAgent | Where-Object {\n    $vm = $_\n    $found = $false\n\n    if ($vm.GuestAgent.NetIf) {\n        foreach ($interface in $vm.GuestAgent.NetIf) {\n            if ($interface.IPv4Addresses -contains $searchIP -or\n                $interface.IPv6Addresses -contains $searchIP) {\n                $found = $true\n                break\n            }\n        }\n    }\n\n    return $found\n}\n```\n\n### Managing Templates\n\n```powershell\n# Create a template from an existing VM\n$template = New-ProxmoxVMTemplate -VMID 100 -Name \"Ubuntu-Template\" -Description \"Ubuntu 20.04 Template\"\n\n# Get all templates\n$templates = Get-ProxmoxVMTemplate\n\n# Create a VM from a template\n$vm = New-ProxmoxVMFromTemplate -Node \"pve1\" -TemplateName \"Ubuntu-Template\" -Name \"web01\" -Start\n\n# Create multiple VMs from a template\n$vms = New-ProxmoxVMFromTemplate -Node \"pve1\" -TemplateName \"Ubuntu-Template\" -Prefix \"web\" -Count 3 -Start\n```\n\n### Working with Cloud Images\n\n```powershell\n# List available cloud images\nGet-ProxmoxCloudImage -Distribution \"ubuntu\" -Release \"22.04\"\n\n# Download a cloud image\n$imagePath = Save-ProxmoxCloudImage -Distribution \"ubuntu\" -Release \"22.04\" -Variant \"server\"\n\n# Customize the cloud image (resize to 20GB)\n$customizedImagePath = Invoke-ProxmoxCloudImageCustomization -ImagePath $imagePath -Resize 20 -ConvertTo \"qcow2\"\n\n# Create a template from the cloud image\n$template = New-ProxmoxCloudImageTemplate -Node \"pve1\" -Name \"ubuntu-22.04\" -ImagePath $customizedImagePath -Storage \"local-lvm\" -Memory 2048 -Cores 2 -DiskSize 20\n\n# Alternatively, download and create a template in one step\n$template = New-ProxmoxCloudImageTemplate -Node \"pve1\" -Name \"ubuntu-22.04\" -Distribution \"ubuntu\" -Release \"22.04\" -Storage \"local-lvm\" -Memory 2048 -Cores 2 -DiskSize 20\n\n# Configure Cloud-Init for a VM\n$password = ConvertTo-SecureString \"SecurePassword123!\" -AsPlainText -Force\n$sshKey = Get-Content -Path \"~/.ssh/id_rsa.pub\"\nSet-ProxmoxVMCloudInit -Node \"pve1\" -VMID 100 -Username \"admin\" -Password $password -SSHKey $sshKey -IPConfig \"dhcp\" -DNS \"8.8.8.8,8.8.4.4\"\n\n# Create a VM from the template with static IP\n$vm = New-ProxmoxVMFromTemplate -Node \"pve1\" -TemplateName \"ubuntu-22.04\" -Name \"web01\"\nSet-ProxmoxVMCloudInit -Node \"pve1\" -VMID $vm.VMID -Username \"admin\" -Password $password -IPConfig \"ip=192.168.1.100/24,gw=192.168.1.1\"\nStart-ProxmoxVM -Node \"pve1\" -VMID $vm.VMID\n```\n\n### Managing Storage\n\n```powershell\n# Get all storage\n$storage = Get-ProxmoxStorage\n\n# Get storage on a specific node\n$storage = Get-ProxmoxStorage -Node \"pve1\"\n\n# Create a new storage\n$storage = New-ProxmoxStorage -Name \"backup\" -Type \"dir\" -Path \"/mnt/backup\" -Content \"backup,iso\"\n\n# Remove a storage\nRemove-ProxmoxStorage -Name \"backup\" -Confirm:$false\n```\n\n### Managing Networks\n\n```powershell\n# Get all network interfaces on a node\n$networks = Get-ProxmoxNetwork -Node \"pve1\"\n\n# Create a new bridge interface\n$network = New-ProxmoxNetwork -Node \"pve1\" -Interface \"vmbr1\" -Type \"bridge\" -BridgePorts \"eth1\" -Method \"static\" -Address \"192.168.2.1\" -Netmask \"255.255.255.0\" -Autostart\n\n# Remove a network interface\nRemove-ProxmoxNetwork -Node \"pve1\" -Interface \"vmbr1\" -Confirm:$false\n```\n\n### Managing Users and Roles\n\n```powershell\n# Get all users\n$users = Get-ProxmoxUser\n\n# Create a new user\n$securePassword = ConvertTo-SecureString \"password\" -AsPlainText -Force\n$user = New-ProxmoxUser -Username \"john\" -Realm \"pam\" -Password $securePassword -FirstName \"John\" -LastName \"Doe\" -Email \"john.doe@example.com\"\n\n# Remove a user\nRemove-ProxmoxUser -UserID \"john@pam\" -Confirm:$false\n\n# Get all roles\n$roles = Get-ProxmoxRole\n\n# Create a new role\n$role = New-ProxmoxRole -RoleID \"Developer\" -Privileges \"VM.Allocate\", \"VM.Config.Disk\", \"VM.Config.CPU\", \"VM.PowerMgmt\"\n\n# Remove a role\nRemove-ProxmoxRole -RoleID \"Developer\" -Confirm:$false\n```\n\n### Managing SDN\n\n```powershell\n# Get all SDN zones\n$zones = Get-ProxmoxSDNZone\n\n# Create a new SDN zone\n$zone = New-ProxmoxSDNZone -Zone \"zone1\" -Type \"vlan\" -Bridge \"vmbr0\"\n\n# Remove an SDN zone\nRemove-ProxmoxSDNZone -Zone \"zone1\" -Confirm:$false\n\n# Get all SDN VNets\n$vnets = Get-ProxmoxSDNVnet\n\n# Create a new SDN VNet\n$vnet = New-ProxmoxSDNVnet -VNet \"vnet1\" -Zone \"zone1\" -IPv4 \"192.168.1.0/24\" -Gateway \"192.168.1.1\"\n\n# Remove an SDN VNet\nRemove-ProxmoxSDNVnet -VNet \"vnet1\" -Confirm:$false\n```\n\n### Managing Clusters\n\n```powershell\n# Get cluster information\n$cluster = Get-ProxmoxCluster\n\n# Join a node to a cluster\n$securePassword = ConvertTo-SecureString \"password\" -AsPlainText -Force\nJoin-ProxmoxCluster -ClusterName \"cluster1\" -HostName \"pve1\" -Password $securePassword\n\n# Leave a cluster\nLeave-ProxmoxCluster -Force\n\n# Create a cluster backup\n$backup = New-ProxmoxClusterBackup -Compress -Wait\n\n# Restore a cluster backup\nRestore-ProxmoxClusterBackup -BackupID \"vzdump-cluster-2023_04_28-12_00_00.vma.lzo\" -Force -Wait\n```\n\n### Managing IP Addresses\n\n```powershell\n# Create a new IP pool\n$pool = New-ProxmoxIPPool -Name \"Production\" -CIDR \"192.168.1.0/24\" -ExcludeIPs \"192.168.1.1\", \"192.168.1.254\"\n\n# Get all IP pools\n$pools = Get-ProxmoxIPPool\n\n# Get a specific IP pool\n$pool = Get-ProxmoxIPPool -Name \"Production\"\n\n# Clear an IP pool\nClear-ProxmoxIPPool -Name \"Production\"\n```\n\n### Managing LXC Containers\n\n```powershell\n# Get all LXC containers\n$containers = Get-ProxmoxContainer\n\n# Get a specific container\n$container = Get-ProxmoxContainer -CTID 100\n\n# Get containers by name pattern (supports wildcards and regex)\n$webContainers = Get-ProxmoxContainer -Name \"web*\"\n$dbContainers = Get-ProxmoxContainer -Name \"^db\\d+$\"\n\n# Create a new container\n$container = New-ProxmoxContainer -Node \"pve1\" -Name \"web-container\" -OSTemplate \"local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz\" -Storage \"local-lvm\" -Memory 512 -Cores 1 -DiskSize 8 -Unprivileged -Start\n\n# Create a container using a builder\n$builder = New-ProxmoxContainerBuilder -Name \"db-container\"\n$builder.WithOSTemplate(\"local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz\")\n        .WithStorage(\"local-lvm\")\n        .WithMemory(1024)\n        .WithCores(2)\n        .WithDiskSize(16)\n        .WithUnprivileged($true)\n        .WithStart($true)\n\n$container = New-ProxmoxContainer -Node \"pve1\" -Builder $builder\n\n# Start, stop, and restart containers\nStart-ProxmoxContainer -Node \"pve1\" -CTID 100 -Wait\nStop-ProxmoxContainer -Node \"pve1\" -CTID 100 -Wait\nRestart-ProxmoxContainer -Node \"pve1\" -CTID 100 -Wait\n\n# Remove a container\nRemove-ProxmoxContainer -Node \"pve1\" -CTID 100 -Confirm:$false\n```\n\n### Working with TurnKey Linux Templates\n\n```powershell\n# List available TurnKey templates\n$templates = Get-ProxmoxTurnKeyTemplate\n\n# Get TurnKey templates by name pattern\n$wordpressTemplates = Get-ProxmoxTurnKeyTemplate -Name \"wordpress*\"\n\n# Download a TurnKey template\n$templatePath = Save-ProxmoxTurnKeyTemplate -Node \"pve1\" -Name \"wordpress\" -Storage \"local\"\n\n# Create a container from a TurnKey template\n$container = New-ProxmoxContainerFromTurnKey -Node \"pve1\" -Name \"wordpress\" -Template \"wordpress\" -Storage \"local-lvm\" -Memory 512 -Cores 1 -DiskSize 8 -Start\n```\n\n## Disconnecting\n\n```powershell\n# Get the current connection and disconnect from the server\n$connection = Test-ProxmoxConnection -Detailed\nDisconnect-ProxmoxServer -Connection $connection\n```\n\n## Development\n\n### Building the Module\n\nTo build the module from source:\n\n```powershell\n# Run the build script\n.\\Scripts\\build.ps1\n```\n\nThis will:\n1. Compile the C# code\n2. Create a versioned release in the Release folder\n3. Update the Module folder with the latest build\n4. Create a ZIP package for distribution\n\n### Project Organization\n\n- **C# Source Code**: All C# source code is in the PSProxmox folder\n- **PowerShell Module**: The PowerShell module files are in the Module folder\n- **Documentation**: Comprehensive documentation is in the Documentation folder\n- **Scripts**: Build and installation scripts are in the Scripts folder\n\n## Documentation\n\nFor detailed documentation, see the [Documentation](Documentation) directory. The documentation includes:\n\n- [Cmdlet Reference](Documentation/cmdlets/README.md)\n- [Examples](Documentation/examples/README.md)\n- [Guides](Documentation/guides/README.md)\n  - [Installation Guide](Documentation/guides/Installation.md)\n  - [Cloud Image Templates Guide](Documentation/guides/CloudImageTemplates.md)\n  - [LXC Containers Guide](Documentation/guides/LXCContainers.md)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGrace-Solutions%2FPSProxmox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGrace-Solutions%2FPSProxmox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGrace-Solutions%2FPSProxmox/lists"}