Installation Proxmox VE - OpenCCU/OpenCCU GitHub Wiki

Setzt man als Virtualisierungsumgebung Proxmox Virtual Environment (VE) ein, kann man mit den folgenden Schritten eine Grundinstallation einer virtuellen OpenCCU vornehmen. Diese kann entweder als vollwertige QEMU/KVM-basierte virtuelle Maschine (VM) oder als leichtgewichtiger LXC-Container (CT) umgesetzt werden. Die Installation kann dabei entweder teilautomatisiert über ein Installationsskript oder komplett manuell erfolgen.

Unterstützt wird eine Proxmox VE Standardinstallation auf x86_64-Hardware (z. B. Intel NUC) als Host. Darüber hinaus kann das Installationsskript auch auf ARM-basierten Proxmox-VE-Systemen (z. B. einem Raspberry Pi 5 mit einem ARM-Port von Proxmox VE) verwendet werden. In diesem Fall wird für eine VM automatisch das UEFI-basierte Image Generic aarch64 anstelle der *.ova verwendet.

• Ein lauffähiges Proxmox-VE-System mit Internetverbindung (für die skriptbasierte Installation).
• Für die virtuelle Maschine bzw. den Container: 2 CPU-Kerne, 2 GB Arbeitsspeicher und eine virtuelle Festplatte mit mindestens 6 GB (empfohlen: 8 GB).
• Ein unterstütztes Funkmodul, das per USB (z. B. HmIP-RFUSB, HB-RF-USB-2), per Netzwerk (HB-RF-ETH) oder – bei einem Container auf ARM-Hardware mit GPIO-Schnittstelle – direkt per GPIO (RPI-RF-MOD) angebunden wird.

Um OpenCCU als virtuelle Maschine (VM) oder als Container (CT/LXC) innerhalb eines Proxmox-VE-Systems zu betreiben, kann man innerhalb einer bereits lauffähigen Proxmox-VE-Umgebung wie folgt vorgehen. Dabei ist zu beachten, dass der Proxmox-VE-Host über eine funktionierende Internetverbindung verfügen muss, da das Installationsskript sowie die Image-Datei automatisch heruntergeladen werden:

1. Proxmox-Shell starten: Nach dem Einloggen in der Proxmox-Weboberfläche kann man per Rechtsklick auf sein Proxmox-System (hier: pve) die „Shell“ aufrufen, um in die Kommandozeile von Proxmox zu gelangen:

2. Installationskommando ausführen: Um die Installation zu starten, das folgende Kommando innerhalb der Proxmox-Shell eingeben und mit Enter bestätigen:

   wget -qO - https://openccu.de/install-proxmox.sh | bash -

   bzw. wenn man als Nicht-root-Benutzer mit sudo-Rechten per SSH verbunden ist:

   sudo sh -c "wget -qO - https://openccu.de/install-proxmox.sh | bash -"

   

3. Virtualisierungstyp wählen: Nach kurzer Ladezeit wird man zuerst aufgefordert, die Art der Virtualisierung auszuwählen (Auswahl mit der Leertaste):

   Generell ist die Virtualisierung als Full Virtual Machine (VM) zu bevorzugen, da hierfür keine zusätzlichen Pakete im Proxmox-VE-System selbst installiert werden müssen, damit die für OpenCCU notwendigen Funkmodule (z. B. HmIP-RFUSB) genutzt werden können. Möchte man OpenCCU hingegen als leichtgewichtigen Container (Lightweight LXC Container) betreiben, um z. B. direkter auf lokale Schnittstellen (GPIO, UART, etc.) des Hostsystems zuzugreifen, wird die Anleitung unter Installation als CT / LXC fortgeführt.

Hat man als Virtualisierungstyp Full Virtual Machine gewählt, sind die folgenden weiteren Schritte des Installationsskripts nacheinander durchzugehen:

1. Version auswählen: Nach kurzer Ladezeit wird man aufgefordert, eine Version für die Installation auszuwählen:

   ⚠️ Hinweis: Bei der Auswahl der zu installierenden OpenCCU-Version wird zwischen release- und snapshot-Versionen unterschieden. Bei Letzteren handelt es sich um experimentelle Entwicklungsstände, die entsprechend instabil sein können. Für eine produktive OpenCCU-Umgebung sollten daher bevorzugt release-Versionen verwendet werden.

2. Storage auswählen: Im nächsten Schritt wird man aufgefordert, den Storage auszuwählen, der für die VM verwendet werden soll (Auswahl mit der Leertaste):

   ⚠️ Hinweis: Diese Aufforderung erscheint nur, wenn mehr als ein VM-Storage in Proxmox VE konfiguriert ist.

3. Festplattengröße wählen: Nun wird man zur Eingabe der gewünschten Größe der virtuellen Festplatte gebeten, auf der u. a. alle nutzerbezogenen Konfigurationsdateien und Zusatzpakete gespeichert werden:

   Das Minimum liegt bei 6 GB, vorgeschlagen werden 8 GB. Bei umfangreichen CCU-Add-ons (z. B. CCU-Historian) kann ein größerer Wert sinnvoll sein. Da es sich um virtuellen Speicherplatz handelt, wird auf dem Hostsystem – je nach Storage-Typ – nur der tatsächlich belegte Platz verbraucht.

4. Funkmodul auswählen: Anschließend wird ein ggf. bereits per USB mit dem Proxmox-Host verbundenes Homematic/Homematic IP-Funkmodul ausgewählt (Auswahl mit der Leertaste), das der VM dann automatisch zugewiesen wird. Ist (noch) kein Funkmodul angeschlossen, kann dieser Schritt übersprungen und das Funkmodul später manuell zugewiesen werden:

5. VM-ID auswählen: Als letzter Schritt vor der eigentlichen Installation wird nach der zu vergebenden ID innerhalb des Proxmox-VE-Systems gefragt. Standardmäßig ist die nächste freie ID voreingetragen:

6. Installation: Nach der Bestätigung lädt das Installationsskript die ausgewählte Version herunter, installiert sie im ausgewählten Storage und verbindet das USB-Funkmodul mit der VM:

Damit ist die Grundinstallation der OpenCCU-VM abgeschlossen und sie erscheint in der Proxmox-Weboberfläche. Da alle Grundeinstellungen bereits vorgenommen wurden, kann die VM unmittelbar gestartet werden; der Startvorgang ist unter „Console“ einsehbar. Mit der Tastenkombination ALT+F2 lassen sich dort detailliertere Ausgaben des Startvorgangs anzeigen. Anschließend helfen die ersten Schritte nach der Installation bei der weiteren Einrichtung.

Updates einer OpenCCU-VM erfolgen wie gewohnt über die Updatefunktion der WebUI (bzw. manuell mit dem *-ova.zip- bzw. *-generic-aarch64.zip-Archiv).

Hat man in Schritt 3 als Virtualisierungstyp Lightweight LXC Container gewählt, sind die folgenden Schritte des Installationsskripts nacheinander durchzugehen:

1. Warnhinweis bestätigen: Da bei einer Installation als Container auf dem Proxmox-VE-System selbst Zusatzpakete installiert und Anpassungen vorgenommen werden müssen, ist zuerst ein entsprechender Warnhinweis zu bestätigen: ⚠️ Hinweis: Die Installation dieser Zusatzpakete und Anpassungen kann jederzeit wieder rückgängig gemacht werden, indem das Skript install-proxmox.sh wie im Abschnitt Deinstallation CT / LXC beschrieben mit der Option uninstall aufgerufen wird.

2. Funkmodul-Overlays installieren: Kommt als Proxmox-VE-Host ein ARM-basiertes System mit GPIO-Schnittstelle (z. B. Raspberry Pi) zum Einsatz, auf dem ein RPI-RF-MOD oder HM-MOD-RPI-PCB direkt betrieben werden soll, wird als Nächstes abgefragt, ob die dafür notwendigen „Device Tree Overlays“ installiert werden sollen: ⚠️ Hinweis: Dieser Schritt ist nur notwendig, wenn eines der beiden GPIO-basierten Funkmodule (RPI-RF-MOD, HM-MOD-RPI-PCB) direkt auf der GPIO-Schnittstelle des ARM-Systems betrieben werden soll. Bei einer USB- (HmIP-RFUSB, HB-RF-USB-2, etc.) oder netzwerkbasierten Anbindung (HB-RF-ETH) ist hier „No“ auszuwählen.

3. Version auswählen: Anschließend wird nach kurzer Ladezeit die OpenCCU-Version für die Installation des Containers ausgewählt:

   ⚠️ Hinweis: Bei der Auswahl der zu installierenden OpenCCU-Version wird zwischen release- und snapshot-Versionen unterschieden. Bei Letzteren handelt es sich um experimentelle Entwicklungsstände, die entsprechend instabil sein können. Für eine produktive OpenCCU-Umgebung sollten daher bevorzugt release-Versionen verwendet werden.

4. Storage auswählen: Im nächsten Schritt wird man aufgefordert, den Storage auszuwählen, der für den Container verwendet werden soll (Auswahl mit der Leertaste):

   ⚠️ Hinweis: Diese Aufforderung erscheint nur, wenn mehr als ein CT-Storage in Proxmox VE konfiguriert ist.

5. Festplattengröße wählen: Nun wird man zur Eingabe der gewünschten Größe des virtuellen Speichers gebeten, auf dem im laufenden Betrieb alle nutzerbezogenen Konfigurationsdateien und Zusatzpakete gespeichert werden:

   Das Minimum liegt bei 6 GB, vorgeschlagen werden 8 GB. Bei umfangreichen CCU-Add-ons (z. B. CCU-Historian) kann ein größerer Wert sinnvoll sein. Da es sich um virtuellen Speicherplatz handelt, wird auf dem Hostsystem – je nach Storage-Typ – nur der tatsächlich belegte Platz verbraucht.

6. VM-ID auswählen: Als letzter Schritt vor der eigentlichen Installation wird nach der zu vergebenden ID innerhalb des Proxmox-VE-Systems gefragt. Standardmäßig ist die nächste freie ID voreingetragen:

7. Installation: Nach der Bestätigung lädt das Installationsskript die ausgewählte Version herunter, installiert sie im ausgewählten Storage und richtet den Container ein:

Damit ist die Grundinstallation des OpenCCU-Containers abgeschlossen und er erscheint in der Proxmox-Weboberfläche. Da alle Grundeinstellungen bereits vorgenommen wurden, kann der Container unmittelbar gestartet werden; der Startvorgang ist unter „Console“ einsehbar. Funkmodule bzw. Adapter wie HmIP-RFUSB oder HB-RF-USB-2 werden erkannt, sobald sie am Proxmox-VE-Host angesteckt sind. Bei Einsatz eines RPI-RF-MOD oder HM-MOD-RPI-PCB direkt auf der GPIO-Schnittstelle ist ggf. zuerst ein Neustart des Proxmox-VE-Systems erforderlich. Anschließend helfen die ersten Schritte nach der Installation bei der weiteren Einrichtung.

Wird OpenCCU bereits als Container innerhalb von Proxmox VE betrieben, lässt sich mit den folgenden Schritten ein Update auf eine neue bzw. andere Version durchführen:

1. CT herunterfahren: Zuerst den OpenCCU-Container ordnungsgemäß herunterfahren – entweder über die Proxmox-Weboberfläche oder mit dem Kommando pct shutdown <VMID>.

2. Backup durchführen: Damit bei einem Problem sofort zur alten Version zurückgekehrt werden kann, über die Proxmox-Weboberfläche unter Backup → Backup now ein aktuelles Backup erstellen.

3. Updateskript aufrufen: In einer Proxmox-Shell das Skript install-proxmox.sh mit dem Parameter update aufrufen:

   wget -qO - https://openccu.de/install-proxmox.sh | bash -s update

   bzw. wenn man als Nicht-root-Benutzer mit sudo-Rechten per SSH verbunden ist:

   sudo sh -c "wget -qO - https://openccu.de/install-proxmox.sh | bash -s update"

   

4. Container auswählen: Nach kurzer Ladezeit werden alle OpenCCU-Container aufgelistet, aus denen der zu aktualisierende Container ausgewählt wird:

5. Zielversion auswählen: Anschließend wird eine Liste der verfügbaren Versionen angezeigt, aus der die gewünschte Zielversion ausgewählt wird:

   ⚠️ Hinweis: Bei der Auswahl der zu installierenden OpenCCU-Version wird zwischen release- und snapshot-Versionen unterschieden. Bei Letzteren handelt es sich um experimentelle Entwicklungsstände, die entsprechend instabil sein können. Für eine produktive OpenCCU-Umgebung sollten daher bevorzugt release-Versionen verwendet werden.

6. Update bestätigen: Vor der eigentlichen Durchführung muss bestätigt werden, dass das Update durchgeführt werden soll und zuvor ein Backup erstellt wurde:

7. Update durchführen: Nach der Bestätigung wird das Update durchgeführt; über Verlauf und Erfolg informiert die Ausgabe in der Proxmox-Shell:

Ist das Updateskript ohne Fehler durchgelaufen, kann der Container entweder über die Proxmox-Weboberfläche oder mit pct start <VMID> wieder gestartet werden. Mit pct console <VMID> lässt sich das Hochfahren direkt verfolgen, um eventuelle Fehler zu erkennen.

Bei der Installation eines OpenCCU-Containers werden auf dem Proxmox-VE-System Zusatzpakete installiert und Anpassungen vorgenommen, damit der Container auf die angeschlossene Homematic-Funkhardware (RPI-RF-MOD, etc.) zugreifen kann. Möchte man später von einer Container-basierten Installation wieder Abstand nehmen, lassen sich diese Änderungen wie folgt rückgängig machen:

1. Deinstallation aufrufen: In einer Proxmox-Shell folgenden Befehl ausführen:

   wget -qO - https://openccu.de/install-proxmox.sh | bash -s uninstall

   bzw. wenn man als Nicht-root-Benutzer mit sudo-Rechten per SSH verbunden ist:

   sudo sh -c "wget -qO - https://openccu.de/install-proxmox.sh | bash -s uninstall"

2. Deinstallation bestätigen: Das Skript bittet zunächst um Bestätigung der Deinstallation:
3. Deinstallation durchführen: Nach der Bestätigung werden alle für den Betrieb eines OpenCCU-Containers notwendigen Zusatzpakete und Anpassungen auf dem Proxmox-VE-System zurückgenommen: ⚠️ Hinweis: Sollten bei der Deinstallation Fehlermeldungen auftreten, kann das Skript problemlos mehrfach hintereinander aufgerufen werden, da es vor jedem Schritt prüft, ob die jeweilige Komponente noch vorhanden ist.

Nach Abschluss der Deinstallation sollte ein Neustart des Proxmox-VE-Hosts eingeplant werden, damit keine der entfernten Komponenten mehr aktiv ist. Zuvor können nicht mehr benötigte Abhängigkeiten mit apt autoremove entfernt werden. Der Container selbst wird über die Proxmox-Weboberfläche bzw. mit pct destroy <VMID> entfernt.

Möchte man die Installation der OpenCCU-VM unter einer x86-basierten Proxmox-VE-Umgebung manuell vornehmen oder funktioniert die automatische Installation z. B. aufgrund von Firewall-Restriktionen im lokalen Netzwerk nicht, kann man auch wie folgt vorgehen:

1. Download: Für Proxmox VE wird zur Installation die *.ova-Datei genutzt, die unter Releases heruntergeladen werden kann. Die *-ova.zip-Datei wird nur für spätere WebUI-basierte Updates der virtuellen Maschine benötigt.

   [!TIP] Ab Proxmox VE 8.2 kann eine *.ova-Datei alternativ auch direkt über die Proxmox-Weboberfläche importiert werden: Dazu die Datei auf einen Storage mit dem Inhaltstyp „Import“ hochladen und dort über „Importieren“ eine neue VM anlegen. Anschließend mit Schritt 6 fortfahren.

2. *.ova-Datei auf den Proxmox-Host kopieren: Die *.ova-Datei z. B. per SCP auf den Proxmox-Host kopieren, damit sie von dort aus importiert werden kann:

3. Proxmox-Shell starten: Nach dem Einloggen in der Proxmox-Weboberfläche per Rechtsklick auf „pve“ die „Shell“ aufrufen:

4. *.ova entpacken: Da Proxmox *.ova-Dateien auf der Kommandozeile nicht direkt verarbeiten kann, wird die Datei zunächst entpackt. Dabei entstehen die Dateien OpenCCU.ovf, OpenCCU.vmdk und OpenCCU.mf:

   tar xvf OpenCCU-X.XX.XX.YYYYMMDD.ova

   

5. *.ovf-Datei importieren: Mit dem Befehl qm importovf wird aus der *.ovf- und der zugehörigen *.vmdk-Datei automatisch eine virtuelle Maschine angelegt. Dabei <VMID> durch eine freie ID (siehe Maschinenliste) und <STORAGE> durch den gewünschten Storage (z. B. local-lvm) ersetzen:

   qm importovf <VMID> OpenCCU.ovf <STORAGE>

   

6. Festplatte vergrößern: Die neue OpenCCU-VM erscheint nun in der Proxmox-Weboberfläche. Unter „Hardware“ das angelegte Laufwerk auswählen, über „Resize Disk“ die virtuelle Festplatte vergrößern und die gewünschte Größe eingeben (empfohlen: insgesamt 8 GB):

7. USB-Gerät hinzufügen: Um das USB-Funkmodul hinzuzufügen, unter „Hardware“ auf „Hinzufügen“ klicken und das gewünschte, am Proxmox-Host angeschlossene USB-Gerät hinzufügen:

8. Netzwerkkarte hinzufügen: Nun noch eine Netzwerkkarte mit dem Modell „VirtIO“ hinzufügen:

9. Einstellungen kontrollieren: Anschließend die VM-Einstellungen unter „Hardware“ kontrollieren. Der SCSI-Controller sollte auf VirtIO SCSI single stehen und für die virtuelle Festplatte die Optionen iothread=1 sowie (bei einer SSD) discard=on aktiviert sein: Unter „Optionen“ sicherstellen, dass als „OS Type“ Linux 6.x - 2.6 Kernel ausgewählt ist und „Use tablet for pointer“ auf No steht:

10. Guest Agent aktivieren: Damit der in OpenCCU integrierte QEMU Guest Agent erkannt wird, unter „Optionen“ den „QEMU Guest Agent“ aktivieren:

11. Erster Start: Nun kann die virtuelle OpenCCU zum ersten Mal gestartet werden. In der virtuellen Konsole ist der Startvorgang zu sehen. Anschließend meldet sich OpenCCU mit der per DHCP bezogenen IP-Adresse und die WebUI ist unter http://openccu/ bzw. dieser IP-Adresse erreichbar. Anschließend helfen die ersten Schritte nach der Installation bei der weiteren Einrichtung.

Eine OpenCCU-VM bzw. ein OpenCCU-Container wird über die Proxmox-Weboberfläche („More → Remove“) bzw. mit qm destroy <VMID> (VM) oder pct destroy <VMID> (Container) entfernt. Wurde ein Container verwendet, können die dafür auf dem Proxmox-Host vorgenommenen Anpassungen wie unter Deinstallation CT / LXC beschrieben zurückgenommen werden.