> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/de/modul-8-entwicklung-and-devops/03-powershell-module.md). # PowerShell-Modul (PSVergeOS) **PSVergeOS** ist ein plattformübergreifendes PowerShell-Modul, das **über 200 Cmdlets** für die Verwaltung der VergeOS-Infrastruktur über die REST-API bereitstellt. Wenn Ihr Team PowerShell bereits für die Verwaltung von Windows Server, Active Directory oder VMware verwendet, können Sie mit PSVergeOS dieselben Workflows und Skriptmuster auf VergeOS ausweiten — mit voller Pipeline-Unterstützung, Tab-Vervollständigung und der vertrauten `Verb-Nomen` Cmdlet-Namenskonvention. ## Voraussetzungen & Installation | Anforderung | Version | | -------------- | --------------------- | | **PowerShell** | 7.4 oder höher | | **VergeOS** | 26.0 oder höher | | **Plattform** | Windows, macOS, Linux | ### Über die PowerShell Gallery (empfohlen) ```powershell Install-Module -Name PSVergeOS -Scope CurrentUser ``` ### Manuelle Installation (Entwicklung) ```powershell git clone https://github.com/verge-io/PSVergeOS.git Import-Module ./PSVergeOS/PSVergeOS.psd1 ``` ### Installation überprüfen ```powershell Get-Module PSVergeOS -ListAvailable Get-Command -Module PSVergeOS | Measure-Object # Sollte 200+ Cmdlets anzeigen ``` ## Authentifizierung PSVergeOS unterstützt mehrere Authentifizierungsmethoden, um unterschiedlichen Umgebungen gerecht zu werden — von interaktiven Administratorsitzungen bis hin zu vollständig automatisierten Pipelines. ### Interaktive Anmeldedaten Benutzername und Passwort zum Verbindungszeitpunkt abfragen: ```powershell Connect-VergeOS -Server "vergeos.example.com" # Fordert interaktiv Anmeldedaten an ``` ### PSCredential-Objekt Anmeldedaten sicher für nicht interaktive Skripte speichern: ```powershell $cred = Get-Credential Connect-VergeOS -Server "vergeos.example.com" -Credential $cred ``` ### API-Token Ein vorab generiertes API-Token für Automatisierungspipelines verwenden: ```powershell Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN ``` ### Selbstsignierte Zertifikate Für Labor- und Entwicklungsumgebungen mit selbstsignierten Zertifikaten: ```powershell Connect-VergeOS -Server "192.168.1.100" -Token $token -SkipCertificateCheck ``` {% hint style="warning" %} Verwenden Sie `-SkipCertificateCheck` nur in Testumgebungen. Für Produktionssysteme konfigurieren Sie gültige SSL-Zertifikate. {% endhint %} ## Verwaltung mehrerer Server PSVergeOS kann **mehrere VergeOS-Systeme** aus einer einzigen PowerShell-Sitzung verwalten. Verwenden Sie den `-PassThru` Parameter, um Verbindungsobjekte zu erfassen, und den `-Server` Parameter, um bestimmte Systeme anzusprechen: ```powershell # Mit mehreren Systemen verbinden $prod = Connect-VergeOS -Server "prod.vergeos.local" -Token $env:PROD_TOKEN -PassThru $dev = Connect-VergeOS -Server "dev.vergeos.local" -Token $env:DEV_TOKEN -PassThru # VMs auf einem bestimmten Server abfragen Get-VergeVM -Server $prod Get-VergeVM -Server $dev # Die Standardverbindung wechseln Set-VergeConnection -Server "prod.vergeos.local" ``` Dies ist besonders wertvoll für **MSPs** die mehrere Kundenumgebungen oder Organisationen mit getrennten Produktions- und Entwicklungs-VergeOS-Clustern verwalten. ## Cmdlet-Kategorien Das Modul organisiert seine über 200 Cmdlets in funktionale Kategorien. Jede Kategorie deckt den vollständigen CRUD-Lebenszyklus plus ressourcenspezifische Aktionen ab. | Kategorie | Beschreibung | | -------------------------- | ----------------------------------------------------------------------- | | **Verbindung** | Verbindungen herstellen, trennen und Serververbindungen verwalten | | **Virtuelle Maschinen** | Lebenszyklus, Leistungssteuerung, Snapshots, Laufwerke, NICs, Klonen | | **Netzwerk** | Virtuelle Netzwerke, Firewall-Regeln, DNS, DHCP, Diagnose | | **VPN** | IPSec-Verbindungen/-Richtlinien, WireGuard-Schnittstellen/-Peers | | **NAS & Speicher** | NAS-Dienste, Volumes, CIFS-/NFS-Freigaben, Snapshots, Synchronisierung | | **Mandanten** | Bereitstellung, Snapshots, Speicher-/Netzwerkblockzuweisung | | **Benutzer & Gruppen** | Kontoverwaltung, Berechtigungen, API-Schlüssel | | **System** | Cluster, Knoten, Lizenzen, Einstellungen | | **Zertifikate** | SSL-Zertifikatsverwaltung | | **Tags** | Ressourcen-Tagging und Kategorisierung | | **Webhooks** | Ereignisgesteuerte Automatisierungshooks | | **Überwachung & Aufgaben** | Alarme, Protokolle, asynchrone Aufgabenverfolgung | | **Backup & DR** | Snapshot-Profile, Cloud-Snapshots, Standortverwaltung, Synchronisierung | | **Dateien & Medien** | ISO-Verwaltung, Datei-Uploads | | **Ressourcengruppen** | Logische Ressourcengruppierung | ### VPN-Cmdlets (IPSec & WireGuard) Die VPN-Kategorie verdient besondere Aufmerksamkeit — PSVergeOS bietet vollständige Verwaltung sowohl für IPSec- als auch für WireGuard-VPN-Implementierungen: **IPSec:** * `New-VergeIPSecConnection` / `Get-VergeIPSecConnection` / `Remove-VergeIPSecConnection` * `New-VergeIPSecPolicy` / `Get-VergeIPSecPolicy` / `Remove-VergeIPSecPolicy` **WireGuard:** * `New-VergeWireGuardInterface` / `Get-VergeWireGuardInterface` / `Remove-VergeWireGuardInterface` * `New-VergeWireGuardPeer` / `Get-VergeWireGuardPeer` / `Remove-VergeWireGuardPeer` ## Pipeline-Unterstützung Eine der größten Stärken von PSVergeOS ist **die vollständige PowerShell-Pipeline-Unterstützung**. Cmdlets akzeptieren Pipeline-Eingaben und erzeugen Pipeline-Ausgaben, wodurch prägnante Einzeiler für Massenoperationen möglich werden: ```powershell # Alle Entwicklungs-VMs stoppen Get-VergeVM -Name "Dev-*" | Stop-VergeVM -Confirm:$false # Von allen Produktions-VMs einen Snapshot erstellen Get-VergeVM -Name "Prod-*" | ForEach-Object { New-VergeVMSnapshot -VMName $_.Name -Name "Daily-$(Get-Date -Format 'yyyyMMdd')" } # Alle VMs in einem bestimmten Netzwerk einschalten Get-VergeVM | Where-Object { $_.Network -eq "app-network" } | Start-VergeVM ``` Durch Pipeline-Unterstützung ist PSVergeOS besonders effektiv für **geplante Wartungsaufgaben** in Verbindung mit dem Windows-Taskplaner oder Linux-Cron-Jobs. ## Praktische Beispiele ### Massen-Snapshot mit Aufbewahrung ```powershell # Mit dem VergeOS-System verbinden Connect-VergeOS -Server "vergeos.example.com" -Token $env:VERGEOS_TOKEN # Von allen laufenden Produktions-VMs einen Snapshot mit 24-Stunden-Aufbewahrung erstellen $vms = Get-VergeVM -Name "Prod-*" | Where-Object { $_.PowerState -eq "Running" } foreach ($vm in $vms) { $snapshot = New-VergeVMSnapshot -VMName $vm.Name ` -Name "Nightly-$(Get-Date -Format 'yyyyMMdd-HHmm')" ` -Retention 86400 Write-Host "Snapshot erstellt für $($vm.Name): $($snapshot.Name)" } Write-Host "Abgeschlossen: $($vms.Count) Snapshots" ``` ### CSV-Export des VM-Inventars ```powershell # Vollständiges VM-Inventar für Berichte nach CSV exportieren Get-VergeVM | Select-Object Name, PowerState, RAM, CPUCores, OS, @{N='DiskGB'; E={[math]::Round($_.DiskSize / 1GB, 2)}}, Created, Description | Export-Csv -Path "vm-inventory-$(Get-Date -Format 'yyyyMMdd').csv" -NoTypeInformation Write-Host "Inventar exportiert nach vm-inventory-$(Get-Date -Format 'yyyyMMdd').csv" ``` ### Netzwerkerstellung mit Firewall-Regeln ```powershell # Ein internes Netzwerk mit DHCP und Firewall-Regeln erstellen $network = New-VergeNetwork -Name "web-tier" ` -NetworkAddress "10.20.1.0/24" ` -IPAddress "10.20.1.1" ` -DHCPEnabled $true # Firewall-Regeln hinzufügen New-VergeNetworkRule -Network $network.Name ` -Name "Allow HTTPS" -Action Accept -Protocol TCP -DestPort 443 New-VergeNetworkRule -Network $network.Name ` -Name "Allow SSH" -Action Accept -Protocol TCP -DestPort 22 # Die Regeln anwenden und einschalten Invoke-VergeNetworkApplyRules -Network $network.Name Start-VergeNetwork -Name $network.Name Write-Host "Netzwerk '$($network.Name)' ist online und die Firewall-Regeln wurden angewendet" ``` ### Ressourcenbericht für mehrere Mandanten ```powershell # Eine Ressourcenübersicht über alle Mandanten hinweg erstellen $report = @() foreach ($tenant in Get-VergeTenant) { $tenantVMs = Get-VergeVM -Tenant $tenant.Name $report += [PSCustomObject]@{ Tenant = $tenant.Name VMCount = $tenantVMs.Count TotalRAM = ($tenantVMs | Measure-Object -Property RAM -Sum).Sum TotalCPU = ($tenantVMs | Measure-Object -Property CPUCores -Sum).Sum Running = ($tenantVMs | Where-Object PowerState -eq "Running").Count Stopped = ($tenantVMs | Where-Object PowerState -ne "Running").Count } } $report | Format-Table -AutoSize $report | Export-Csv "tenant-report.csv" -NoTypeInformation ``` ### WireGuard-VPN-Einrichtung ```powershell # Eine WireGuard-Schnittstelle im externen Netzwerk erstellen $wgInterface = New-VergeWireGuardInterface -Network "External" ` -Name "Remote-Access" ` -IPAddress "10.100.0.1/24" ` -ListenPort 51820 # Einen Peer für einen entfernten Benutzer hinzufügen New-VergeWireGuardPeer -Interface $wgInterface.Name ` -Name "Engineer-1" ` -AllowedIPs "10.100.0.2/32" ` -AutoGenerateConfig $true # Netzwerkregeln anwenden Invoke-VergeNetworkApplyRules -Network "External" ``` ## Integration mit dem Taskplaner PSVergeOS-Skripte lassen sich für eine vollständig automatisierte Ausführung ganz natürlich in geplante Aufgabensysteme integrieren: **Windows-Taskplaner:** ```powershell # Speichern als C:\Scripts\nightly-snapshot.ps1 Import-Module PSVergeOS Connect-VergeOS -Server "vergeos.local" -Token $env:VERGEOS_TOKEN -SkipCertificateCheck Get-VergeVM -Name "Prod-*" | ForEach-Object { New-VergeVMSnapshot -VMName $_.Name -Name "Nightly-$(Get-Date -Format 'yyyyMMdd')" -Retention 86400 } Disconnect-VergeOS ``` **Linux cron (PowerShell 7.4+):** ```bash # Täglich um 2:00 Uhr ausführen 0 2 * * * /usr/bin/pwsh -File /opt/scripts/nightly-snapshot.ps1 ``` ## Häufige Anwendungsfälle ### Bulk-VM-Operationen Mehrere VMs per Pipeline-Einzeiler stoppen, starten, snapshotten oder migrieren. Ideal für Wartungsfenster. ### Infrastrukturberichte VM-Inventar, Ressourcennutzung und Konfigurationsdaten für Audits und Kapazitätsplanung nach CSV exportieren. ### Netzwerkautomatisierung Netzwerke erstellen, DHCP konfigurieren, Firewall-Regeln verwalten und VPN-Tunnel programmgesteuert einrichten. ### Geplante Wartung Mit Taskplaner oder cron für automatisierte Snapshots, Bereinigung und Compliance-Prüfungen integrieren. {% hint style="info" %} **Kommen Sie von VMware oder Nutanix?** PSVergeOS verwendet die standardmäßige PowerShell `Verb-Nomen` Konvention, sodass sich die Muskelgedächtnis- `Get-VM | Stop-VM` wird zu `Get-VergeVM | Stop-VergeVM`. Die Authentifizierung unterstützt interaktive Eingabeaufforderungen, `PSCredential` Objekte und API-Tokens, sodass hier dieselben Skriptmuster gelten, die Sie bereits für nicht interaktive Automatisierung verwenden. Um mehr als ein VergeOS-System aus einer einzigen Sitzung zu verwalten, übergeben Sie `-Server` bei jedem Cmdlet, um eine bestimmte Verbindung anzusprechen. {% endhint %} ## Zusätzliche Ressourcen * [GitHub-Repository](https://github.com/verge-io/PSVergeOS) — Quellcode, Issues und 16 Beispielskripte * [PowerShell Gallery](https://www.powershellgallery.com/packages/PSVergeOS) — Neueste Version und Installationsinformationen * [PowerShell 7.4-Dokumentation](https://learn.microsoft.com/en-us/powershell/) — Referenz zur PowerShell-Laufzeit --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/learn-the-platform/de/modul-8-entwicklung-and-devops/03-powershell-module.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.