3CX-Leitfaden zur automatisierten Proxmox-Bereitstellung

Überblick

Diese Anleitung beschreibt die automatisierte Bereitstellung einer virtuellen 3CX PBX-Maschine auf Proxmox VE. Mithilfe generischer Debian-Cloud-Images und Cloud-Init stellt dieses Skript die Rechenressourcen bereit, übernimmt die Netzwerkkonfiguration über DHCP, fügt die erforderlichen Installationsskripte ein und kann optional ein 3CX-Backup im Hintergrund wiederherstellen.

Voraussetzungen

Bevor Sie das Bereitstellungsskript ausführen, stellen Sie sicher, dass die folgenden Voraussetzungen erfüllt sind:

  • Gehe zu Datacenter -> Storage.
  • Wählen Sie „local“ und klicken Sie auf „Edit“.
  • Stellen Sie im Content-Dropdown sicher, dass die Optionen „Snippets“ und „Disk Image“ ausgewählt sind.

Proxmox-Speicherkonfiguration

  • Root Access: Sie müssen im Proxmox-Knoten angemeldet sein als root.
  • SSH Keys: Auf dem Proxmox-Host muss ein SSH-Schlüsselpaar vorhanden sein. (z.B., /root/.ssh/id_rsa).
  • Internet Access: Der Proxmox-Knoten muss in der Lage sein, cloud.debian.org zu erreichen, um das Basis-Image herunterzuladen.
  • DHCP Reservation: Das Zielnetzwerk muss über einen DHCP-Server mit einer reservierten IP-Adresse verfügen, die der in Ihrer Konfiguration definierten MAC-Adresse zugeordnet ist.

Reservierte Adresse hinzufügen

Hinweis: Das obige Beispiel zeigt eine DHCP-Reservierung in einer WatchGuard-Umgebung. Die genaue Schnittstelle und die Schritte zur Konfiguration einer statischen MAC-zu-IP-Zuordnung variieren je nach verwendeter Netzwerkausrüstung (z. B. pfSense, UniFi, FortiGate oder Windows Server). Die Grundvoraussetzung bleibt jedoch gleich: Diese statische, eindeutige MAC-Adresse wird dauerhaft an diese reservierte IP-Adresse in Ihrem Netzwerk gebunden und in Ihrer .env-Datei verwendet, wie im Abschnitt „Bereitstellung Ihres 3CX-Telefonsystems“ beschrieben.

Laden Sie die 3CX Proxmox Bereitstellungstools herunter.

  • Melden Sie sich per SSH (oder über die Web-Management-Oberfläche) als Root-Benutzer am Proxmox-Host an.
  • Navigieren Sie zum Home-Verzeichnis und laden Sie die 3CX-Bereitstellungstools herunter:

cd ~

wget https://downloads-global.3cx.com/downloads/misc/3cx-proxmox.tar.gz

tar -zxvf 3cx-proxmox.tar.gz

Bereitstellung Ihres 3CX-Telefonsystems

Bereiten Sie Ihren Bereitstellungsordner vor

  • Erstellen Sie einen eigenen Ordner für Ihre neue PBX (in diesem Beispiel ~/3cx-proxmox/deployments/pbx01) und kopieren Sie die Umgebungsvorlage hinein:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Hinweis: Wenn Sie eine unbeaufsichtigte Wiederherstellung durchführen, müssen Sie auch Ihre setupconfig.xml- und 3cx-backup.zip-Dateien in diesen Ordner kopieren.

Konfigurieren Sie Ihre .ENV-Datei

nano ~/3cx-proxmox/deployments/pbx01/3cx-proxmox.env

Beachten Sie Folgendes:

  • PBX_INSTALLATION_MODE auf "manuell" (Standardeinstellung) setzen:
  • Option 1: Erstellen Sie eine gültige Datei ~/3cx-proxmox/deployments/pbx01/setupconfig.xml.
  • Option 2: Alternativ können Sie eine setupconfig.xml-Datei mit einer gültigen Minimalkonfiguration aus dem 3CX-Portal herunterladen.
  • Wenn Sie eine Wiederherstellung durchführen, setzen Sie BACKUP_FILE auf den Dateinamen Ihrer Sicherung (im Verzeichnis ~/3cx-proxmox/deployments/pbx01).
  • Setzen Sie PBX_INSTALLATION_MODE auf "wizard", um die Web-UI-Konfiguration zu starten.
  • Legen Sie die VMID auf eine verfügbare, eindeutige Proxmox-VM-ID fest.
  • Sie können die aktuell verwendeten VM-IDs über die Proxmox-Shell mit dem Befehl `qm list` überprüfen.
  • Legen Sie für Ihre 3CX-Instanz die passenden Werte fest (einige Hinweise finden Sie hier: Hardwareanforderungen):
  • DISK_GB (default 40)
  • CORES (default 2)
  • SOCKETS (default 1)
  • MEMORY_MB (default 2048)
  • Setzen Sie Ihre MAC-Adresse auf den Wert, den Sie im vorherigen Schritt der Voraussetzungen festgelegt haben.
  • (Optional) VLAN_TAG festlegen (standardmäßig leer)
  • Gewünschte 3CX-Versionsvariablen festlegen; für die neueste Version 20 Update 8:
  • PBX_VERSION="20.0.8.1121"
  • PBX_REPO="bookworm"
  • PBX_REPO_VERSION="2008"
  • CLOUD_IMAGE_URL=https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
  • CLOUD_IMAGE_FILE=debian-12.qcow2
  • (Optional) Legen Sie die Pfade zu SSH_PUBLIC_KEY_FILE und SSH_PRIVATE_KEY_FILE fest, falls Sie benutzerdefinierte Schlüssel zur Sicherung der Kommunikation zwischen Ihrem Proxmox-Host und den Gästen erstellt haben.

Weitere Informationen zur Bereitstellung von 3CX und zu den Provisionierungseinstellungen finden Sie in der Datei setupconfig.xml.

Projektverzeichnisstruktur

So sollte Ihre Verzeichnisstruktur aussehen:

Verzeichnisstruktur

Führen Sie das Bereitstellungsskript aus.

Führen Sie das Hauptskript aus und übergeben Sie den Pfad zur spezifischen Umgebungsdatei mithilfe des Flags --config (oder -c):

cd ~/3cx-proxmox

./create-3cx-vm.sh --config ./deployments/pbx01/3cx-proxmox.env

root@QA-pve:~# cd ~/3cx-proxmox

root@QA-pve:~/3cx-proxmox# ./create-3cx-vm.sh --config ./deployments/pbx01/3cx-proxmox.env

[INFO] Deployment configuration folder: /root/3cx-proxmox/deployments/pbx01

[INFO] Creating unique Cloud-Init profile at /var/lib/vz/snippets/3cx-profile-300.yaml...

[INFO] Injecting XML setupconfig.xml...

[INFO] Injecting script ./scripts/3cx-setup.sh...

[INFO] Injecting PBX version to install 20.0.8.1121.

[INFO] Injecting PBX repository distribution...

[INFO] Injecting PBX repository version channel...

[INFO] Injecting PBX installation mode...

[INFO] Creating VM 300

[INFO] Importing Disk...

importing disk '/var/lib/vz/template/qcow2/debian-12.qcow2' to VM 300 ...

Formatting '/var/lib/vz/images/300/vm-300-disk-0.raw', fmt=raw size=3221225472 preallocation=off

transferred 0.0 B of 3.0 GiB (0.00%)

transferred 30.7 MiB of 3.0 GiB (1.00%)

Überwachen Sie die Bereitstellung

Das Skript liefert Live-Feedback im Terminal. Es wird systematisch:

  • Laden Sie das Debian-Cloud-Image herunter (falls nicht im Cache vorhanden).
  • Fügen Sie Ihre Skripte und Variablen dynamisch in einen eindeutigen Cloud-Init-Codeausschnitt ein.
  • Stellen Sie die Rechenressourcen und die Netzwerkschnittstelle der VM bereit.
  • Starten Sie die VM und warten Sie, bis der QEMU-Gastagent die zugewiesene DHCP-IP-Adresse meldet.

[INFO] Applying Cloud-Init settings...

update VM 300: -cicustom vendor=local:snippets/3cx-profile-300.yaml -ciuser root -ipconfig0 ip=dhcp -scsi1 local:cloudinit -serial0 socket -sshkeys ssh-rsa%20AAAAB3NzaC1yc2EAAAADAQABAAACAQCifHLUh%2FJ%2F2gK%2Fz1uYuipXtgLxgaf6Egj%2B%2BhTPKWb%2Ba5Uc%2FOfIaA1Km8YuZrXE3652DA7mhjMmAslyYSno2uARwRnGzpwVPLnFEwshylPiiHdaS%2FFgSAV6XpQyzLepbB01ek4QqrPhB35NDGxlrIeKYRycfFdgy%2Fcwj54EQtHTIMwDBpczjRQxf%2BMISqgL5rJRziWfuuXAh06ocP1J8m4yAb8EGygVgXZIcuyToXQXweFq6zEl%2FnhqEACtVdcNJedcjpXiJENk%2Fd%2BTqoYQFcA42vHk5DI2vJ7uY3qkgTkDzz4PjkKXPu2VwHFH9DIdBkVMxx1HVBxGuDIkFSnc5IUlqEW7oKnUQAycZyt%2BOLbZNpKQNhMZ9itgRPEx96w%2BJy%2BllYoFF2H5LavE7wmBiN6aT8YS209xLV9jGhikU0JM0EfEUiQfTDM836xpdJgUZWbxXHxpmMR2XfDdPgo6jbA7JGzzR3BjGYDie3SbjNVk%2B9PugBSu1wSVgq3sfR9I%2FWLHw%2FRJlsuE19yMcSsuhahIP9rrcxc38bSFJbHW4yj1adhoKSzGi1XBB0QzVbL34grztYZ1BTtWP76FWtr1zc1Gy28AwqfRLasUgWWbosaiPJ%2Fkkn0ErlmDLI0ra%2Bibu%2BRItyzBiH4UcEkay5GOVLkpg%2FWyvHjcihZfN6SC50tdhw%3D%3D%20root%40QA-pve%0A -vga serial0

Formatting '/var/lib/vz/images/300/vm-300-cloudinit.qcow2', fmt=qcow2 cluster_size=65536 extended_l2=off preallocation=metadata compression_type=zlib size=4194304 lazy_refcounts=off refcount_bits=16

scsi1: successfully created disk 'local:300/vm-300-cloudinit.qcow2,media=cdrom'

generating cloud-init ISO

[INFO] Virtual machine has been deployed successfully.

[INFO] Generating deployment notes file...

[INFO] Starting VM...

generating cloud-init ISO

[INFO] Waiting for QEMU Guest Agent to report IP address (this takes 1-2 minutes)...

[INFO] VM is online with IP: 10.28.5.177

[INFO] Waiting for SSH to be ready...

[INFO] Clear old IP address in known_hosts file that might interfere with the SSH connection...

# Host 10.28.5.177 found: line 1

/root/.ssh/known_hosts updated.

Original contents retained as /root/.ssh/known_hosts.old

[INFO] Executing 3CX Setup Script...

Automatisierte Einrichtung und Übergabe

Sobald die IP-Adresse erkannt wurde, bereinigt das Skript automatisch Ihre Proxmox-Datei „known_hosts“, um SSH-Konflikte zu vermeiden. Anschließend kopiert es die Sicherungsdatei (falls vorhanden) sicher und führt das Installationsskript „3cx-setup.sh“ remote aus.

Nach Abschluss des Vorgangs wird ein Erfolgsbanner mit der Zusammenfassung der VM angezeigt.

Setup erfolgreich

Hinweise nach der Bereitstellung

Je nach gewähltem PBX_INSTALLATION_MODE variieren die letzten Schritte:

  • Wizard Mode: Das Skript fragt die neu erstellte VM so lange ab, bis der 3CX Web Wizard reagiert. Sobald dies abgeschlossen ist, rufen Sie http://<VM_IP>:5015 in Ihrem Browser auf, um die Einrichtung abzuschließen.
  • Manual Mode: Die Telefonanlage wird im Hintergrund mithilfe der eingefügten setupconfig.xml-Datei installiert und kann optional aus der bereitgestellten Sicherungsdatei wiederhergestellt werden. Es ist keine weitere Interaktion mit dem Installationsassistenten erforderlich.

Hinweis: Die Bereitstellungsprotokolle befinden sich im Konfigurationsverzeichnis. Zum Beispiel: ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

Laden Sie Ihre setupconfig.xml-Datei vom 3CX-Portal herunter.

So erhalten Sie eine vorkonfigurierte, minimale setupconfig.xml-Datei direkt vom 3CX-Portal:

  • Melden Sie sich in Ihrem 3CX-Portal-Konto an.

3CX Portal

  • Wählen Sie Ihr Zielsystem aus und klicken Sie auf den Link „Installieren“.

Welche 3CX

  • Wählen Sie die Optionen für die Installation lokal aus und klicken Sie auf die Schaltfläche „Weiter“.

Nebenstellen

  • Wählen Sie die Anzahl der Ziffern für die Nebenstellen Ihres Systems aus und klicken Sie auf die Schaltfläche „Weiter“.

Einstellungen

  • Wählen Sie Ihre regionalen Systemeinstellungen aus und klicken Sie auf die Schaltfläche „Weiter“.

Plattform

  • Wählen Sie auf der letzten Seite die Linux-Plattform aus.
  • Klicken Sie auf den Download-Link, um eine SetupConfig.xml-Datei herunterzuladen.
  • Benennen Sie die heruntergeladene Datei SetupConfig.xml in setupconfig.xml um – die Installationsskripte unterscheiden zwischen Groß- und Kleinschreibung.
  • Kopieren Sie die Datei setupconfig.xml auf Ihren Proxmox-Rechner nach ~/3cx-proxmox/deployments/pbx01/setupconfig.xml

Letztes Update

Dieses Dokument wurde zuletzt am 29. Mai 2026 aktualisiert.

https://www.3cx.de/docs/proxmox-autodeployment/