3CX Automated Proxmox Deployment Guide

Panoramica

Questa guida illustra l'implementazione automatizzata di una macchina virtuale 3CX su Proxmox VE. Utilizzando immagini cloud generiche Debian e Cloud-Init, questo script provvede all'allocazione delle risorse di calcolo, gestisce la configurazione di rete tramite DHCP, esegue gli script di installazione necessari e, facoltativamente, può ripristinare in modo silenzioso un backup 3CX.

Prerequisiti

Prima di eseguire lo script di distribuzione, assicurarsi che siano soddisfatti i seguenti prerequisiti:

  • Andare su Datacenter > Storage.
  • Selezionare locale e cliccare su Modifica
  • Nel menu a tendina Contenuto, assicurarsi che le opzioni Snippet e Immagine disco siano selezionate.

  • Accesso root: È necessario aver effettuato l'accesso al nodo Proxmox come root.
  • Chiavi SSH: Deve esistere una coppia di chiavi SSH sull'host Proxmox (ad es., /root/.ssh/id_rsa).
  • Accesso a Internet: Il nodo Proxmox deve essere in grado di raggiungere cloud.debian.org per scaricare l'immagine di base.
  • Riserva DHCP: La rete di destinazione deve disporre di un server DHCP con un IP riservato mappato all'indirizzo MAC definito nella configurazione.

Nota: L'esempio sopra riportato illustra una prenotazione DHCP in un ambiente WatchGuard. L'interfaccia esatta e i passaggi necessari per configurare un collegamento statico MAC-IP variano a seconda dell'apparecchiatura di rete specifica (ad esempio, pfSense, UniFi, FortiGate o Windows Server). Il requisito fondamentale rimane lo stesso: questo indirizzo MAC statico univoco sarà associato in modo permanente a questo indirizzo IP riservato sulla rete e verrà utilizzato nel file.env come descritto di seguito nella sezione Implementazione del sistema telefonico 3CX.

Scarica gli strumenti di installazione di 3CX per Proxmox

  • Accedere tramite SSH (o tramite l'interfaccia web di gestione) come utente root all'host Proxmox
  • Andare alla cartella home e scarica gli strumenti di installazione di 3CX:

cd ~

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

tar -zxvf 3cx-proxmox.tar.gz

Installazione del sistema telefonico 3CX

Preparare la cartella di installazione

  • Creare una cartella dedicata al nuovo PBX (in questo esempio ~/3cx-proxmox/deployments/pbx01) e copiare il modello di ambiente:

cd ~/3cx-proxmox

cp -r deployment-template/ deployments/pbx01

Nota: Se si esegue un ripristino in modalità silenziosa, è necessario copiare anche i file setupconfig.xml e 3cx-backup.zip in questa cartella.

Configura il tuo file .ENV

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

Presta attenzione a quanto segue:

  • Impostare PBX_INSTALLATION_MODE su "manual" (impostazione predefinita):
  • Opzione 1: crea un file ~/3cx-proxmox/deployments/pbx01/setupconfig.xml valido
  • Opzione 2: in alternativa, è possibile ottenere un file setupconfig.xml già preparato con una configurazione minima valida dal portale 3CX
  • Se si sta eseguendo un ripristino. Impostare BACKUP_FILEsul nome del file di backup (all'interno di ~/3cx-proxmox/deployments/pbx01)
  • Impostare PBX_INSTALLATION_MODE su “wizard” per avviare la configurazione dell'interfaccia utente web
  • Impostare VMID su un ID VM Proxmox univoco disponibile
  • é possibile controllare gli ID VM attualmente in uso dalla shell Proxmox con qm list
  • Impostare i valori appropriati (alcuni suggerimenti qui: Requisiti hardware) per la propria istanza 3CX per:
  • DISK_GB (default 40)
  • CORES (default 2)
  • SOCKETS (default 1)
  • MEMORY_MB (default 2048)
  • Impostare MAC_ADDRESS sul valore specificato nella fase dei prerequisiti sopra descritta
  • (facoltativo) impostare VLAN_TAG (impostazione predefinita vuota)
  • Impostare le variabili relative alla versione 3CX desiderata; per l'ultima versione 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
  • (facoltativo) impostare i percorsi SSH_PUBLIC_KEY_FILE e SSH_PRIVATE_KEY_FILE se hai creato chiavi personalizzate per proteggere le comunicazioni tra il tuo host Proxmox e gli ospiti

Puoi leggere ulteriori informazioni su come distribuire 3CX e configurare le impostazioni tramite setupconfig.xml.

Struttura delle directory del progetto

Ecco come dovrebbe presentarsi la struttura delle directory:

Esegui lo script di distribuzione

Esegui lo script principale, indicando il percorso del file di configurazione specifico tramite l'opzione --config (o -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%)

Monitorare l'implementazione

Lo script fornisce un feedback in tempo reale sul terminale. In particolare:

  • Scarica l'immagine cloud di Debian (se non è presente nella cache).
  • Inserisce dinamicamente gli script e le variabili dell'utente in un unico snippet Cloud-Init.
  • Provvede all'allocazione delle risorse di calcolo e dell'interfaccia di rete della VM.
  • Avvia la VM e attende che l'agente guest QEMU segnali l'indirizzo IP DHCP assegnato.

[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...

Configurazione automatica e passaggio di consegne

Una volta rilevato l'indirizzo IP, lo script pulisce automaticamente il file `known_hosts` di Proxmox per evitare conflitti SSH. Successivamente, copia in modo sicuro il file di backup (se presente) ed esegue in remoto lo script di installazione `3cx-setup.sh`.

Al termine dell'operazione, verrà visualizzato un messaggio di conferma con il riepilogo della macchina virtuale.

Note successive all'installazione

A seconda della modalità PBX_INSTALLATION_MODE selezionata, le fasi finali varieranno::

  • Modalità guidata: Lo script effettuerà un polling sulla macchina virtuale appena creata fino a quando la procedura guidata web di 3CX non diventerà operativa. Una volta completata l'operazione, accedere a http://<VM_IP>:5015 nel browser per completare la configurazione.
  • Modalità manuale: Il PBX verrà installato in modo silenzioso utilizzando il file setupconfig.xml inserito e, facoltativamente, ripristinerà i dati dal file di backup fornito. Non è richiesta alcuna ulteriore interazione con la procedura guidata.

Nota: I log di distribuzione si trovano nella directory di configurazione. Ad esempio: ~/3cx-proxmox/deployments/pbx01/vm-300-deployment-notes.txt

Scaricare il file setupconfig.xml dal portale 3CX

Per scaricare un file setupconfig.xml minimale e preconfigurato direttamente dal portale 3CX:

  • Accefere al tuo account sul portale 3CX

  • Indicare il sistema di destinazione e clicca sul link Installa

  • Selezionare le opzioni On-Premise e clicca sul pulsante Avanti

  • Selezionare il numero di cifre per gli interni del tuo sistema e clicca sul pulsante Avanti

  • Selezionare le impostazioni regionali per il tuo sistema e clicca sul pulsante Avanti

  • Nell'ultima pagina, selezionare la piattaforma Linux
  • Cliccare sul link Download per scaricare il file SetupConfig.xml
  • Rinominare il file SetupConfig.xml scaricato in setupconfig.xml: gli script di installazione distinguono tra maiuscole e minuscole
  • Copiare il file setupconfig.xml sulla tua macchina Proxmox nella directory ~/3cx-proxmox/deployments/pbx01/setupconfig.xml

Ultimo aggiornamento

Questo documento è stato aggiornato il 2 maggio 2026

https://www.3cx.it/doc/proxmox-autodeployment/